会话列表
展示用户的会话,带未读数、草稿、搜索、置顶和隐藏。
会话列表

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。
演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): conversation-list-basic.tsx
"use client";
import { ConversationList } from "@openmaxai/chat/conversation-list";
import { ChatHostProvider } from "@openmaxai/chat/host";
import { useState } from "react";
// Docs helpers: useDemoHost() is an in-memory host with sample data (no backend).
// In your app, pass the host from createChatHost() or your own ChatHost instead.
import { useDemoData, useDemoHost } from "./kit";
export default function ConversationListDemo() {
const host = useDemoHost();
const { conversations } = useDemoData();
const [selectedId, setSelectedId] = useState<string | null>("launch");
return (
<ChatHostProvider host={host}>
<div className="flex h-full justify-center bg-background text-foreground">
<ConversationList
conversations={conversations}
selectedId={selectedId}
onSelect={(conversation) => setSelectedId(conversation.id)}
onDeselect={() => setSelectedId(null)}
/>
</div>
</ChatHostProvider>
);
}
演示代码中的 useDemoHost() 是内存宿主,接入真实宿主的写法见概览。
本页讲的是 @openmaxai/chat 的底层组件 ConversationList。它们不带样式根:SDK 样式表只作用在 SDK 组件自带的 .omx-chat 组件根之内,ChatRoot 本身不是样式作用域,所以照抄下面的示例渲染出来没有样式。要用它们,把它们放进 ChatRoot,再在外面包一层带 omx-chat 类的元素(深色时另加 omx-dark,并给 ChatRoot 传 colorScheme="dark"),或者自己出样式。只包一层不够:对话框、菜单、浮层不在 ChatRoot 里时落到 document.body,在你包的那层之外,拿不到样式;在 ChatRoot 里时它们落在 ChatRoot 带 omx-chat 类的落点上。用 createChatHost 的宿主时改用 SDK 组件 CwsConversationList,写法见快速开始。
何时使用
- 聊天界面左栏:置顶宫格、会话行(头像、名称、最后一条消息、时间、未读、
[草稿])、置顶 / 静音 / 隐藏操作。 - 搜索框同时搜会话和组织通讯录;选中通讯录里的 Agent 会直接打开单聊。
- 列表不自己拉数据,会话由你传入。
示例
基础用法
sidebar.tsx
import { ConversationList } from "@openmaxai/chat/conversation-list";
export function Sidebar({ conversations, selectedId, onSelect }: SidebarProps) {
return (
<ConversationList
conversations={conversations}
selectedId={selectedId}
onSelect={(c) => onSelect(c.id)}
onSelectConversationId={onSelect}
onDeselect={() => onSelect(null)}
/>
);
}
从通讯录搜索打开单聊后回调 onSelectConversationId(只拿得到新会话 id);选中的会话被隐藏时回调 onDeselect。
置顶、取消置顶、隐藏、取消隐藏失败时,列表保持原样,经宿主的 attention.notify("error", …) 提示「置顶失败」「取消置顶失败」「隐藏会话失败」或「取消隐藏失败」;onDeselect 只在隐藏成功后回调。
宿主的 conversations 有 setMuted 时,会话行(鼠标悬停时的操作图标、触屏左滑)和置顶宫格(触屏长按出的面板)都给「静音」或「取消静音」,旁观的会话不给。静音失败时列表保持原样,提示「静音失败」或「取消静音失败」;成功后列表重取,静音标识跟着变。
搭配 OpenMax SDK
useChatSdkConversationList() 负责拉取、分页和实时刷新(含断线重连),需在 <ChatProvider> 下配合 createChatHost() 创建的宿主使用。
sidebar.tsx
import { ConversationList } from "@openmaxai/chat/conversation-list";
import { useChatSdkConversationList } from "@openmaxai/chat-sdk/react";
export function Sidebar({ selectedId, onSelect }: SidebarProps) {
const { conversations, isLoading, isLoadingError, hasNextPage, fetchNextPage, refetch } =
useChatSdkConversationList();
return (
<ConversationList
conversations={conversations}
selectedId={selectedId}
onSelect={(c) => onSelect(c.id)}
onSelectConversationId={onSelect}
isLoading={isLoading}
loadFailed={isLoadingError}
onRetry={() => void refetch()}
hasNextPage={hasNextPage}
onLoadMore={() => void fetchNextPage()}
/>
);
}
「新建群聊」按钮

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。
演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): conversation-list-create-group.tsx
"use client";
import { ConversationList } from "@openmaxai/chat/conversation-list";
import { CreateGroupModal } from "@openmaxai/chat/group-management";
import { ChatHostProvider } from "@openmaxai/chat/host";
import { Plus } from "lucide-react";
import { useState } from "react";
// Docs helpers: useDemoHost() is an in-memory host with sample data (no backend).
// In your app, pass the host from createChatHost() or your own ChatHost instead.
import { Button, useDemoData, useDemoHost } from "./kit";
export default function ConversationListCreateGroupDemo() {
const host = useDemoHost(); // includes the `groupManagement` capability
const { conversations, lang } = useDemoData();
const [selectedId, setSelectedId] = useState<string | null>("launch");
const [creating, setCreating] = useState(false);
return (
<ChatHostProvider host={host}>
<div className="flex h-full justify-center bg-background text-foreground">
<ConversationList
conversations={conversations}
selectedId={selectedId}
onSelect={(conversation) => setSelectedId(conversation.id)}
onDeselect={() => setSelectedId(null)}
// Rendered next to the search box.
createGroupAction={
<Button
size="icon-sm"
variant="outline"
aria-label={lang === "zh" ? "新建群聊" : "New group"}
onClick={() => setCreating(true)}
>
<Plus />
</Button>
}
/>
</div>
<CreateGroupModal
open={creating}
onClose={() => setCreating(false)}
onCreated={(conversationId) => setSelectedId(conversationId)}
/>
</ChatHostProvider>
);
}
把按钮作为 createGroupAction 传入搜索框右侧插槽,CreateGroupModal 自己渲染:
const [creating, setCreating] = useState(false);
<ConversationList
/* … */
createGroupAction={
<button type="button" onClick={() => setCreating(true)}>新建群聊</button>
}
/>
<CreateGroupModal open={creating} onClose={() => setCreating(false)} onCreated={onSelect} />
可拖宽的列
宽度由你保存,null 为默认宽度(双击把手恢复)。拖动范围是 220 到 560 px,且不超过视口的 40%。
列表的宽度来自 CSS 变量 --chat-list-w:width 为 null 时,用你在祖先元素上设的值,没设就是 clamp(220px, 26vw, 340px)(见主题 · 布局);不为 null 时,这一栏在自己的外壳上设置这个变量,覆盖祖先上的值。
import {
ConversationList,
ResizableConversationListColumn,
} from "@openmaxai/chat/conversation-list";
const [width, setWidth] = useState<number | null>(null);
<ResizableConversationListColumn width={width} onWidthChange={setWidth}>
<ConversationList /* … */ />
</ResizableConversationListColumn>;
API
ConversationList
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
conversations |
ChatConversation[] |
必填 | 要展示的会话 |
selectedId |
string | null |
必填 | 高亮行的 id |
onSelect |
(conv: ChatConversation) => void |
必填 | 点了某一行 |
onSelectConversationId |
(conversationId: string) => void |
— | 从通讯录搜索打开了单聊 |
onDeselect |
() => void |
— | 选中的会话被隐藏 |
hasNextPage |
boolean |
— | 还有更多会话 |
isFetchingNextPage |
boolean |
— | 下一页加载中 |
onLoadMore |
() => void |
— | 滚到底部时调用 |
isLoading |
boolean |
false |
首屏加载中,显示骨架屏而非「暂无对话」 |
loadFailed |
boolean |
false |
第一页取失败、一页都没有:显示「加载失败」而非「暂无对话」。已有行时重取或翻页失败不算 |
onRetry |
() => void |
— | loadFailed 态里的重试按钮,不传则没有按钮 |
memberNames |
Record<string, string> |
— | member_id → 显示名,给你旁观但不参与的会话起名 |
createGroupAction |
ReactNode |
— | 搜索框右侧插槽,不传则为空 |
onDetach |
(conv, drop: ListRowDrop) => void |
— | 一行(含置顶头像)被鼠标或笔拖出列表松手:落在列表外(float,带松手点)或停靠区(dock)。给了且不在窄屏时行才能拖;开窗由你做 |
hiddenInSurfaces |
boolean |
false |
实验性。有会话因为开在浮窗或停靠列里,没放进 conversations。只改空态文字:没有行、也不在搜索时,说会话在浮窗或者右侧栏里,而不是「暂无对话」。它自己不藏任何会话:那些会话要你自己从 conversations 里去掉。搜索时与窄条里不看它 |
compact |
boolean |
false |
实验性。画成 64 px 宽的头像窄条(头像、未读数、@ 角标;会话名在 tooltip 和可读名里,可读名另带未读数)。↑ / ↓ 在头像之间移动,Enter 选中。置顶排最前、后面一条分隔线;不画搜索框、createGroupAction 和置顶宫格。进窄条时清掉搜索词;焦点原在列表里的,交给选中的头像(回到整列时交给搜索框)。窄屏忽略 |
当前用户从宿主的 identity 能力读取,不是 props。排版跟随所在容器的宽度,见响应式。
ResizableConversationListColumn
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
width |
number | null |
必填 | 宽度(px),null 为默认 |
onWidthChange |
(w: number | null) => void |
必填 | 拖动或按键后的新宽度,恢复默认时为 null |
children |
ReactNode |
必填 | ConversationList |
inactive |
boolean |
false |
窄屏(一次一栏)时传 true:外壳退成 display: contents,不写宽度、不出把手。切换它时里面的 ConversationList 不重挂,搜索框里的字和滚动位置都在 |
依赖的能力
| 能力 | 缺了会怎样 |
|---|---|
conversations(list、setPinned、setHidden) |
渲染时抛出指名错误;没有会话列表的应用不要渲染此组件 |
attention |
必需;置顶、静音、隐藏失败时的提示 |
identity |
必需;当前用户和通讯录搜索 |
drafts |
必需;[草稿] 前缀 |
messaging |
必需;从通讯录搜索打开单聊 |
无障碍
- 搜索框为
role="searchbox",有无障碍名称;Escape清空,清空按钮有标签。 - 置顶、取消置顶、静音、取消静音按钮有标签。
- 拖宽把手为
role="separator",带aria-orientation="vertical"、aria-valuenow,可 Tab 聚焦,ArrowLeft/ArrowRight调宽。 - 骨架屏标了
aria-busy。 - 会话行没有键盘操作,选中会话需要鼠标或触摸。
常见问题
我旁观的会话没有名字。
传入 memberNames。
