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。
代码演示
预览使用本地消息数据;每个演示的面板内可查看源码与接入命令。
基本用法
自动跟随与回到底部按钮;向上阅读后再追加,位置保持不变。
回合等待与审批卡
pending 等待指示与 approvals 审批卡互斥;审批的查询与提交见 useChat。
回合锚点栏
右缘回合刻度:悬停显示摘要 tooltip,点击跳到对应回合(只滚动本列表容器);不足两个回合 不渲染,小于 768px 隐藏。
自定义滚动容器单独使用时,复制锚点栏组件(items 与跳转行为由调用方提供):
pnpm kit:add message-anchor-railimport { 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} 可
强制整体渲染。
会话加载骨架屏
历史回放尚未就绪(消息为空且未 connected)时,经 empty 插槽展示骨架。
单独复制:
pnpm kit:add message-skeletonAPI
MessageList
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
messages | 必填,按展示顺序排列的消息;每条消息使用业务 id 作为 key | ChatMessage[] | — |
variant | 消息布局;工作区样式将阅读内容居中,并传给内部 Message | "default" | "workspace" | "default" |
empty | 消息为空时显示的内容 | ReactNode | — |
autoScroll | 自动跟随新增消息与流式内容;用户上滚阅读历史时暂停跟随 | boolean | true |
scrollKey | 逻辑会话标识;值变化时重置跟随状态,使新会话恢复滚底 | string | null | — |
active | 线程视图保持挂载但隐藏时设 false,暂停滚动副作用;再次显示恢复阅读位置 | boolean | true |
historyCursor | 更早一页成功加载后变化的游标;即使消息合并进同一 Turn,仍可补偿高度保留阅读锚点 | string | null | — |
pending | 回合执行中但助手尚未返回首帧时,在列表末尾常驻「生成中…」指示 | boolean | false |
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 用于还原用户气泡中的技能 chip | string[] | — |
anchorRail | 在列表右缘显示回合锚点栏(Qoder 形态),见回合锚点栏 | boolean | false |
virtualize | 长列表虚拟滚动开关(见虚拟滚动);false 时无论消息数都整体渲染 | boolean | true |
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-width | workspace 阅读列宽度;宽屏居中,窄屏随可用空间收缩 | 48rem | 48rem |
--kit-bg | workspace 底部渐隐层的底色 | #ffffff | #ffffff |
--kit-blur-overlay | 底部渐隐层的最大模糊半径 | 8px | 8px |
--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 下静止。更多主题配置见
组件总览。