好友管理
本文档旨在指导开发者如何使用融云即时通讯 Web IMLib SDK 实现添加好友、删除好友、查看好友列表、管理好友等功能。
提示
此功能从 5.12.0 版本开始支持。
开通服务
使用此功能前，您须在控制台开通信息托管服务。
好友事件监听
好友监听定义包含好友添加、删除、好友申请状态、清空全部好友、好友信息变更多端同步等。
监听返回的数据类型快速连接：
- 好友添加数据类型：IFriendAdd。
- 删除好友数据类型：IFriendDelete。
- 清空全部好友数据类型为
number时间戳代表清空好友的时间。 - 好友申请数据类型：IFriendApplicationStatusChange。
- 好友信息变更多端同步数据类型：IFriendInfoChangedSync。
javascript
// 添加好友
RongIMLib.addEventListener(RongIMLib.Events.FRIEND_ADDED, (data) => {
// data 类型为 IFriendAdd
console.info('添加好友监听', data);
});
// 删除好友
RongIMLib.addEventListener(RongIMLib.Events.FRIEND_DELETE, (data) => {
// data 类型为 IFriendDelete
console.info('删除好友监听', data);
});
// 清空全部好友
RongIMLib.addEventListener(RongIMLib.Events.FRIEND_CLEARED, (data) => {
// data 类型为 number，时间戳代表清空好友的时间
console.info('清空全部好友监听', data);
});
// 好友申请
RongIMLib.addEventListener(RongIMLib.Events.FRIEND_APPLICATION_STATUS_CHANGED, (data) => {
// data 类型为 IFriendApplicationStatusChange
console.info('好友申请监听', data);
});
// 【多端同步】好友信息监听
RongIMLib.addEventListener(RongIMLib.Events.FRIEND_INFO_CHANGED_SYNC, (data) => {
// data 类型为 IFriendInfoChangedSync
console.info('【多端同步】好友信息监听', data);
});
好友在线状态与资料变更
好友之间的在线状态和用户资料变更，无需调用 subscribeEvent 接口主动订阅。
为了接收好友在线状态和资料事件的变更通知，您需要设置订阅监听器。监听器需要在连接之前调用。
订阅事件的变更，需要根据 SubscribeType 订阅类型来处理对应的业务， SubscribeType.FRIEND_ONLINE_STATUS 时代表好友在线状态；SubscribeType.FRIEND_USER_PROFILE 代表好友资料。
javascript
// 好友在线装填好友信息同步完成
RongIMLib.addEventListener(RongIMLib.Events.SUBSCRIBED_USER_STATUS_CHANGE, (data) => {
// 好友的在线状态变更
if (data.subscribeType === RongIMLib.SubscribeType.FRIEND_ONLINE_STATUS) {
console.info('好友的在线状态变更', data);
} else if (data.subscribeType === RongIMLib.SubscribeType.FRIEND_USER_PROFILE) {
// 好友的用户资料变更
console.info('好友的用户资料变更', data);
}
});
好友操作
添加好友
用户通过用户名、用户ID、手机号等信息，搜索出用户后，可选择是否输入好友申请内容，申请添加好友。
提示
一个用户最多可以添加 3000 个好友。
加好友权限说明
AppKey 默认用户信息权限为 需要用户同意添加好友。
下面列举了 AppKey 级权限与 用户 级权限综合说明：
| AppKey 权限 | 用户级权限 | 结果 |
|---|---|---|
| 都不可见、仅好友可见、所有人可见 | 未设置 | 以 AppKey 权限设置为准 |
| 都不可见、仅好友可见、所有人可见 | 设置为（都不可见、所有人可见、仅好友可见） | 以用户权限设置为准 |
不同的权限设置，会产生以下两种流程
场景1：添加好友不需要对方验证
- 用户 A 和 B 调用
setFriendListener设置好友事件监听。 - 用户 B 通过
setFriendAddPermission设置加好友权限为 : 任何人直接添加好友，见 FriendAddPermission。 - 用户 A 调用
addFriend申请添加 B 为好友，接口返回processCode为0，表示直接加为好友，同时用户 A 和 B 都会收到好友添加监听Events.FRIEND_ADDED。
场景2：添加好友需要通过对方验证
- 用户 A 和 B 调用
setFriendListener设置好友事件监听。 - 用户 B 通过
setFriendAddPermission设置加好友权限为 : 需要用户同意添加好友，见FriendAddPermission。 - 用户 A 调用
addFriend申请添加 B 为好友，接口返回processCode为25461，表示需要等待用户 B 的验证，同时用户 A 和 B 都会收到好友申请状态监听Events.FRIEND_APPLICATION_STATUS_CHANGED。 - 用户 B 收到
Events.FRIEND_APPLICATION_STATUS_CHANGED监听，参数 FriendApplicationStatus 为UNHANDLED，可以选择接受或者拒绝：- 用户 B 调用
acceptFriendApplication接受好友请求，双方都会收到Events.FRIEND_ADDED监听，说明好友添加成功 。 - 用户 B 调用
refuseFriendApplication拒绝好友请求，双方都会收到Events.FRIEND_APPLICATION_STATUS_CHANGED监听，参数 FriendApplicationStatus 为REFUSED。
- 用户 B 调用
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | string | 是 | 目标用户 ID，需要添加为好友的用户 ID。 |
| directionType | DirectionType | 是 | 好友类型 |
| extra | string | 否 | 附加信息，发送好友请求时的附加信息，长度不超过 128 个字符。 |
javascript
const userId = 'UserId';
const directionType = DirectionType.BOTH
const extra = 'Hello, I would like to add you as a friend.';
const res = await RongIMLib.addFriend(userId, directionType, extra);
console.info('请求添加好友结果：', res);
提示
请求添加好友结果包含 code 和 processCode，code 代表请求操作状态，processCode 为需要后续处理的业务状态码。
解除好友
您可以使用 deleteFriends 批量解除好友关系。解除好友成功，双方都会收到好友删除监听 Events.FRIEND_DELETE。
该接口支持批量移除，您可以一次传入多个 userId 解除多个用户好友关系，最多不超过 100 个。
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userIds | string[] | 是 | 目标用户 ID 数组，需要解除好友关系的用户 ID，一次最多解除 100 个用户。 |
| directionType | DirectionType | 是 | 好友类型 |
javascript
const userIds = ['UserId1', 'UserId2'];
const directionType = DirectionType.BOTH;
const res = await RongIMLib.deleteFriends(userIds, directionType);
console.info('请求解除好友结果：', res);
好友信息设置
您可以使用 setFriendInfo 设置好友的备注名和扩展信息。
提示
- 扩展信息的 key 需要通过开发者后台或 API 设置后才能使用，否则返回设置失败，最多可设置 10 个扩展信息 key。
- 好友信息修改成功后，本用户登录的其他终端会收到好友信息变更多端监听
Events.FRIEND_INFO_CHANGED_SYNC。
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | string | 是 | 好友用户 ID |
| remark | string | 否 | 好友备注名，最多为 64 个字符。不传或为空时清除备注名 |
| extProfile | {[key: string]: string} | 否 | 扩展信息，开发者可根据自身业务需求添加自定义扩展属性，默认最多可设置 10 个扩展信息。自定义属性需要通过开发者后台或 API 设置后才能使用，否则返回设置失败 |
javascript
const userId = 'UserId';
const remark = 'Best Friend';
RongIMLib.setFriendInfo(userId, remark);
检查好友关系
用户可以检查好友关系，目前仅支持双向好友检查。
提示
一次最多检查 20 个用户。
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userIds | string[] | 是 | 好友关系的用户 ID 列表，一次最多检查 20 个用户 |
| directionType | DirectionType | 是 | 检查的好友类型 |
javascript
const userIds = ['UserId1', 'UserId2'];
const directionType = DirectionType.BOTH;
const res = await RongIMLib.checkFriends(userIds, directionType);
console.info('好友关系检查结果：', res);
设置加好友权限
设置当前用户的加好友权限，未设置时以 AppKey 默认的加好友权限为准。
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| permission | FriendAddPermission | 是 | 加好友权限，参照 FriendAddPermission |
javascript
const permission = FriendAddPermission.Free;
const res = await RongIMLib.setFriendAddPermission(permission);
console.info('设置当前用户的加好友权限结果：', res);
获取加好友权限
获取当前用户的加好友权限。
javascript
const res = await RongIMLib.getFriendAddPermission();
console.info('获取加好友权限结果：', res);
好友申请
同意加为好友
收到添加好友请求后，用户同意后成为好友关系。
在收到添加好友请求后，调用 acceptFriendApplication 接受好友请求，双方都会收到 Events.FRIEND_ADDED 监听，说明好友添加成功。
同时好友申请列表中的好友请求状态变为已同意。
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | string | 是 | 目标用户 ID |
javascript
const userId = 'UserId';
const res = await RongIMLib.acceptFriendApplication(userId);
console.info('同意加为好友结果：', res);
拒绝加为好友
收到添加好友请求后，用户可以拒绝成为好友，并发送拒绝好友系统消息。拒绝后，好友申请列表中状态变为已拒绝，同时双方都能收到拒绝的好友状态监听。
拒绝成功后，双方都会收到 Events.FRIEND_APPLICATION_STATUS_CHANGED 监听，好友请求状态为已拒绝。
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | string | 是 | 拒绝成为好友的用户 ID |
javascript
const userId = 'UserId';
const res = await RongIMLib.refuseFriendApplication(userId, reason);
console.info('拒绝加为好友结果：', res);
分页获取好友请求列表
查看所有请求添加用户为好友和用户发送的所有申请添加好友的记录信息。
- 此接口不支持返回请求总数。
- 好友请求处理有效期为 7 天，融云服务端最多存储 7 天的请求数据，超过 7 天后需要重新发起请求。
提示
- 好友请求处理有效期为 7 天，融云服务端最多存储 7 天的请求数据，超过 7 天后需要重新发起请求。
- Electron 支持请求类型（types）和请求状态（status）的条件查询能力，Web 端暂不支持。
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| option | IPagingQueryOption | 否 | 分页拉取参数，默认 50 条，最大不超过 100 条。 |
| types | FriendApplicationType | 否 | 仅在 Electron 平台支持，请求类型：1:发送的好友请求、2:接收的好友请求。 |
| status | FriendApplicationStatus | 否 | 仅在 Electron 平台支持，请求状态 |
javascript
// Web 传递无效
const types = [FriendApplicationType.SENT, FriendApplicationType.RECEIVED];
// Web 传递无效
const status = [FriendApplicationStatus.ACCEPTED];
const option = {
count: 50,
pageToken: '',
order: false,
};
const res = await RongIMLib.getFriendApplications(option, types, status);
console.info('好友请求列表：', res);
获取好友列表
获取好友列表
获取当前用户的好友列表。option 参数仅在 Web 平台有效，Electron 获取全部列表如需分页展示需要业务层按照展示逻辑自行截取。
提示
Web 平台不传递 pageToken 时默认查询第一页。分页查询需要下一页查询时输入对应的 pageToken，pageToken 通过接口返回结果中获取。
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| directionType | QueryFriendsDirectionType | 是 | 好友类型 |
| option | IPagingQueryOption | 否 | Electron 获取全部，仅 Web 平台有效，分页拉取参数，默认 50 条，最大不超过 100 条。 |
javascript
const directionType = QueryFriendsDirectionType.BOTH;
const option = {
count: 50,
pageToken: '',
order: false,
};
const friendsList = await RongIMLib.getFriends(directionType, option);
console.info('好友列表：', friendsList);
根据用户 ID 获取好友信息
您可以使用 getFriendsInfo 根据用户 ID 获取好友信息。
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userIds | string[] | 是 | 用户 ID 列表，一次最多获取 100 个好友信息。 |
javascript
const userIds = ['user1', 'user2', 'user3'];
const friendsInfo = await RongIMLib.getFriendsInfo(userIds);
console.info('好友信息列表：', friendsInfo);
根据好友昵称搜索好友信息
您可以使用 searchFriendsInfo 根据好友昵称搜索好友信息。
搜索时默认先搜好友备注名 remark，再搜索好友名称 name。只要其中一个字段匹配成功，即返回搜索结果。
注意
此接口仅支持 Electron 平台。
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 是 | 用户昵称关键字，不能为空最长不超过 64 个字符，支持模糊搜索查询，不支持搜索纯空格。 |
javascript
const name = 'userName';
const searchResults = await RongIMLib.searchFriendsInfo(name);
console.info('搜索好友列表结果：', searchResults);