OpenMax
免费试用

群管理

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

群管理

group-management-create demo

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

群信息面板

group-management-info-panel demo

演示截图。演示跑在内存里的示例 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 或空格开始编辑。
  • 退群、解散、移除成员的确认框是标准对话框。