管理群成员名片
管理群成员名片
功能说明
群成员名片是用户在特定群组内的个性化显示信息,用于区分该用户在不同群组中的身份展示,例如,展示部门、岗位、项目角色等群内身份信息。
例如,在企业群组中,成员可将在群组中的名片设置为“部门-姓名”或“岗位-姓名”的格式,便于群内成员快速识别和沟通。
React Native SDK 提供群成员名片管理功能,支持群成员名片的设置、本地查询、服务端获取和变更监听。开启 用户信息自动管理功能 后,SDK 还支持通过消息自动同步群成员名片更新。
技术原理
群成员名片管理功能主要由 ChatGroupManager 和 ChatGroupEventHandler 提供。SDK 通过“主动设置或拉取、本地内存存储、事件通知、消息触发自动同步”的机制管理群成员名片,具体如下:
- 当前登录用户可通过
ChatGroupManager.updateGroupNamecard设置或更新自己在指定群组中的群成员名片。 - SDK 收到群成员名片变更通知,或通过消息自动同步群成员名片并更新本地内存后,会通过
ChatGroupEventHandler.onUserGroupNamecardChanged事件通知 Flutter 业务层。 - SDK 支持通过
ChatGroupManager.fetchGroupMembersInfo从服务端分页获取群成员信息,并将返回的群成员名片写入原生 SDK 本地内存。 - SDK 支持通过
ChatGroupManager.getGroupNamecard从原生 SDK 本地内存读取指定成员在指定群组中的群成员名片。该方法返回Future<String?>,不会主动请求服务端。 - 若在初始化 SDK 时将
ChatOptions.enableUserInfo设为true(默认为false),发送群聊消息时会自动附带发送方群成员名片的更新时间;接收方开启该功能后,若消息携带有效的更新时间,且该时间晚于本地内存中的对应时间戳,或本地尚无对应名片缓存,SDK 会自动从服务端拉取最新群成员名片,获取成功后更新原生 SDK 本地内存,并通过onUserGroupNamecardChanged事件通知 Flutter 业务层。
内存更新流程如下图所示:

前提条件
开始接入前,请确保满足以下条件:
监听群成员名片更新
SDK 提供 ChatGroupEventListener,用于监听群成员名片更新事件。建议在业务初始化阶段完成监听注册,并在组件卸载或不再需要监听时移除监听器。
SDK 收到群成员名片变更通知,或通过消息自动同步群成员名片并更新本地内存后,会触发 ChatGroupEventListener#onUserGroupNamecardChanged 事件。该事件适用于以下场景:
- 当前登录用户更新群成员名片后,群内其他 在线成员 收到变更通知。
- 开启 用户信息自动管理功能 后,接收方因接收消息触发自动同步并更新本地内存后。
主动调用 ChatGroupManager#fetchMemberInfoListFromServer 获取群成员信息时,不会因本次拉取触发该事件。获取成功后,请根据接口返回结果刷新界面,不应等待名片变更事件。
const groupNamecardListener: ChatGroupEventListener = {
onUserGroupNamecardChanged({ groupId, userId, namecard }) {
console.log('群成员名片更新:', { groupId, userId, namecard });
// 清除群名片时兼容 undefined、null 或空字符串等空值
},
};
ChatClient.getInstance().groupManager.addGroupListener(
groupNamecardListener
);
// 在页面或组件卸载时调用,移除同一个监听器对象。
function removeGroupNamecardListener(): void {
ChatClient.getInstance().groupManager.removeGroupListener(
groupNamecardListener
);
}
设置群成员名片
调用 ChatGroupManager#updateGroupNamecard 设置或更新当前登录用户在指定群组中的群成员名片。群内其他在线成员收到对应的群成员名片变更通知后,会触发 ChatGroupEventListener#onUserGroupNamecardChanged 事件。
try {
await ChatClient.getInstance().groupManager.updateGroupNamecard(
'groupId',
'new_namecard'
);
console.log('设置群成员名片成功');
} catch (error) {
console.error('设置群成员名片失败:', error);
}
若要清除当前用户在该群组中的群名片,请省略第二个参数或传入 undefined:
try {
await ChatClient.getInstance().groupManager.updateGroupNamecard('groupId');
} catch (error: unknown) {
console.error('清除群成员名片失败:', error);
}
从服务端获取群成员名片
调用 ChatGroupManager#fetchMemberInfoListFromServer 从服务器分页获取群成员信息,包含群成员名片。
获取成功后,相关群成员信息会自动更新至本地内存。有关该接口的更多说明,详见 管理群成员。
// limit:每页期望返回的群成员数量,默认 200。
// 首次调用时将 `cursor` 传入空字符串 `''`,后续调用时传入上一次返回的 `result.cursor`。
try {
const result = await ChatClient.getInstance()
.groupManager.fetchMemberInfoListFromServer('groupId', '', 50);
for (const member of result.list ?? []) {
console.log('群成员信息:', {
userId: member.memberId,
nickname: member.nickname,
avatarUrl: member.avatarUrl,
namecard: member.namecard,
});
}
// result.cursor 非空时,将其作为 cursor 获取下一页;为空时停止翻页
// const nextResult = await ChatClient.getInstance()
// .groupManager.fetchMemberInfoListFromServer(
// 'groupId',
// result.cursor,
// 50
// );
} catch (error) {
console.error('获取群成员信息失败:', error);
}
从本地内存获取群成员名片
调用 ChatGroupManager#getGroupNamecard 可从本地内存读取指定成员在指定群组中的群成员名片。该接口不会发起网络请求,适用于本地展示场景,返回类型为 Promise<string | undefined>。本地没有对应数据时可能返回 undefined,空字符串也会原样返回,展示时请兼容空值。
try {
const namecard = await ChatClient.getInstance()
.groupManager.getGroupNamecard('groupId', 'userId');
console.log('群成员名片:', namecard);
} catch (error) {
console.error('读取群成员名片失败:', error);
}
通过消息自动同步群成员名片
如果希望在发送消息时自动携带群成员名片的更新时间,并在接收消息时自动更新本地内存,需要在初始化 SDK 时开启 用户信息自动管理功能,即将 ChatOptions.enableUserInfo 设为 true。
const options = ChatOptions.withAppKey({
appKey: 'your-org#your-app',
enableUserInfo: true,
});
try {
await ChatClient.getInstance().init(options);
} catch (error: unknown) {
console.error('初始化 SDK 失败:', error);
}
提示
enableUserInfo 必须在调用 ChatClient#init 时通过 ChatOptions 传入。SDK 初始化完成后再修改原选项对象,不会重新配置已初始化的原生 SDK。
用户信息功能开启后,SDK 会执行以下操作:
- 当前登录用户更新群成员名片后,后续发送的消息会自动附带群成员名片更新时间。
- 接收方收到消息后,SDK 会将消息中的群成员名片更新时间与本地内存进行比较。
- 如果消息中的更新时间晚于本地内存,SDK 会自动从服务端拉取最新群成员名片。
- 获取成功后,SDK 会更新本地内存,并触发
ChatGroupEventListener#onUserGroupNamecardChanged事件。
此外,开启用户信息功能后,还可以通过收到的 ChatMessage.senderInfo 获取消息发送方当前可用的群成员名片信息。群名片字段为 groupNameCard。详见 用户信息自动管理。
const senderInfoListener: ChatMessageEventListener = {
onMessagesReceived(messages) {
for (const message of messages) {
console.log('发送方群成员名片:', message.senderInfo?.groupNameCard);
}
},
};
ChatClient.getInstance().chatManager.addMessageListener(senderInfoListener);
// 页面或组件卸载、不再需要监听时移除同一个监听器对象
function removeSenderInfoListener(): void {
ChatClient.getInstance().chatManager.removeMessageListener(senderInfoListener);
}
注意事项
- 群成员名片是用户在特定群组中的显示信息,不同群组之间互不影响。
ChatGroupManager#getGroupNamecard仅查询本地内存,不会主动从服务端获取最新数据。- 更新名片后,发给群内其他成员的变更通知仅投递给在线用户;通过消息自动同步引起的本地更新,也可触发
ChatGroupEventListener#onUserGroupNamecardChanged。主动获取成员信息不会因本次拉取触发该事件,应根据接口返回结果刷新界面。 - 若需通过消息自动同步群成员名片,必须在 SDK 初始化时将
ChatOptions.enableUserInfo设为true。 - 开启 用户信息自动管理 后,群成员名片的自动更新依赖消息触发;若业务需要主动获取最新数据,仍应调用服务端接口。
ChatGroupMember中的群名片字段为namecard,ChatMessageSenderInfo中的群名片字段为groupNameCard,两者的大小写不同。
常见问题
设置群成员名片后,为何其他成员未立即收到事件?
调用 ChatGroupManager#updateGroupNamecard 后,当前登录用户在指定群组中的群成员名片会更新。其他 在线成员 在收到对应的群成员名片变更通知后,才会触发 ChatGroupEventListener#onUserGroupNamecardChanged 事件。
为何调用 getGroupNamecard 获取不到群成员名片?
ChatGroupManager#getGroupNamecard 仅从本地内存读取数据,不会主动从服务端获取最新信息。如果本地尚未缓存对应成员的群成员名片,返回结果可能为 undefined 或空字符串。此时可先调用 ChatGroupManager#fetchMemberInfoListFromServer 从服务端获取群成员信息。如需通过消息自动同步群成员名片,还需在初始化时开启用户信息功能。
从服务端获取的群成员信息是否写入本地内存?
会。调用 ChatGroupManager#fetchMemberInfoListFromServer 从服务端获取群成员信息成功后,返回结果中的群成员名片等数据会写入本地内存,后续可通过 ChatGroupManager#getGroupNamecard 直接读取。
开启用户信息自动管理后,群成员名片为何会自动更新?
初始化时将 ChatOptions.enableUserInfo 设为 true 后,发送消息时会自动附带发送方群成员名片更新时间。接收方收到消息后,SDK 会将消息中的更新时间与本地内存进行比较。如果消息中的更新时间晚于本地内存,SDK 会自动从服务端拉取最新群成员名片并更新本地内存。
通过消息自动同步群成员名片后,还需主动从服务端获取吗?
视业务场景而定。通过消息自动同步依赖消息触发;如果业务需要立即获取最新群成员名片,或当前没有消息触发同步,仍建议调用 ChatGroupManager#fetchMemberInfoListFromServer 主动从服务端获取最新数据。
相关文档
接口列表
| API 名称 | 所属模块/类 | 说明 |
|---|---|---|
updateGroupNamecard | ChatGroupManager | 设置、更新或清除当前用户在指定群组中的群名片。 |
fetchMemberInfoListFromServer | ChatGroupManager | 从服务器分页获取群成员信息。 |
getGroupNamecard | ChatGroupManager | 从本地内存读取指定成员的群名片。 |
onUserGroupNamecardChanged | ChatGroupEventListener | 群成员名片发生变化并同步到本地时触发。 |
withAppKey | ChatOptions | 使用 App Key 创建 SDK 初始化配置。也可根据业务配置使用 withAppId。 |
init | ChatClient | 使用指定配置初始化 SDK。 |
