OpenAgentPack Kit
组件通用

MessageList 消息列表

排列多条消息,提供滚动容器、自动跟随、空态与虚拟滚动

MessageList 将 ChatMessage[] 渲染为可滚动的消息列表;单条消息由 Message 承担。父容器需提供有界高度(flex 布局配合 min-h-0)。

import { MessageList } from "@openagentpack/kit-chat-ui";

copy-in 接入(与 Message 共用条目,复制后 import 改为项目内路径):

pnpm kit:add message

交给 coding agent 接入时使用 kit-components Skill;主题与渲染依赖见 组件总览。

何时使用

  • 渲染完整对话流:传入 useChat().messages,接入见 useChat。
  • 只展示单条消息用 Message;带输入框用 Chat;侧栏会话目录用 SessionSidebar。

代码演示

预览使用本地消息数据;每个演示的面板内可查看源码与接入命令。

基本用法

自动跟随与回到底部按钮;向上阅读后再追加,位置保持不变。

MessageList(消息排列与滚动)

回合等待与审批卡

pending 等待指示与 approvals 审批卡互斥;审批的查询与提交见 useChat。

MessageList(回合等待与审批卡)

回合锚点栏

右缘回合刻度:悬停显示摘要 tooltip,点击跳到对应回合(只滚动本列表容器);不足两个回合 不渲染,小于 768px 隐藏。

MessageList(回合锚点栏)

自定义滚动容器单独使用时,复制锚点栏组件(items 与跳转行为由调用方提供):

pnpm kit:add message-anchor-rail
import { MessageAnchorRail } from "@openagentpack/kit-chat-ui";
import { useState } from "react";

export function ConversationAnchors() {
  const [active, setActive] = useState(0);
  return (
    <div className="relative h-72">
      <MessageAnchorRail
        items={[
          { label: "Summarize the report", summary: "Key findings: latency dropped 40% after batching." },
          { label: "Translate the conclusions", summary: "Ran 2 tool calls." },
        ]}
        activeIndex={active}
        onSelect={setActive}
      />
    </div>
  );
}

虚拟滚动

超过 24 条自动启用虚拟滚动:数据层仍传全量 messages(宿主不需要分页);virtualize={false} 可 强制整体渲染。

MessageList(虚拟滚动)

会话加载骨架屏

历史回放尚未就绪(消息为空且未 connected)时,经 empty 插槽展示骨架。

MessageList(会话加载骨架屏)

单独复制:

pnpm kit:add message-skeleton

API

MessageList

属性说明类型默认值
messages必填,按展示顺序排列的消息;每条消息使用业务 id 作为 keyChatMessage[]—
variant消息布局;工作区样式将阅读内容居中,并传给内部 Message"default" | "workspace""default"
empty消息为空时显示的内容ReactNode—
autoScroll自动跟随新增消息与流式内容;用户上滚阅读历史时暂停跟随booleantrue
scrollKey逻辑会话标识;值变化时重置跟随状态,使新会话恢复滚底string | null—
active线程视图保持挂载但隐藏时设 false,暂停滚动副作用;再次显示恢复阅读位置booleantrue
historyCursor更早一页成功加载后变化的游标;即使消息合并进同一 Turn,仍可补偿高度保留阅读锚点string | null—
pending回合执行中但助手尚未返回首帧时,在列表末尾常驻「生成中…」指示booleanfalse
pendingLabel覆盖 pending 指示文案(如发送请求在途时的「发送中…」)string—
approvals当前待审批卡;内嵌到列表末尾,存在时由调用方抑制 pending 指示ReactNode—
onArtifactDownload传给每个 Message 的文件下载回调(fileId: string) => void—
onArtifactOpen传给每个 Message 的文件预览回调(fileId: string, contentType?: string) => void—
onCopy传给每个 Message 的回答复制能力;失败时抛出异常(text: string) => void | Promise<void>浏览器剪贴板
multiAgent主流内子 Agent 卡片的实时状态与历史查询来源;省略时不显示子 Agent 分片ChatMultiAgent—
skills当前 Agent 的技能名,传给各条 Message 用于还原用户气泡中的技能 chipstring[]—
anchorRail在列表右缘显示回合锚点栏(Qoder 形态),见回合锚点栏booleanfalse
virtualize长列表虚拟滚动开关(见虚拟滚动);false 时无论消息数都整体渲染booleantrue
className添加到列表滚动容器的 Tailwind 工具类string—

组件只消费展示模型与回调,不解析 Provider SSE,也不发送请求;messages 通常来自 useChat 的 chat.messages。自动跟随只设置自身 scrollTop,scrollKey 变化时重置跟随状态(通常传当前 sessionId)。

语义结构

区域当前结构与交互
滚动容器组件内部 section 承载滚动;自动跟随只设置自身 scrollTop,不使用 scrollIntoView
消息行每条消息渲染为 Message,沿用业务 id 与 core 提供的稳定分片 id
空态empty 插槽原样渲染在列表位置;骨架屏经该插槽接入
回到底部离开底部时出现的圆形按钮,键盘可聚焦;prefers-reduced-motion 下直接定位
回合锚点栏列表右缘刻度列,悬停或键盘聚焦显示 tooltip;点击只滚动本列表容器
底部渐隐workspace 布局贴底淡出层,装饰层 aria-hidden、不响应指针

主题变量(Design Token)

引入 @openagentpack/kit-chat-ui/theme.css 后使用以下冻结 token。下表列出亮色值, 暗色由 data-kit-theme="dark" 使用对应色板。

Token用途默认主题工作区主题
--kit-chat-widthworkspace 阅读列宽度;宽屏居中,窄屏随可用空间收缩48rem48rem
--kit-bgworkspace 底部渐隐层的底色#ffffff#ffffff
--kit-blur-overlay底部渐隐层的最大模糊半径8px8px
--kit-skeleton骨架屏消息块底色#ececec#ececec
--kit-skeleton-card骨架屏助手卡面#f7f7f7#f7f7f7
--kit-skeleton-bar骨架屏文字条#e4e4e4#e4e4e4
--kit-skeleton-sheen骨架屏扫光高光rgb(255 255 255 / 70%)同左

骨架扫光消费 --kit-animate-skeleton,prefers-reduced-motion 下静止。更多主题配置见 组件总览。

本页目录