GroupSetting State

最近更新时间:2025-09-12 18:14:53

我的收藏

介绍

GroupSettingState 是一个功能强大的群聊状态管理中心,专门用于管理群聊的各种设置、成员信息和权限控制。它提供了群聊信息管理、成员操作、权限验证、群聊设置等全方位的功能支持,是构建群聊管理界面的核心工具。
该 Hook 具备以下特色:
完整的群聊信息管理:群组基本信息、成员列表、权限设置等。
智能权限控制:基于角色的权限验证和操作限制。
丰富的成员操作:添加、删除、设置角色、禁言等成员管理功能。
实时状态同步:自动监听群聊状态变化并更新本地数据。

什么时候使用 GroupSettingState?

当目前的 ChatSetting 组件能力无法满足您的特定需求,或者您希望基于底层数据重新开发一个自定义的群聊设置组件时,可以使用 useGroupSettingState() 组合式函数来获取原始的数据源和相关的操作方法,进而进行灵活的定制和开发。

属性列表

群聊状态相关

字段
类型
描述
groupID
string | undefined
群组 ID
groupType
GroupType | undefined
群组类型
groupName
string | undefined
群组名称
avatar
string | undefined
群组头像 URL
string | undefined
群组公告
isMuted
boolean | undefined
是否免打扰
isPinned
boolean | undefined
是否置顶
GroupMember | undefined
群主信息
GroupMember[]
管理员列表
GroupMember[] | undefined
所有成员列表
number | undefined
当前成员数量
number | undefined
最大成员数量
string | undefined
当前用户 ID
GroupMemberRole | undefined
当前用户角色
boolean | undefined
是否全员禁言
isInGroup
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; // 用户ID
nick: string; // 用户昵称
avatar: string; // 用户头像URL
role: 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
描述:检查指定角色在特定群类型中是否具有某项权限。如果不传入 rolegroupType,则自动使用当前登录用户(自己)的角色和当前激活的群的类型。
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[]>
描述:获取群成员列表,支持分页加载。加载完毕后,会自动将结果填充到 groupOwnerallMembersadminMembers 中,无需处理返回值。
GetGroupMemberListParams 接口定义:
interface GetGroupMemberListParams {
count?: number; // 获取数量,最大100,默认100
groupID?: 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; // 用户ID
role: 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; // 用户ID
time: 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">
<input
value={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>
<input
type="checkbox"
checked={isPinned || false}
onChange={e => setChatPinned(e.target.checked)}
/>
</div>
<div className="setting-item">
<span>mute</span>
<input
type="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 的各项功能,构建功能完整的群聊管理界面。

相关文档

交流与反馈

如遇任何问题,可联系 官网售后 反馈,享有专业工程师的支持,解决您的难题。