OpenMax
免费试用

会话列表

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

会话列表

conversation-list-basic demo

演示截图。演示跑在内存里的示例 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()}
    />
  );
}

「新建群聊」按钮

conversation-list-create-group demo

演示截图。演示跑在内存里的示例 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。