Thread

Thread 是 aui-components 的核心组件。它使用 assistant-ui 的 ThreadPrimitive 原语，预组装了菜单消息（AssistantMessage + UserMessage）、输入框（Composer）、滚动控制、附件、引用等功能。

引入

import { Thread } from "aui-components";

基本用法

import { AssistantRuntimeProvider, useChatRuntime } from "@assistant-ui/react";
import { Thread } from "aui-components";

export function ChatPage() {
  const runtime = useChatRuntime({
    api: "/api/chat",
  });

  return (
    <AssistantRuntimeProvider aui={runtime.aui} runtime={runtime}>
      <div className="h-screen">
        <Thread />
      </div>
    </AssistantRuntimeProvider>
  );
}

Props

属性	类型	默认值	说明
`components`	`enum`	`{}`	可选的自定义组件覆盖，用于替换默认的消息渲染
`isHistoryThread`	`enum`	—	是否正在加载已有 thread 的历史记录（/thread/[id] 路由）
`isHistoryThreadLoaded`	`enum`	`true`	历史 thread 是否已加载完成

ThreadProps

export type ThreadProps = {
  /** 自定义子组件覆盖 */
  components?: ThreadComponents | undefined;
  /** 是否正在加载历史对话（/thread/[id] 路由场景） */
  isHistoryThread?: boolean | undefined;
  /** 历史对话是否已加载完成 */
  isHistoryThreadLoaded?: boolean | undefined;
};

ThreadComponents

通过 components prop 可以覆盖 Thread 内部的默认组件：

export type ThreadComponents = {
  /** 覆盖整个 AssistantMessage 渲染 */
  AssistantMessage?: ComponentType | undefined;
  /** 覆盖欢迎界面 */
  Welcome?: ComponentType | undefined;
  /** 覆盖工具调用的通用回退 UI */
  ToolFallback?: ToolCallMessagePartComponent | undefined;
  /** 覆盖工具调用分组容器 */
  ToolGroup?:
    ComponentType<PropsWithChildren<{ group: ThreadGroupPart }>> | undefined;
  /** 覆盖思维链分组容器 */
  ReasoningGroup?:
    ComponentType<PropsWithChildren<{ group: ThreadGroupPart }>> | undefined;
};

覆盖示例

// 自定义欢迎界面
function CustomWelcome() {
  return <h1>Welcome to AI Chat!</h1>;
}

// 自定义工具调用分组
function CustomToolGroup({
  children,
  group,
}: {
  children: React.ReactNode;
  group: ThreadGroupPart;
}) {
  return (
    <div className="rounded-lg border border-blue-200 p-3">
      <p>Tools used: {group.indices.length}</p>
      {children}
    </div>
  );
}

<Thread
  components={{
    Welcome: CustomWelcome,
    ToolGroup: CustomToolGroup,
  }}
/>;

isHistoryThread

当从 /thread/[id] 路由加载历史对话时，设置 isHistoryThread 和 isHistoryThreadLoaded 可以控制加载状态：

<Thread isHistoryThread={true} isHistoryThreadLoaded={messages.length > 0} />

加载中：显示 Loading 指示器 + 输入框，隐藏消息区域
加载完成：正常渲染消息列表

内部结构

Thread 由以下子组件组成，它们已在源码中预配置好：

布局结构

ThreadRoot — 最外层容器，包含 Viewport + Footer
- ThreadPrimitive.Viewport — 可滚动视口
  - Welcome — 空状态欢迎界面
  - Messages — 消息列表
  - ViewportFooter — 固定在底部的区域
    - ScrollToBottom — 滚动到底部按钮
    - FollowupSuggestions — 追问建议
    - Composer — 输入框
    - Suggestions — 初始建议列表
- SelectionToolbar — 文本选中工具栏

AssistantMessage

<MessagePrimitive.GroupedParts groupBy={groupPartByType(...)}>
  {({ part, children }) => {
    switch (part.type) {
      case "group-chainOfThought": // 思维分组包装
      case "group-tool":           // 工具分组 + 折叠
      case "group-reasoning":      // 思维链展示
      case "text":                 // Markdown 渲染
      case "reasoning":            // 独立推理块
      case "tool-call":            // 工具调用回退或自定义 UI
      case "image":                // 图片渲染
      case "indicator":            // 加载指示器
    }
  }}
</MessagePrimitive.GroupedParts>

UserMessage

用户附件展示（UserMessageAttachments）
引用块渲染（QuoteBlock）
消息内容（MessagePrimitive.Parts）
编辑按钮（ActionBarPrimitive.Edit）

Composer

附件拖拽区域（AttachmentDropzone）
附件预览（ComposerAttachments）
引用预览（ComposerQuotePreview）
文本输入（Input）
语音输入（Dictate）
发送 / 取消按钮
附件添加按钮（ComposerAddAttachment）

完整示例

export function CustomThread() {
  const runtime = useChatRuntime({
    api: "/api/chat",
    // 配合 LangGraph
    // transport: new DefaultChatTransport(...),
  });

  return (
    <AssistantRuntimeProvider aui={runtime.aui} runtime={runtime}>
      <div className="mx-auto h-screen max-w-3xl">
        <Thread
          components={{
            Welcome: () => (
              <div className="flex flex-col items-center py-12">
                <h1 className="text-2xl font-bold">My AI Assistant</h1>
                <p className="text-muted-foreground mt-2">
                  How can I help you today?
                </p>
              </div>
            ),
          }}
        />
      </div>
    </AssistantRuntimeProvider>
  );
}