群管理
让用户建群、修改群名称和描述、管理群成员。
群管理

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。
演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): group-management-create.tsx
"use client";
import { CreateGroupModal } from "@openmaxai/chat/group-management";
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 { Button, useDemoData, useDemoHost, useDemoNotify } from "./kit";
export default function CreateGroupDemo() {
const host = useDemoHost(); // includes `groupManagement.createGroup`
const { lang } = useDemoData();
const notify = useDemoNotify();
const [open, setOpen] = useState(false);
return (
<ChatHostProvider host={host}>
<div className="flex h-full items-center justify-center bg-background text-foreground">
<Button onClick={() => setOpen(true)}>
{lang === "zh" ? "新建群聊" : "New group"}
</Button>
</div>
<CreateGroupModal
open={open}
onClose={() => setOpen(false)}
onCreated={(conversationId) =>
notify("success", `onCreated("${conversationId}")`)
}
/>
</ChatHostProvider>
);
}
演示代码中的 useDemoHost() 是内存宿主,接入真实宿主的写法见概览。
本页讲的是 @openmaxai/chat 的底层组件 CreateGroupModal、ChatInfoPanel、AddMemberContainer。它们不带样式根:SDK 样式表只作用在 SDK 组件自带的 .omx-chat 组件根之内,ChatRoot 本身不是样式作用域,所以照抄下面的示例渲染出来没有样式。要用它们,把它们放进 ChatRoot,再在外面包一层带 omx-chat 类的元素(深色时另加 omx-dark,并给 ChatRoot 传 colorScheme="dark"),或者自己出样式。只包一层不够:对话框、菜单、浮层不在 ChatRoot 里时落到 document.body,在你包的那层之外,拿不到样式;在 ChatRoot 里时它们落在 ChatRoot 带 omx-chat 类的落点上。用 createChatHost 的宿主时改用 SDK 组件:建群入口在 CwsConversationList 里,群信息面板是 CwsGroupInfoPanel,见下文。
何时使用
CreateGroupModal:新建群聊弹窗,填名称、描述,从通讯录选成员。ChatInfoPanel:群信息侧栏(容器窄时全屏),改名称和描述、管理成员、退群或解散,宿主实现agentGroupPolicy时另画「AGENT 群聊设置」(群里每个 Agent 的回复模式)。AddMemberContainer:面板里的添加成员弹窗,也可单独用。
直接用这几个组件时它们不会被自动挂载:建群按钮作为 createGroupAction 传给 ConversationList,面板由 ChatHeader 的 onToggleInfoPanel 打开。
用 Chat SDK(@openmaxai/chat-sdk/react)时入口是 SDK 画的:宿主有 groupManagement 时 CwsConversationList 自带「新建群聊」,ConversationHeader 在群聊里画信息按钮(没有 groupManagement 时传了 onToggleInfoPanel 也不画),面板用 CwsGroupInfoPanel,它自己取成员、按端口给按钮;浮窗、停靠列与小屏抽屉里已内建。自己挂 ChatInfoPanel 的 SDK 接入方改用 <CwsGroupInfoPanel>。 CwsGroupInfoPanel 本身已弃用:ChatProvider 打开 infoSidebar 后,主区与浮窗、停靠标签里都由会话信息侧栏(ConversationInfoSidebar)取代它。
示例
建群
sidebar.tsx
import { ConversationList } from "@openmaxai/chat/conversation-list";
import { CreateGroupModal } from "@openmaxai/chat/group-management";
const [creating, setCreating] = useState(false);
<ConversationList
/* … */
createGroupAction={
<button type="button" onClick={() => setCreating(true)}>新建群聊</button>
}
/>
<CreateGroupModal
open={creating}
onClose={() => setCreating(false)}
onCreated={(conversationId) => setSelectedId(conversationId)}
/>
群信息面板

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。
演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): group-management-info-panel.tsx
"use client";
import { ChatInfoPanel } from "@openmaxai/chat/group-management";
import { ChatHostProvider } from "@openmaxai/chat/host";
// 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 {
ME,
useDemoData,
useDemoHost,
useDemoNotify,
useIsCompact,
} from "./kit";
export default function InfoPanelDemo() {
const host = useDemoHost(); // includes `groupManagement` with all four writes
const { conversations, members } = useDemoData();
const notify = useDemoNotify();
const isCompact = useIsCompact();
const group = conversations[0];
return (
<ChatHostProvider host={host}>
<div className="mx-auto flex h-full max-w-sm flex-col bg-background text-foreground">
<ChatInfoPanel
conversation={group}
currentMemberId={ME}
isMobile={isCompact}
participants={members.map((m) => ({
member_id: m.memberId,
kind: m.kind ?? "human",
display_name: m.displayName,
avatar_url: null,
}))}
memberStatus={{
ada: { onlineStatus: "online" },
helper: { onlineStatus: "online" },
}}
onClose={() => notify("info", "onClose()")}
/>
</div>
</ChatHostProvider>
);
}
conversation-pane.tsx
import { ChatInfoPanel } from "@openmaxai/chat/group-management";
{infoOpen && conversation.type === "GROUP" && (
<ChatInfoPanel
conversation={conversation}
participants={participants}
currentMemberId={me.id}
memberStatus={statusByMemberId}
onClose={() => setInfoOpen(false)}
onUpdate={(patch) => updateLocalConversation(conversation.id, patch)}
/>
)}
改名称和描述走宿主的 groupManagement 能力。加人、移人、退群、解散也走它的可选方法(addMembers、removeMembers、leave、dissolve,见宿主能力 · groupManagement):有哪一项面板才画哪个按钮,写完由面板出提示——全部成功说人数,有人没成时说出是谁、为什么(同一原因的人合成一句,名字最多列 3 个),整次失败说失败原因。群主退群时选的继任者作为 newOwnerId 交给 leave。
ChatInfoPanel 另有 onAddMembers / onRemoveMembers / onLeave / onDelete 四个回调,是过渡接口(@deprecated,后续版本移除):给了回调就走回调、不走端口,提示也由你出。新代码不要传它们。
提供这项能力
group-management.ts
import type { ChatGroupManagementPort } from "@openmaxai/chat/host";
export const groupManagement: ChatGroupManagementPort = {
async createGroup({ title, description, memberIds }) {
const room = await api.createRoom({ name: title, members: memberIds, topic: description });
return { conversationId: room.id };
},
updateGroupProfile: (conversationId, { name, description }) =>
api.updateRoom(conversationId, { name, topic: description }),
// 可选:有哪一项,信息面板才画哪个按钮。
addMembers: (conversationId, memberIds) => api.addToRoom(conversationId, memberIds),
removeMembers: (conversationId, memberIds) => api.removeFromRoom(conversationId, memberIds),
leave: (conversationId, options) => api.leaveRoom(conversationId, options?.newOwnerId),
dissolve: (conversationId) => api.deleteRoom(conversationId),
};
updateGroupProfile 每次只带一个字段(名称和描述分开保存)。自己写宿主时,改名后要刷新会话列表,新名字才会出现;用 createChatHost 时由 SDK 刷新(建群、改资料后会话列表重取,加人、移人后那条会话的成员表重取),见适配器接口 · groupManagement。
建群失败时弹窗不关,在提交按钮上方显示原因。createGroup 请求失败时抛 ChatSdkError:有 message 就显示它,没有就按 kind 显示包里的文案,再没有显示「创建群聊失败,请重试」。抛别的异常会被当成代码错误:打一条 console.error 后照原样抛出,不显示在弹窗里。
API
CreateGroupModal
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
open |
boolean |
必填 | 是否打开 |
onClose |
() => void |
必填 | 弹窗关闭 |
onCreated |
(conversationId: string) => void |
— | 建群成功,参数是新会话 id |
ChatInfoPanel
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
conversation |
ChatConversation |
必填 | 这个群 |
onClose |
() => void |
必填 | 关闭面板 |
participants |
ChatConversationParticipant[] |
[] |
成员列表,由你加载 |
currentMemberId |
string |
— | 判断是否群主,并把自己排除出继任者候选 |
onUpdate |
(updates: Partial<ChatConversation>) => void |
— | 名称或描述保存成功后的本地补丁 |
onAddMembers |
(memberIds: string[]) => void |
— | 已废弃(过渡)。给了就不走端口的 addMembers |
onRemoveMembers |
(memberIds: string[]) => Promise<void> | void |
— | 已废弃(过渡)。给了就不走端口的 removeMembers |
onLeave |
(newOwnerId?: string) => Promise<void> | void |
— | 已废弃(过渡)。给了就不走端口的 leave |
onDelete |
() => Promise<void> | void |
— | 已废弃(过渡)。给了就不走端口的 dissolve |
ownerId |
string |
conversation.owner_id |
群主的成员 id(如按成员表的 role 判出的),不必改写会话对象 |
cover |
boolean |
false |
盖满最近的定位祖先(不盖宿主整页);嵌在别人页面里窄屏时用 |
memberStatus |
Record<string, ChatMemberStatus> |
— | memberId → { onlineStatus?, billingSuspended?, creditCapReached? } |
overlay |
boolean |
false |
不是全屏浮层时,浮在聊天区右侧,不占一栏 |
每个人的会话内角色从宿主的 memberStore 读(这个群成员表每行的 role)。读到了,改名称与描述、添加、移除成员、解散按 can() 画(对齐服务端);成员表没取过、或缺你自己 / 某个成员时,那一格按兜底规则:人人可改名称描述、可添加,owner_id 那个人可移除(除自己外的全部成员)、可解散。不是群的会话(如 Agent 协作)名称与描述只读,与角色无关。
面板按所在容器的宽度选择形态:容器窄于 768 px 时是盖住会话区的全屏浮层,否则是侧栏。见响应式。
AddMemberContainer
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
open |
boolean |
必填 | 是否打开 |
existingParticipants |
ChatConversationParticipant[] |
必填 | 现有成员,不进候选 |
onClose |
() => void |
必填 | 弹窗关闭 |
onAdd |
(memberIds: string[]) => void |
必填 | 选中的成员 id |
候选来自通讯录搜索,排除现有成员和停用账号。
依赖的能力
| 能力 | 缺了会怎样 |
|---|---|
groupManagement(createGroup、updateGroupProfile) |
CreateGroupModal 和 ChatInfoPanel 渲染时抛出指名错误。不做群管理就别渲染它们,也别传 createGroupAction |
identity |
必需;成员选择器的通讯录搜索 |
render |
必需;群描述里的链接和 @ |
agentGroupPolicy |
可选。不实现 ⇒ 面板里没有「AGENT 群聊设置」,其余照常。实现了 ⇒ 普通群(不是 Agent 协作)里列出群内每个 Agent:canManageGroupPolicy 为 true 的给「智能回复 / 仅回复 @」切换,false 的只读显示当前模式,undefined(判不出)的那一行不画;群聊范围挡住本群时给出原因与「加入群聊白名单」。openAgentSettings 不给 ⇒ 不画「去 Agent 设置调整」入口。见 agentGroupPolicy |
以下 props 漏传不报错,只是静默失效:
| Prop | 不传时 |
|---|---|
groupManagement 的 addMembers / removeMembers / leave / dissolve(且没给对应回调) |
没有那个按钮 |
memberStatus |
所有成员显示离线 |
无障碍
CreateGroupModal是带标题的对话框;名称字段在碰过或提交后仍不合法时带aria-invalid并显示错误。- 名称和描述编辑区是带标签的
role="textbox";描述非编辑态是可聚焦的role="button",Enter或空格开始编辑。 - 退群、解散、移除成员的确认框是标准对话框。
