GroupSettingState

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

我的收藏

概述

useGroupSettingState 是一个 Vue 3 Composition API Hook,用于管理群聊(Group)设置相关的状态和业务操作。它提供了群组信息、成员管理、权限控制等功能的响应式数据,以及群组管理、成员操作等核心功能的操作方法。该 Hook 会自动监听当前会话变化,并同步更新相关状态。

什么时候使用 GroupSettingState?

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

返回值速查表

字段
类型
描述
groupID
Ref<string | undefined>
群组 ID
groupType
Ref<GroupType | undefined>
群组类型
groupName
Ref<string | undefined>
群组名称
avatar
Ref<string | undefined>
群组头像 URL
Ref<string | undefined>
群公告
isMuted
Ref<boolean | undefined>
是否开启免打扰
isPinned
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>
当前用户角色
nameCard
Ref<string | undefined>
当前用户群名片
Ref<boolean | undefined>
是否全员禁言
isInGroup
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>
解散群组
quitGroup
(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; // 用户 ID
nick: 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; // 获取数量,最大 100
groupID?: string; // 群组 ID
role?: string; // 角色筛选
offset?: number; // 偏移量
}

updateGroupProfile

类型:(params: UpdateGroupProfileParams) => Promise<void>
详细说明:更新群组资料,默认值为 undefined
UpdateGroupProfileParams 接口定义:
interface UpdateGroupProfileParams {
groupID?: string; // 群组 ID
name?: 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; // 用户 ID
role: string; // 角色
groupID?: string; // 群组 ID
}

changeGroupOwner

类型:(params: ChangeGroupOwnerParams) => Promise<void>
详细说明:转让群主,默认值为 undefined
ChangeGroupOwnerParams 接口定义:
interface ChangeGroupOwnerParams {
newOwnerID: string; // 新群主 ID
groupID?: string; // 群组 ID
}

setGroupMemberMuteTime

类型:(params: SetGroupMemberMuteTimeParams) => Promise<void>
详细说明:设置成员禁言时间,默认值为 undefined
SetGroupMemberMuteTimeParams 接口定义:
interface SetGroupMemberMuteTimeParams {
userID: string; // 用户 ID
time: 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">
<div
v-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>

<div
class="member-actions"
>
<button
v-if="canPromote && member.role === GroupMemberRole.COMMON"
@click="handlePromote(member.userID)"
>
Promote to Admin
</button>
<button
v-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 类型支持。
可运行性:包含所有必要的逻辑和样式。

相关文档

交流与反馈

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