tencent cloud

即时通信 IM

动态与公告
产品动态
公告
产品简介
产品概述
基本概念
应用场景
功能介绍
账号系统
用户资料与关系链
消息管理
群组相关
公众号系统
音视频通话 Call
使用限制
购买指南
计费概述
价格说明
购买指引
续费指引
停服说明
退费说明
开发指引
Demo 专区
开通服务
体验 Demo
快速跑通
下载中心
SDK & Demo 源码
更新日志
聊天互动(含 UI)
TUIKit 组件介绍
快速开始
全功能接入
单功能接入
AI 集成
构建基础界面
更多特性
定义外观
国际化界面语言
推送服务(Push)
服务概述
名词解释
开通服务
快速跑通
厂商通道
数据统计
排查工具
客户端 API
服务端 API
推送回调
高级功能
更新日志
错误码
常见问题
智能客服
功能概述
快速入门
集成指引
管理员操作手册
客服操作手册
更多实践
直播间搭建
AI 聊天机器人方案
超大娱乐协作社群
Discord 实现指南
游戏内集成 Chat 指南
类 WhatsApp Channel 搭建方案
发送红包
Chat 应对防火墙限制相关
无 UI 集成
快速开始
集成 SDK
初始化
登录登出
消息相关
会话相关
群组相关
社群话题
用户管理
离线推送
云端搜索
本地搜索
公众号
客户端 API
JavaScript
Android
iOS & macOS
Swift
Flutter
Electron
Unity
React Native
C 接口
C++
服务端 API
生成 UserSig
REST API
第三方回调
控制台指南
新版控制台介绍
创建并升级应用
基本配置
功能配置
账号管理
群组管理
公众号管理
回调配置
用量统计
资源包查看指南
实时监控
开发辅助工具
访问管理
高级功能
常见问题
uni-app 常见问题
购买相关问题
SDK 相关问题
账号鉴权相关问题
用户资料与关系链相关问题
消息相关问题
群组相关问题
直播群相关问题
昵称头像相关问题
协议与认证
服务等级协议
安全合规认证
IM 政策
隐私政策
数据隐私和安全协议
平滑迁移方案
平滑迁移完整版
平滑迁移简化版
错误码
联系我们

GroupSetting State

PDF
聚焦模式
字号
最后更新时间: 2025-07-22 17:46:08

介绍

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

属性列表

群聊状态相关

字段
类型
描述
groupID
string | undefined
群组 ID
groupType
GroupType | undefined
群组类型
groupName
string | undefined
群组名称
avatar
string | undefined
群组头像 URL
notification
string | undefined
群组公告
isMuted
boolean | undefined
是否免打扰
isPinned
boolean | undefined
是否置顶
groupOwner
GroupMember | undefined
群主信息
adminMembers
GroupMember[]
管理员列表
allMembers
GroupMember[] | undefined
所有成员列表
memberCount
number | undefined
当前成员数量
maxMemberCount
number | undefined
最大成员数量
currentUserID
string | undefined
当前用户 ID
currentUserRole
GroupMemberRole | undefined
当前用户角色
isMuteAllMembers
boolean | undefined
是否全员禁言
isInGroup
boolean | undefined
当前用户是否在群内
inviteOption
GroupInviteType | undefined
邀请加群方式

权限工具方法

方法
类型
描述
hasPermission
(permission: GroupPermission, role?: GroupMemberRole, groupType?: GroupType) => boolean
检查是否具有特定权限

业务操作方法

方法
类型
描述
getGroupMemberList
(params?: GetGroupMemberListParams) => Promise<IGroupMember[]>
获取群成员列表
updateGroupProfile
(params: UpdateGroupProfileParams) => Promise<void>
更新群组资料
addGroupMember
(params: AddGroupMemberParams) => Promise<IAddGroupMemberResult>
添加群成员
deleteGroupMember
(params: DeleteGroupMemberParams) => Promise<void>
删除群成员
changeGroupOwner
(params: ChangeGroupOwnerParams) => Promise<void>
转让群主
setGroupMemberRole
(params: SetGroupMemberRoleParams) => Promise<void>
设置成员角色
setChatPinned
(value: boolean) => Promise<void>
设置群聊置顶【Beta】
setChatMuted
(value: boolean) => Promise<void>
设置群聊免打扰【Beta】
setGroupMemberMuteTime
(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
描述: 检查指定角色在特定群类型中是否具有某项权限。如果不传入 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,默认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;
}
}
}
}
}

实践建议

1. 权限验证

在执行群聊操作前检查是否需要前置的权限检查
使用 hasPermission 方法控制 UI 显示

2. 性能优化

合理使用分页加载成员列表
避免频繁调用 API,考虑防抖处理
大群聊场景下注意内存使用

3. 用户体验

提供加载状态指示
操作前进行确认提示
及时更新本地状态以提供即时反馈
通过以上文档,您可以全面了解和使用 GroupSettingState 的各项功能,构建功能完整的群聊管理界面。

帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈