文档概览/
Feedback

Android（Compose）

组件概述

ChatSetting 是基于 Jetpack Compose 构建的聊天设置组件集合，主要包含单聊设置（C2CChatSetting）和群聊设置（GroupChatSetting）两个核心组件。这些组件为用户提供了完整的聊天会话管理功能，包括用户信息管理、权限设置、群组管理等核心能力，并支持隐藏、替换和新增设置项。
单聊设置界面
群聊设置界面



组件集成

ChatSetting 组件属于 TUIKit Compose 的一部分，集成 TUIKit Compose 即可获取并使用 ChatSetting 组件。集成方法请参考文档 TUIKit Compose 里的集成步骤。

组件构成

ChatSetting 包含两个主要组件：C2CChatSetting（单聊设置）和 GroupChatSetting（群聊设置），每个组件都提供了丰富的配置选项。

单聊设置（C2CChatSetting）

对外方法

方法名
参数
描述
C2CChatSetting
userID: String
聊天对象的用户 ID。
modifier: Modifier
Jetpack Compose 中用来设置组件的样式、布局、行为和外观。
onSendMessageClick: () -> Unit
“发送消息”按钮点击回调，通常在这里跳转到与该用户的聊天页面。可选参数。
onContactDeleted: () -> Unit
删除好友成功后的回调，通常在这里关闭设置页面。点击“删除好友”时，组件会先弹出确认框，用户确认后才执行删除。可选参数。
onVoiceCallClick: (() -> Unit)?
“语音通话”按钮点击回调，可选参数。为 null 时，组件会直接向该用户发起语音通话（需要集成 TUICallKit）。
onVideoCallClick: (() -> Unit)?
“视频通话”按钮点击回调，可选参数。为 null 时，组件会直接向该用户发起视频通话（需要集成 TUICallKit）。
config: C2CChatSettingConfigProtocol
单聊设置配置，控制各设置项的显示，并支持编辑设置项。默认值为 C2CChatSettingConfig()。
c2cChatSettingViewModelFactory: C2CChatSettingViewModelFactory
创建组件内部 C2CChatSettingViewModel 的工厂类。通常情况下，您无需手动创建，组件已提供默认实现。

群聊设置（GroupChatSetting）

对外方法

方法名
参数
描述
GroupChatSetting
groupID: String
群组 ID，用于标识群聊。
modifier: Modifier
Jetpack Compose 中用来设置组件的样式、布局、行为和外观。
onGroupMemberClick: (GroupMember) -> Unit
群成员点击回调，通常在这里跳转到该成员的资料页。可选参数。
onGroupDeleted: () -> Unit
退出群聊或解散群聊成功后的回调，通常在这里关闭设置页面。可选参数。
config: GroupChatSettingConfigProtocol
群聊设置配置，控制各设置项的显示，并支持编辑设置项。默认值为 GroupChatSettingConfig()。
groupChatSettingViewModelFactory: GroupChatSettingViewModelFactory
创建组件内部 GroupChatSettingViewModel 的工厂类。通常情况下，您无需手动创建，组件已提供默认实现。

基础用法

初始化 C2CChatSetting 即可直接展示单聊设置页面，示例代码如下：
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.systemBarsPadding
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import io.trtc.tuikit.chat.uikit.components.chatsetting.ui.C2CChatSetting

@Composable
fun C2CChatSettingScreen(
    userID: String,
    onOpenChat: (conversationID: String) -> Unit,
    onClose: () -> Unit
) {
    Box(
        modifier = Modifier
            .fillMaxSize()
            .systemBarsPadding()
    ) {
        C2CChatSetting(
            userID = userID,
            onSendMessageClick = {
                // 点击“发送消息”，跳转到与该用户的聊天页面
                onOpenChat("c2c_$userID")
            },
            onContactDeleted = {
                // 删除好友成功，关闭当前页面
                onClose()
            }
        )
    }
}
初始化 GroupChatSetting 即可直接展示群聊设置页面，示例代码如下：
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.systemBarsPadding
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import io.trtc.tuikit.chat.uikit.components.chatsetting.ui.GroupChatSetting

@Composable
fun GroupChatSettingScreen(
    groupID: String,
    onOpenUserProfile: (userID: String) -> Unit,
    onClose: () -> Unit
) {
    Box(
        modifier = Modifier
            .fillMaxSize()
            .systemBarsPadding()
    ) {
        GroupChatSetting(
            groupID = groupID,
            onGroupMemberClick = { member ->
                // 点击群成员，跳转到该成员的资料页
                onOpenUserProfile(member.userID)
            },
            onGroupDeleted = {
                // 退出或解散群聊成功，关闭当前页面
                onClose()
            }
        )
    }
}

自定义组件

您可以隐藏、替换或新增设置项。方法如下。

隐藏设置项

通过 C2CChatSettingConfig 和 GroupChatSettingConfig 中的开关控制各设置项是否显示，所有开关的默认值均为 true。
单聊设置的开关
开关
对应设置项 ID
设置项
isShowHeader
ChatSettingItemIDs.C2C_HEADER
顶部的用户资料（头像、昵称、用户 ID、个性签名）
isShowRemark
ChatSettingItemIDs.C2C_REMARK
备注名
isShowDoNotDisturb
ChatSettingItemIDs.C2C_DO_NOT_DISTURB
消息免打扰
isShowPin
ChatSettingItemIDs.C2C_PIN
置顶聊天
isShowChatBackground
ChatSettingItemIDs.C2C_CHAT_BACKGROUND
聊天背景
isShowBlacklist
ChatSettingItemIDs.C2C_BLACKLIST
加入黑名单
isShowSendMessage
ChatSettingItemIDs.C2C_SEND_MESSAGE
发送消息
isShowVoiceCall
ChatSettingItemIDs.C2C_VOICE_CALL
语音通话
isShowVideoCall
ChatSettingItemIDs.C2C_VIDEO_CALL
视频通话
isShowClearHistory
ChatSettingItemIDs.C2C_CLEAR_HISTORY
清空聊天记录
isShowDeleteFriend
ChatSettingItemIDs.C2C_DELETE_FRIEND
删除好友
群聊设置的开关
开关
对应设置项 ID
设置项
isShowHeader
ChatSettingItemIDs.GROUP_HEADER
顶部的群资料（群头像、群名称、群 ID）
isShowMemberPreview
ChatSettingItemIDs.GROUP_MEMBER_PREVIEW
群成员预览
isShowNotice
ChatSettingItemIDs.GROUP_NOTICE
群公告
isShowManagement
ChatSettingItemIDs.GROUP_MANAGEMENT
管理群
isShowGroupType
ChatSettingItemIDs.GROUP_TYPE
群类型
isShowJoinMethod
ChatSettingItemIDs.GROUP_JOIN_METHOD
主动加群方式
isShowInviteMethod
ChatSettingItemIDs.GROUP_INVITE_METHOD
邀请进群方式
isShowAlias
ChatSettingItemIDs.GROUP_ALIAS
我的群名片
isShowDoNotDisturb
ChatSettingItemIDs.GROUP_DO_NOT_DISTURB
消息免打扰
isShowPin
ChatSettingItemIDs.GROUP_PIN
置顶聊天
isShowChatBackground
ChatSettingItemIDs.GROUP_CHAT_BACKGROUND
聊天背景
isShowTransferOwner
ChatSettingItemIDs.GROUP_TRANSFER_OWNER
转让群主
isShowClearHistory
ChatSettingItemIDs.GROUP_CLEAR_HISTORY
清空聊天记录
isShowDeleteAndQuit
ChatSettingItemIDs.GROUP_DELETE_AND_QUIT
退出群聊
isShowDismiss
ChatSettingItemIDs.GROUP_DISMISS
解散该群聊
以下示例隐藏了单聊设置中的“加入黑名单”和音视频通话按钮，并通过 customActions 在底部操作按钮区域的末尾增加了一个“投诉”按钮：
import io.trtc.tuikit.chat.uikit.components.chatsetting.config.C2CChatSettingConfig
import io.trtc.tuikit.chat.uikit.components.chatsetting.ui.C2CChatSetting
import io.trtc.tuikit.chat.uikit.components.chatsetting.ui.SettingRowButton
import io.trtc.tuikit.chat.uikit.components.chatsetting.ui.SettingRowButtonStyle

C2CChatSetting(
    userID = userID,
    config = C2CChatSettingConfig(
        isShowBlacklist = false,   // 隐藏“加入黑名单”
        isShowVoiceCall = false,   // 隐藏“语音通话”
        isShowVideoCall = false    // 隐藏“视频通话”
    ),
    customActions = {
        // 显示在底部操作按钮区域的末尾
        SettingRowButton(
            title = "投诉",
            style = SettingRowButtonStyle.DANGER,
            onClick = {
                // 跳转到投诉页面
            }
        )
    }
)

编辑设置项

如需替换、移动或新增设置项，可以通过 C2CChatSettingConfig 或 GroupChatSettingConfig 的 customizeItems 编辑设置项。在 customizeItems 中，可以通过 editorContext.userID（单聊）或 editorContext.groupID（群聊）获取当前聊天对象，通过 editorContext.androidContext 获取 Android Context，并调用以下方法编辑设置项：
方法
描述
add(item)
在末尾添加设置项。item 的 ID 为空白或与已有设置项重复时会抛出 IllegalArgumentException。
remove(ID)
移除指定 ID 的设置项，不存在时返回 false。
replace(ID) { item -> ... }
替换指定 ID 的设置项，不存在时返回 false。替换后的设置项必须保持 ID 不变，否则会抛出异常。
insertBefore(anchorID, item) / insertAfter(anchorID, item)
在锚点设置项之前或之后插入设置项。锚点不存在时返回 false，且不会插入。item 的 ID 规则与 add 相同。
moveBefore(ID, anchorID) / moveAfter(ID, anchorID)
将设置项移动到锚点设置项之前或之后，任意一个 ID 不存在时返回 false。
clear()
移除全部设置项。
items
当前设置项列表的只读快照。
设置项 ChatSettingCustomItem 的字段说明如下：
字段
类型
描述
ID
String
设置项的唯一标识，必填。
sectionID
String?
设置项所属的分组 ID，默认为 null，不能为空白字符串。
contentFactory
@Composable (C) -> Unit
设置项的内容，参数为 editorContext，单聊为 C2CChatSettingItemContext，群聊为 GroupChatSettingItemContext。
相邻且 sectionID 相同的设置项会显示在同一个分组中，分组内的设置项之间有分隔线，分组之间有间隔；sectionID 为 null 的设置项单独显示。默认的分组 ID 定义在 ChatSettingSectionIDs 中：
分组 ID
包含的默认设置项
ChatSettingSectionIDs.C2C_REMARK
备注名
ChatSettingSectionIDs.C2C_SWITCHES
消息免打扰、置顶聊天
ChatSettingSectionIDs.C2C_CHAT_BACKGROUND
聊天背景
ChatSettingSectionIDs.C2C_BLACKLIST
加入黑名单
ChatSettingSectionIDs.C2C_ACTIONS
发送消息、语音通话、视频通话、清空聊天记录、删除好友，以及 customActions
ChatSettingSectionIDs.GROUP_SETTINGS
群公告、管理群、群类型、主动加群方式、邀请进群方式
ChatSettingSectionIDs.GROUP_ALIAS
我的群名片
ChatSettingSectionIDs.GROUP_SWITCHES
消息免打扰、置顶聊天
ChatSettingSectionIDs.GROUP_CHAT_BACKGROUND
聊天背景
ChatSettingSectionIDs.GROUP_ACTIONS
转让群主、清空聊天记录、退出群聊、解散该群聊
顶部资料（C2C_HEADER、GROUP_HEADER）和群成员预览（GROUP_MEMBER_PREVIEW）的 sectionID 为 null。
自定义设置项的内容可以使用组件提供的以下组件，与默认设置项保持一致的样式：
组件
描述
SettingRowNavigate(title, value, showArrow, customAccessoryResId, onClick)
左侧为标题、右侧为文字和箭头的设置行。onClick 为 null 时不可点击。
SettingRowToggle(title, checked, onCheckedChange)
带开关的设置行。
SettingRowButton(title, style, onClick)
文字居中的按钮行，style 支持 NORMAL（默认）、LINK（链接色）和 DANGER（警示色）。
以下示例隐藏了群聊设置中的“群类型”，在“置顶聊天”之后新增了一个开关，并在“聊天背景”之后新增了一个独立的分组：
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import io.trtc.tuikit.chat.uikit.components.chatsetting.config.GroupChatSettingConfig
import io.trtc.tuikit.chat.uikit.components.chatsetting.model.ChatSettingCustomItem
import io.trtc.tuikit.chat.uikit.components.chatsetting.model.ChatSettingItemIDs
import io.trtc.tuikit.chat.uikit.components.chatsetting.model.ChatSettingSectionIDs
import io.trtc.tuikit.chat.uikit.components.chatsetting.ui.GroupChatSetting
import io.trtc.tuikit.chat.uikit.components.chatsetting.ui.SettingRowNavigate
import io.trtc.tuikit.chat.uikit.components.chatsetting.ui.SettingRowToggle

val groupSettingConfig = GroupChatSettingConfig(
    isShowGroupType = false   // 隐藏“群类型”
).customizeItems {
    // 加入“消息免打扰”“置顶聊天”所在的分组，放在“置顶聊天”之后
    insertAfter(
        ChatSettingItemIDs.GROUP_PIN,
        ChatSettingCustomItem(
            ID = "custom.group.showMemberNickname",
            sectionID = ChatSettingSectionIDs.GROUP_SWITCHES
        ) {
            // 示例中的开关状态仅保存在内存，实际使用时请与业务数据绑定
            var checked by remember { mutableStateOf(true) }
            SettingRowToggle(
                title = "显示群成员昵称",
                checked = checked,
                onCheckedChange = { checked = it }
            )
        }
    )
    // 在“聊天背景”之后新增一个独立的分组
    insertAfter(
        ChatSettingItemIDs.GROUP_CHAT_BACKGROUND,
        ChatSettingCustomItem(
            ID = "custom.group.files",
            sectionID = "custom.section.groupFiles"
        ) { itemContext ->
            SettingRowNavigate(
                title = "群文件",
                onClick = {
                    // 跳转到群文件页面，itemContext.groupID 为当前群 ID
                }
            )
        }
    )
}

GroupChatSetting(
    groupID = groupID,
    config = groupSettingConfig
)
注意：
群聊设置中的“管理群”“消息免打扰”“置顶聊天”“转让群主”“清空聊天记录”“退出群聊”“解散该群聊”会根据群类型和当前用户的群角色自动隐藏，例如非群主看不到“转让群主”和“解散该群聊”。通过 replace 替换后的设置项只要 ID 不变，仍然受权限控制；新增的设置项不受权限控制，请自行判断是否展示。
插入设置项时，如果锚点设置项已通过开关隐藏，insertBefore / insertAfter 会返回 false 且不会插入。