概述
useGroupSettingState 是一个 Vue 3 Composition API Hook,用于管理群聊(Group)设置相关的状态和业务操作。它提供了群组信息、成员管理、权限控制等功能的响应式数据,以及群组管理、成员操作等核心功能的操作方法。该 Hook 会自动监听当前会话变化,并同步更新相关状态。
什么时候使用 GroupSettingState?
当目前的
ChatSetting
组件能力无法满足您的特定需求,或者您希望基于底层数据重新开发一个自定义的群聊设置组件时,可以使用 useGroupSettingState()
组合式函数来获取原始的数据源和相关的操作方法,进而进行灵活的定制和开发。返回值速查表
字段 | 类型 | 描述 |
Ref<string | undefined> | 群组 ID | |
Ref<GroupType | undefined> | 群组类型 | |
Ref<string | undefined> | 群组名称 | |
Ref<string | undefined> | 群组头像 URL | |
Ref<string | undefined> | 群公告 | |
Ref<boolean | undefined> | 是否开启免打扰 | |
Ref<boolean | undefined> | 是否置顶会话 | |
Ref<GroupMember | undefined> | 群主信息 | |
Ref<GroupMember[] | undefined> | 管理员列表 | |
Ref<GroupMember[] | undefined> | 所有成员列表 | |
Ref<number | undefined> | 群成员数量 | |
Ref<number | undefined> | 群最大成员数量 | |
Ref<string | undefined> | 当前用户 ID | |
Ref<GroupMemberRole | undefined> | 当前用户角色 | |
Ref<string | undefined> | 当前用户群名片 | |
Ref<boolean | undefined> | 是否全员禁言 | |
Ref<boolean | undefined> | 是否在群内 | |
Ref<GroupInviteType | undefined> | 群邀请选项 | |
(permission: GroupPermission, role?: GroupMemberRole, groupType?: GroupType) => boolean | 检查权限 | |
(params?: GetGroupMemberListParams) => Promise<GroupMember[]> | 获取群成员列表 | |
(params: UpdateGroupProfileParams) => Promise<void> | 更新群资料 | |
(params: AddGroupMemberParams) => Promise<AddGroupMemberResult> | 添加群成员 | |
(params: DeleteGroupMemberParams) => Promise<void> | 删除群成员 | |
(params: ChangeGroupOwnerParams) => Promise<void> | 转让群主 | |
(params: SetGroupMemberRoleParams) => Promise<void> | 设置成员角色 | |
(params: SetGroupMemberMuteTimeParams) => Promise<void> | 设置成员禁言 | |
(value: boolean) => Promise<void> | 设置全员禁言 | |
(value: boolean) => Promise<void> | 设置会话置顶 | |
(value: boolean) => Promise<void> | 设置会话免打扰 | |
(groupID?: string) => Promise<void> | 解散群组 | |
(groupID?: string) => Promise<void> | 退出群组 |
类型定义
groupID
类型:Ref<string | undefined>
详细说明:当前群组的唯一标识符,默认值为
undefined
。groupType
类型:Ref<GroupType | undefined>
详细说明:群组类型,包括工作群、公开群、会议群等,默认值为
undefined
。GroupType 枚举定义:
enum GroupType {WORK = 'Private', // 工作群PUBLIC = 'Public', // 公开群MEETING = 'ChatRoom', // 会议群AVCHATROOM = 'AVChatRoom', // 直播群COMMUNITY = 'Community', // 社群}
groupName
类型:Ref<string | undefined>
详细说明:群组名称,默认值为
undefined
。avatar
类型:Ref<string | undefined>
详细说明:群组头像 URL 地址,默认值为
undefined
。introduction
类型:Ref<string | undefined>
详细说明:群组简介信息,默认值为
undefined
。notification
类型:Ref<string | undefined>
详细说明:群公告内容,默认值为
undefined
。isMuted
类型:Ref<boolean | undefined>
详细说明:当前会话是否开启免打扰模式,默认值为
undefined
。isPinned
类型:Ref<boolean | undefined>
详细说明:当前会话是否置顶显示,默认值为
undefined
。groupOwner
类型:Ref<GroupMember | undefined>
详细说明:群主信息,默认值为
undefined
。adminMembers
类型:Ref<GroupMember[] | undefined>
详细说明:群管理员列表,默认值为
undefined
。allMembers
类型:Ref<GroupMember[] | undefined>
详细说明:所有群成员列表,默认值为
undefined
。GroupMember 接口定义:
interface GroupMember {userID: string; // 用户 IDnick: string; // 用户昵称avatar: string; // 用户头像role: GroupMemberRole; // 成员角色joinTime: number; // 加入时间muteUntil: string; // 禁言截止时间memberCustomField: string; // 成员自定义字段}enum GroupMemberRole {OWNER, // 群主ADMIN, // 管理员COMMON, // 普通成员}
memberCount
类型:Ref<number | undefined>
详细说明:当前群成员数量,默认值为
undefined
。maxMemberCount
类型:Ref<number | undefined>
详细说明:群最大成员数量限制,默认值为
undefined
。currentUserID
类型:Ref<string | undefined>
详细说明:当前用户的 ID,默认值为
undefined
。currentUserRole
类型:Ref<GroupMemberRole | undefined>
详细说明:当前用户在群内的角色,默认值为
undefined
。GroupMemberRole 枚举定义:
enum GroupMemberRole {OWNER, // 群主ADMIN, // 管理员COMMON, // 普通成员}
nameCard
类型:Ref<string | undefined>
详细说明:当前用户的群名片,默认值为
undefined
。isMuteAllMembers
类型:Ref<boolean | undefined>
详细说明:是否开启全员禁言,默认值为
undefined
。isInGroup
类型:Ref<boolean | undefined>
详细说明:当前用户是否在群内,默认值为
undefined
。inviteOption
类型:Ref<GroupInviteType | undefined>
详细说明:群邀请选项,默认值为
undefined
。GroupInviteType 枚举定义:
enum GroupInviteType {FREE_ACCESS, // 自由加入NEED_PERMISSION, // 需要审批DISABLE_APPLY, // 禁止申请}
hasPermission
类型:(permission: GroupPermission, role?: GroupMemberRole, groupType?: GroupType) => boolean
详细说明:检查指定角色在指定群类型下是否具有某项权限,默认值为
undefined
。GroupPermission 枚举定义:
enum GroupPermission {// 群资料权限EDIT_GROUP_PROFILE_NAME = 'EDIT_GROUP_PROFILE_NAME', // 编辑群名称EDIT_GROUP_PROFILE_AVATAR = 'EDIT_GROUP_PROFILE_AVATAR', // 编辑群头像EDIT_GROUP_PROFILE_INTRODUCTION = 'EDIT_GROUP_PROFILE_INTRODUCTION', // 编辑群简介EDIT_GROUP_PROFILE_NOTIFICATION = 'EDIT_GROUP_PROFILE_NOTIFICATION', // 编辑群公告EDIT_GROUP_PROFILE_ELSE = 'EDIT_GROUP_PROFILE_ELSE', // 编辑其他群资料// 成员管理权限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[]>
详细说明:获取群成员列表,默认值为
undefined
。自动更新 allMember
属性。GetGroupMemberListParams 接口定义:
interface GetGroupMemberListParams {count?: number; // 获取数量,最大 100groupID?: string; // 群组 IDrole?: string; // 角色筛选offset?: number; // 偏移量}
updateGroupProfile
类型:(params: UpdateGroupProfileParams) => Promise<void>
详细说明:更新群组资料,默认值为
undefined
。UpdateGroupProfileParams 接口定义:
interface UpdateGroupProfileParams {groupID?: string; // 群组 IDname?: string; // 群名称avatar?: string; // 群头像introduction?: string; // 群简介notification?: string; // 群公告}
addGroupMember
类型:(params: AddGroupMemberParams) => Promise<AddGroupMemberResult>
详细说明:添加群成员,默认值为
undefined
。AddGroupMemberParams 接口定义:
interface AddGroupMemberParams {userIDList: string[]; // 用户 ID 列表groupID?: string; // 群组 ID}
AddGroupMemberResult 接口定义:
interface AddGroupMemberResult {data: {successUserIDList: string[]; // 成功添加的用户 ID 列表failureUserIDList: string[]; // 添加失败的用户 ID 列表existedUserIDList: string[]; // 已存在的用户 ID 列表};}
deleteGroupMember
类型:(params: DeleteGroupMemberParams) => Promise<void>
详细说明:删除群成员,默认值为
undefined
。DeleteGroupMemberParams 接口定义:
interface DeleteGroupMemberParams {userIDList: string[]; // 用户 ID 列表groupID?: string; // 群组 ID}
setGroupMemberRole
类型:(params: SetGroupMemberRoleParams) => Promise<void>
详细说明:设置成员角色,默认值为
undefined
。SetGroupMemberRoleParams 接口定义:
interface SetGroupMemberRoleParams {userID: string; // 用户 IDrole: string; // 角色groupID?: string; // 群组 ID}
changeGroupOwner
类型:(params: ChangeGroupOwnerParams) => Promise<void>
详细说明:转让群主,默认值为
undefined
。ChangeGroupOwnerParams 接口定义:
interface ChangeGroupOwnerParams {newOwnerID: string; // 新群主 IDgroupID?: string; // 群组 ID}
setGroupMemberMuteTime
类型:(params: SetGroupMemberMuteTimeParams) => Promise<void>
详细说明:设置成员禁言时间,默认值为
undefined
。SetGroupMemberMuteTimeParams 接口定义:
interface SetGroupMemberMuteTimeParams {userID: string; // 用户 IDtime: number; // 禁言时间(秒)groupID?: string; // 群组 ID}
setGroupMemberNameCard
类型:(params: SetGroupMemberNameCardParams) => Promise<void>
详细说明:设置群名片,默认值为
undefined
。SetGroupMemberNameCardParams 接口定义:
interface SetGroupMemberNameCardParams {nameCard: string; // 群名片userID?: string; // 用户 ID,不提供则修改当前用户groupID?: string; // 群组 ID}
setMuteAllMember
类型:(value: boolean) => Promise<void>
详细说明:设置全员禁言,默认值为
undefined
。setChatPinned
类型:(value: boolean) => Promise<void>
详细说明:设置会话置顶,默认值为
undefined
。【Beta】setChatMuted
类型:(value: boolean) => Promise<void>
详细说明:设置会话免打扰,默认值为
undefined
。【Beta】dismissGroup
类型:(groupID?: string) => Promise<void>
详细说明:解散群组,默认值为
undefined
。quitGroup
类型:(groupID?: string) => Promise<void>
详细说明:退出群组,默认值为
undefined
。示例代码
GroupChatSetting 组件
以下是使用
useGroupSettingState
实现一个简易的群成员列表,支持列表渲染群成员和成员角色类型,以及晋升群成员和移除群成员。<template><div class="member-list"><divv-for="member in allMembers":key="member.userID"class="member-item"><Avatar :src="member.avatar" :alt="member.nick" /><span class="member-name">{{ member.nick }}</span><span class="member-role">{{ member.role }}</span><divclass="member-actions"><buttonv-if="canPromote && member.role === GroupMemberRole.COMMON"@click="handlePromote(member.userID)">Promote to Admin</button><buttonv-if="canRemove && member.role === GroupMemberRole.COMMON"@click="handleRemove(member.userID)">Remove</button></div></div></div></template><script setup lang="ts">import { onMounted, computed } from 'vue';import {useGroupSettingState,GroupMemberRole,GroupPermission,Avatar,} from '@tencentcloud/chat-uikit-vue3';const {allMembers,hasPermission,getGroupMemberList,setGroupMemberRole,deleteGroupMember,} = useGroupSettingState();const canPromote = computed(() => hasPermission(GroupPermission.SET_MEMBER_ROLE));const canRemove = computed(() => hasPermission(GroupPermission.REMOVE_MEMBER));onMounted(() => {getGroupMemberList({ count: 50 });});const handlePromote = (userID: string) => {setGroupMemberRole({ userID, role: GroupMemberRole.ADMIN });};const handleRemove = (userID: string) => {deleteGroupMember({ userIDList: [userID] });};</script><style scoped>.member-list {display: flex;flex-direction: column;gap: 8px;}.member-item {display: flex;align-items: center;padding: 12px;border-radius: 8px;gap: 12px;}.member-name {font-weight: 500;}.member-role {font-size: 12px;color: #666;padding: 2px 8px;background: #f0f0f0;border-radius: 12px;}.member-actions {display: flex;gap: 8px;}.member-actions button {padding: 4px 12px;font-size: 12px;border: 1px solid #007bff;background: white;color: #007bff;border-radius: 4px;cursor: pointer;}.member-actions button:hover {background: #007bff;color: white;}</style>
示例效果如下所示:

实现建议
权限检查:使用
hasPermission
进行权限检查。响应式数据:所有状态都是响应式的,自动更新 UI。
错误处理:完整的错误处理和用户反馈。
类型安全:完整的 TypeScript 类型支持。
可运行性:包含所有必要的逻辑和样式。