介绍
GroupSettingState
是一个功能强大的群聊状态管理中心,专门用于管理群聊的各种设置、成员信息和权限控制。它提供了群聊信息管理、成员操作、权限验证、群聊设置等全方位的功能支持,是构建群聊管理界面的核心工具。该 Hook 具备以下特色:
完整的群聊信息管理:群组基本信息、成员列表、权限设置等。
智能权限控制:基于角色的权限验证和操作限制。
丰富的成员操作:添加、删除、设置角色、禁言等成员管理功能。
实时状态同步:自动监听群聊状态变化并更新本地数据。
什么时候使用 GroupSettingState?
当目前的
ChatSetting
组件能力无法满足您的特定需求,或者您希望基于底层数据重新开发一个自定义的群聊设置组件时,可以使用 useGroupSettingState()
组合式函数来获取原始的数据源和相关的操作方法,进而进行灵活的定制和开发。属性列表
群聊状态相关
字段 | 类型 | 描述 |
string | undefined | 群组 ID | |
GroupType | undefined | 群组类型 | |
string | undefined | 群组名称 | |
string | undefined | 群组头像 URL | |
string | undefined | 群组公告 | |
boolean | undefined | 是否免打扰 | |
boolean | undefined | 是否置顶 | |
GroupMember | undefined | 群主信息 | |
GroupMember[] | 管理员列表 | |
GroupMember[] | undefined | 所有成员列表 | |
number | undefined | 当前成员数量 | |
number | undefined | 最大成员数量 | |
string | undefined | 当前用户 ID | |
GroupMemberRole | undefined | 当前用户角色 | |
boolean | undefined | 是否全员禁言 | |
boolean | undefined | 当前用户是否在群内 | |
GroupInviteType | undefined | 邀请加群方式 |
权限工具方法
方法 | 类型 | 描述 |
(permission: GroupPermission, role?: GroupMemberRole, groupType?: GroupType) => boolean | 检查是否具有特定权限 |
业务操作方法
方法 | 类型 | 描述 |
(params?: GetGroupMemberListParams) => Promise<IGroupMember[]> | 获取群成员列表 | |
(params: UpdateGroupProfileParams) => Promise<void> | 更新群组资料 | |
(params: AddGroupMemberParams) => Promise<IAddGroupMemberResult> | 添加群成员 | |
(params: DeleteGroupMemberParams) => Promise<void> | 删除群成员 | |
(params: ChangeGroupOwnerParams) => Promise<void> | 转让群主 | |
(params: SetGroupMemberRoleParams) => Promise<void> | 设置成员角色 | |
(value: boolean) => Promise<void> | 设置群聊置顶【Beta】 | |
(value: boolean) => Promise<void> | 设置群聊免打扰【Beta】 | |
(params: SetGroupMemberMuteTimeParams) => Promise<void> | 设置成员禁言时间 | |
dismissGroup | (groupID?: string) => Promise<void> | 解散群聊 |
quitGroup | (groupID?: string) => Promise<void> | 退出群聊 |
详细字段说明
groupID
类型:string | undefined
描述:当前群聊的唯一标识符。用于所有群聊相关的 API 调用和操作识别。如果为 undefined,则表示当前没有激活的群聊。
groupType
类型:GroupType | undefined
描述:群聊类型枚举,影响群聊的功能特性和权限模型。如果为 undefined,则表示当前没有激活的群聊。
枚举定义:
enum GroupType {WORK,PUBLIC,MEETING,AVCHATROOM,COMMUNITY,}
groupName
类型:string | undefined
描述:群聊的显示名称。可通过 updateGroupProfile 方法修改(需要相应权限)。如果为
undefined
,则表示当前没有激活的群聊。avatar
类型:string | undefined
描述:群聊头像的 URL 地址。可通过 updateGroupProfile方法修改(需要相应权限)。如果为
undefined
,则表示当前没有激活的群聊。notification
类型:string | undefined
描述:群聊公告,通常用于发布重要通知或群规。可通过 updateGroupProfile方法修改(需要相应权限)。如果为
undefined
,则表示当前没有激活的群聊。isMuted
类型:boolean | undefined
描述:当前用户是否对该群聊设置了免打扰。设置后不会收到群聊的推送通知。如果为
undefined
,则表示当前没有激活的群聊。isPinned
类型:boolean | undefined
描述:当前用户是否将该群聊置顶。置顶后群聊会显示在会话列表的顶部。如果为
undefined
,则表示当前没有激活的群聊。groupOwner
类型:GroupMember | undefined
描述:群主的详细信息。如果为
undefined
,则表示当前没有激活的群聊。GroupMember 接口定义:
interface GroupMember {userID: string; // 用户IDnick: string; // 用户昵称avatar: string; // 用户头像URLrole: GroupMemberRole; // 用户角色joinTime: number; // 加入时间戳muteUntil: string; // 禁言截止时间memberCustomField: string; // 成员自定义字段}enum GroupMemberRole {OWNER = 'Owner', // 群主ADMIN = 'Admin', // 群管理COMMON = 'Member', // 群成员}
adminMembers
类型:GroupMember[]
描述:群管理员列表,包含所有具有管理员角色的成员信息。
allMembers
类型:GroupMember[] | undefined
描述:群聊中所有成员的列表,支持分页加载。通过 getGroupMemberList 方法获取和更新。
memberCount
类型:number | undefined
描述:当前成员数量。如果为
undefined
,则表示当前没有激活的群聊。maxMemberCount
类型:number | undefined
描述:群聊最大成员限制。如果为
undefined
,则表示当前没有激活的群聊。currentUserID
类型:string | undefined
描述:当前登录用户(自己)的 userID。如果为
undefined
,则表示当前没有激活的群聊。currentUserRole
类型:GroupMemberRole | undefined
描述:当前登录用户(自己)在群聊中的角色,影响用户的操作权限。如果为
undefined
,则表示当前没有激活的群聊。枚举定义:
enum GroupMemberRole {OWNER = 'OWNER',ADMIN = 'ADMIN',COMMON = 'COMMON'}
isMuteAllMembers
类型:boolean | undefined
描述:是否开启全员禁言。开启后只有群主和管理员可以发言。如果为
undefined
,则表示当前没有激活的群聊。isInGroup
类型:boolean | undefined
描述:当前登录用户(自己)是否还在群聊中。用于处理被踢出群聊等异常情况。如果为
undefined
,则表示当前没有激活的群聊。inviteOption
类型:GroupInviteType | undefined
描述:群聊的邀请加群方式设置。如果为
undefined
,则表示当前没有激活的群聊。枚举定义:
enum GroupInviteType {FREE_ACCESS = 'FREE_ACCESS',NEED_PERMISSION = 'NEED_PERMISSION',DISABLE_APPLY = 'DISABLE_APPLY'}
hasPermission
类型:(permission: GroupPermission, role?: GroupMemberRole, groupType?: GroupType) => boolean
描述:检查指定角色在特定群类型中是否具有某项权限。如果不传入
role
和 groupType
,则自动使用当前登录用户(自己)的角色和当前激活的群的类型。GroupPermission 枚举定义:
enum GroupPermission {EDIT_GROUP_PROFILE_NAME = 'EDIT_GROUP_PROFILE_NAME', // 编辑群名称EDIT_GROUP_PROFILE_AVATAR = 'EDIT_GROUP_PROFILE_AVATAR', // 编辑群头像EDIT_GROUP_PROFILE_NOTIFICATION = 'EDIT_GROUP_PROFILE_NOTIFICATION', // 编辑群公告REMOVE_MEMBER = 'REMOVE_MEMBER', // 移除成员SET_MEMBER_ROLE = 'SET_MEMBER_ROLE', // 设置成员角色MUTE_MEMBER = 'MUTE_MEMBER', // 禁言成员MUTE_ALL_MEMBERS = 'MUTE_ALL_MEMBERS', // 全员禁言TRANSFER_OWNERSHIP = 'TRANSFER_OWNERSHIP', // 转让群主DISMISS_GROUP = 'DISMISS_GROUP', // 解散群聊QUIT_GROUP = 'QUIT_GROUP' // 退出群聊}
getGroupMemberList
类型:(params?: GetGroupMemberListParams) => Promise<GroupMember[]>
描述:获取群成员列表,支持分页加载。加载完毕后,会自动将结果填充到
groupOwner
、allMembers
、adminMembers
中,无需处理返回值。GetGroupMemberListParams 接口定义:
interface GetGroupMemberListParams {count?: number; // 获取数量,最大100,默认100groupID?: string; // 群组ID,可选role?: string; // 角色筛选,可选offset?: number; // 偏移量,默认0}
updateGroupProfile
类型:(params: UpdateGroupProfileParams) => Promise<void>
描述:更新群组资料。groupID 可不填,会自动使用当前激活的群 ID,其余字段请至少保证有一个。
UpdateGroupProfileParams 接口定义:
interface UpdateGroupProfileParams {groupID?: string; // 群组ID,可选name?: string; // 群名称,可选avatar?: string; // 群头像URL,可选introduction?: string; // 群简介,可选notification?: string; // 群公告,可选}
addGroupMember
类型:(params: AddGroupMemberParams) => Promise<AddGroupMemberResult>
描述:添加群成员。groupID 可不填,会自动使用当前激活的群 ID。
AddGroupMemberParams 接口定义:
interface AddGroupMemberParams {groupID?: string; // 群组ID,可选userIDList: string[]; // 要添加的用户ID列表}
deleteGroupMember
类型:(params: DeleteGroupMemberParams) => Promise<void>
描述:删除群成员。groupID 可不填,会自动使用当前激活的群 ID。
DeleteGroupMemberParams 接口定义:
interface DeleteGroupMemberParams {groupID?: string; // 群组ID,可选userIDList: string[]; // 要删除的用户ID列表}
changeGroupOwner
类型:(params: ChangeGroupOwnerParams) => Promise<void>
描述:转让群主。groupID 可不填,会自动使用当前激活的群 ID。
ChangeGroupOwnerParams 接口定义:
interface ChangeGroupOwnerParams {groupID?: string; // 群组ID,可选newOwnerID: string; // 新群主用户ID}
setGroupMemberRole
类型:(params: SetGroupMemberRoleParams) => Promise<void>
描述:设置成员角色。groupID 可不填,会自动使用当前激活的群 ID。
SetGroupMemberRoleParams 接口定义:
interface SetGroupMemberRoleParams {groupID?: string; // 群组ID,可选userID: string; // 用户IDrole: GroupMemberRole; // 新角色 [GroupMemberRole.ADMIN, GroupMemberRole.COMMON]}
setChatPinned
类型:(value: boolean) => Promise<void>
描述:设置群聊置顶状态。会自动使用当前激活的群 ID。【Beta】
setChatMuted
类型:(value: boolean) => Promise<void>
描述:设置群聊免打扰状态。会自动使用当前激活的群 ID。【Beta】
setGroupMemberMuteTime
类型:(params: SetGroupMemberMuteTimeParams) => Promise<void>
描述:设置成员禁言时间。groupID 可不填,会自动使用当前激活的群 ID。取消禁言设置 time 为 0 即可。
SetGroupMemberMuteTimeParams 接口定义:
interface SetGroupMemberMuteTimeParams {groupID?: string; // 群组ID,可选userID: string; // 用户IDtime: number; // 禁言时间(秒)}
dismissGroup
类型:(groupID?: string) => Promise<void>
描述:解散群聊。groupID 可不填,会自动使用当前激活的群 ID。
quitGroup
类型:(groupID?: string) => Promise<void>
描述:退出群聊。groupID 可不填,会自动使用当前激活的群 ID。
使用示例
基础群聊设置组件
import React, { useState } from 'react';import { useGroupSettingState, GroupPermission } from '@tencentcloud/chat-uikit-react';const GroupSettingPanel = () => {const {groupID,groupName,avatar,memberCount,maxMemberCount,isMuted,isPinned,hasPermission,setChatPinned,setChatMuted,updateGroupProfile,quitGroup,} = useGroupSettingState();const [isEditing, setIsEditing] = useState(false);const [newName, setNewName] = useState(groupName || '');const handleUpdateName = async () => {try {await updateGroupProfile({ name: newName });setIsEditing(false);} catch (error) {console.error('更新失败:', error);}};if (!groupID) return <div>请选择群聊</div>;return (<div className="group-setting">{/* 群聊信息 */}<div className="group-info"><img src={avatar} alt="群头像" className="group-avatar" />{isEditing ? (<div className="edit-form"><inputvalue={newName}onChange={e => setNewName(e.target.value)}className="name-input"/><button onClick={handleUpdateName}>save</button><button onClick={() => setIsEditing(false)}>cancel</button></div>) : (<div className="group-details"><h3>{groupName}</h3><span>member: {memberCount}/{maxMemberCount}</span>{hasPermission(GroupPermission.UPDATE_GROUP_INFO) && (<button onClick={() => setIsEditing(true)}>Edit</button>)}</div>)}</div>{/* 聊天设置 */}<div className="chat-settings"><div className="setting-item"><span>pin conversation</span><inputtype="checkbox"checked={isPinned || false}onChange={e => setChatPinned(e.target.checked)}/></div><div className="setting-item"><span>mute</span><inputtype="checkbox"checked={isMuted || false}onChange={e => setChatMuted(e.target.checked)}/></div></div>{/* 操作按钮 */}<div className="actions"><button onClick={quitGroup} className="danger-btn">Quit Group</button></div></div>);};
效果图如下图所示:

成员管理组件
import React, { useEffect } from 'react';import { useGroupSettingState, GroupMemberRole, GroupPermission } from '@tencentcloud/chat-uikit-react';const GroupMemberList: React.FC = () => {const {allMembers,hasPermission,getGroupMemberList,setGroupMemberRole,deleteGroupMember,} = useGroupSettingState();useEffect(() => {getGroupMemberList({ count: 50 });}, []);const handlePromote = (userID: string) => {setGroupMemberRole({ userID, role: GroupMemberRole.ADMIN });};const handleRemove = (userID: string) => {deleteGroupMember({ userIDList: [userID] });};return (<div className="member-list">{allMembers?.map(member => (<div key={member.userID} className="member-item"><img src={member.avatar} alt="" className="member-avatar" /><span className="member-name">{member.nick}</span><span className="member-role">{member.role}</span>{hasPermission(GroupPermission.SET_MEMBER_ROLE) && (<div className="member-actions">{member.role === GroupMemberRole.COMMON && (<button onClick={() => handlePromote(member.userID)}>Promote to Admin</button>)}<button onClick={() => handleRemove(member.userID)}>Remove</button></div>)}</div>))}</div>);};
效果图如下图所示:

样式文件
// 基础群聊设置组件样式.group-setting {padding: 20px;background: white;border-radius: 8px;.group-info {display: flex;align-items: center;gap: 15px;margin-bottom: 20px;.group-avatar {width: 60px;height: 60px;border-radius: 50%;object-fit: cover;}.group-details {flex: 1;h3 {margin: 0 0 5px 0;font-size: 18px;}span {color: #666;font-size: 14px;}button {margin-top: 8px;padding: 4px 8px;background: #f0f0f0;border: none;border-radius: 4px;cursor: pointer;}}.edit-form {display: flex;flex-direction: column;gap: 10px;.name-input {padding: 8px;border: 1px solid #ddd;border-radius: 4px;}button {padding: 6px 12px;border: none;border-radius: 4px;cursor: pointer;&:first-child {background: #1890ff;color: white;}&:last-child {background: #f0f0f0;}}}}.chat-settings {margin-bottom: 20px;.setting-item {display: flex;justify-content: space-between;align-items: center;padding: 12px 0;border-bottom: 1px solid #f0f0f0;span {font-size: 14px;}input[type="checkbox"] {width: 20px;height: 20px;}}}.actions {.danger-btn {padding: 10px 20px;background: #ff4d4f;color: white;border: none;border-radius: 4px;cursor: pointer;&:hover {background: #ff7875;}}}}// 成员管理组件样式.member-list {.member-item {display: flex;align-items: center;gap: 12px;padding: 12px;border-bottom: 1px solid #f0f0f0;.member-avatar {width: 40px;height: 40px;border-radius: 50%;object-fit: cover;}.member-name {flex: 1;font-size: 14px;}.member-role {color: #666;font-size: 12px;margin-right: 10px;}.member-actions {display: flex;gap: 8px;button {padding: 4px 8px;font-size: 12px;border: 1px solid #ddd;border-radius: 4px;background: white;cursor: pointer;&:hover {border-color: #1890ff;color: #1890ff;}}}}}
实践建议
权限验证
在执行群聊操作前检查是否需要前置的权限检查。
使用
hasPermission
方法控制 UI 显示。性能优化
合理使用分页加载成员列表。
避免频繁调用 API,考虑防抖处理。
大群聊场景下注意内存使用。
用户体验
提供加载状态指示。
操作前进行确认提示。
及时更新本地状态以提供即时反馈。
通过以上文档,您可以全面了解和使用 GroupSettingState 的各项功能,构建功能完整的群聊管理界面。