好友管理

本文档旨在指导开发者如何使用融云即时通讯 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 接口主动订阅，只需在 SDK 建立连接前设置订阅监听器。

监听回调中通过 SubscribeType 区分事件类型：

• SubscribeType.FRIEND_ONLINE_STATUS 表示好友在线状态变更
• SubscribeType.FRIEND_PROFILE_CHANGED 表示好友资料变更

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、手机号等方式搜索目标用户，选择是否填写申请附言，调用 addFriend 提交好友请求。

提示

单个用户最多可以添加 3000 个好友。

加好友权限说明

AppKey 默认用户信息权限为 需要用户同意添加好友。 下面列举了 AppKey 级权限与 用户 级权限综合说明：

AppKey 权限	用户级权限	结果
都不可见、仅好友可见、所有人可见	未设置	以 AppKey 权限设置为准
都不可见、仅好友可见、所有人可见	设置为（都不可见、所有人可见、仅好友可见）	以用户权限设置为准

不同权限流程说明

场景1：无需验证直接添加

1. 双方调用 setFriendListener 注册好友事件监听。
2. 用户 B 设置加好友权限为：任何人直接添加（见 FriendAddPermission）
3. 用户 A 调用 addFriend，接口返回 processCode 为 0，表示已直接成为好友。双方收到 Events.FRIEND_ADDED 事件。

场景2：需验证同意

1. 双方调用 setFriendListener 注册好友事件监听。
2. 用户 B 设置加好友权限为： 需要验证（见 FriendAddPermission）。
3. 用户 A 调用 addFriend，接口返回 processCode 为 25461，表示待验证。双方收到 Events.FRIEND_APPLICATION_STATUS_CHANGED 事件。
4. 用户 B 通过监听收到申请，可调用：
   • acceptFriendApplication 同意，双方收到 Events.FRIEND_ADDED
   • refuseFriendApplication 拒绝，双方收到 Events.FRIEND_APPLICATION_STATUS_CHANGED 状态为 REFUSED

接口

JavaScript

RongIMLib.addFriend(userId, directionType, extra)

参数说明

参数名	类型	必填	说明
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 事件。

接口

JavaScript

RongIMLib.deleteFriends(userIds, directionType);

参数说明

参数名	类型	必填	说明
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。

接口

JavaScript

RongIMLib.setFriendInfo(userId, remark)

参数说明

参数名	类型	必填	说明
userId	string	是	好友用户 ID
remark	string	否	好友备注名，最多为 64 个字符。不传或为空时清除备注名
extProfile	{[key: string]: string}	否	扩展信息，开发者可根据自身业务需求添加自定义扩展属性，默认最多可设置 10 个扩展信息。自定义属性需要通过开发者后台或 API 设置后才能使用，否则返回设置失败

示例代码

javascript

const userId = 'UserId';
const remark = 'Best Friend';

RongIMLib.setFriendInfo(userId, remark);

检查好友关系

调用 checkFriends 可以检查好友关系，目前仅支持双向好友检查。

接口

javascript

RongIMLib.checkFriends(userId, directionType);

参数说明

参数名	类型	必填	说明
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);

设置加好友权限

调用 setFriendAddPermission 设置当前用户的加好友权限，未设置时以 AppKey 默认的加好友权限为准。

接口

JavaScript

RongIMLib.setFriendAddPermission(permission)

参数说明

参数名	类型	必填	说明
permission	FriendAddPermission	是	加好友权限，参照 FriendAddPermission

示例代码

javascript

const permission = FriendAddPermission.Free; 

const res = await RongIMLib.setFriendAddPermission(permission);
console.info('设置当前用户的加好友权限结果：', res);

获取加好友权限

调用 getFriendAddPermission 获取当前用户的加好友权限。

接口

javascript

RongIMLib.getFriendAddPermission();

参数说明

无

示例代码

javascript

const res = await RongIMLib.getFriendAddPermission();
console.info('获取加好友权限结果：', res);

好友申请

同意加为好友

收到添加好友请求后，用户同意后成为好友关系。

在收到添加好友请求后，调用 acceptFriendApplication 接受好友请求，双方都会收到 Events.FRIEND_ADDED 监听，说明好友添加成功。

同时好友申请列表中的好友请求状态变为已同意。

接口

javascript

RongIMLib.acceptFriendApplication(userId)

参数说明

参数名	类型	必填	说明
userId	string	是	目标用户 ID

示例代码

javascript

const userId = 'UserId';

const res = await RongIMLib.acceptFriendApplication(userId);
console.info('同意加为好友结果：', res);

拒绝加为好友

收到添加好友请求后，用户可以调用 refuseFriendApplication 拒绝成为好友，并发送拒绝好友系统消息。拒绝后，好友申请列表中状态变为已拒绝，同时双方都能收到拒绝的好友状态监听。

拒绝成功后，双方都会收到 Events.FRIEND_APPLICATION_STATUS_CHANGED 监听，好友请求状态为已拒绝。

接口

javascript

RongIMLib.refuseFriendApplication(userId, reason);

参数说明

参数名	类型	必填	说明
userId	string	是	拒绝成为好友的用户 ID
reason	string	否	拒绝原因，长度不超过 128 个字符

示例代码

javascript

const userId = 'UserId';

const res = await RongIMLib.refuseFriendApplication(userId, reason);
console.info('拒绝加为好友结果：', res);

分页获取好友请求列表

调用 getFriendApplications 查看所有请求添加用户为好友和用户发送的所有申请添加好友的记录信息。

提示

• 好友请求处理有效期为 7 天，融云服务端最多存储 7 天的请求数据，超过 7 天后需要重新发起请求。
• 此接口不支持返回请求总数。
• Electron 支持请求类型（types）和请求状态（status）的条件查询能力，Web 端暂不支持。

接口

JavaScript

 RongIMLib.getFriendApplications(option, types, status)

参数说明

参数名	类型	必填	说明
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);

获取好友列表

获取好友列表

调用 getFriends 获取当前用户的好友列表。

接口

javascript

RongIMLib.getFriends(directionType, option)

参数说明

提示

Web 平台不传递 pageToken 时默认查询第一页。分页查询需要下一页查询时输入对应的 pageToken，pageToken 通过接口返回结果中获取。

参数名	类型	必填	说明
directionType	QueryFriendsDirectionType	是	好友类型
option	IPagingQueryOption	否	仅 Web 平台有效，分页拉取参数，默认 50 条，最大不超过 100 条。Electron 获取全部列表如需分页展示需要业务层按照展示逻辑自行截取。

示例代码

javascript

const directionType = QueryFriendsDirectionType.BOTH; 
const option = {
  count: 50,
  pageToken: '',
  order: false,
};

const friendsList = await RongIMLib.getFriends(directionType, option);
console.info('好友列表：', friendsList);

根据用户 ID 获取好友信息

调用 getFriendsInfo 获取好友信息。

接口

javascript

RongIMLib.getFriendsInfo(userIds)

参数说明

参数名	类型	必填	说明
userIds	string[]	是	用户 ID 列表，一次最多获取 100 个好友信息。

示例代码

javascript

const userIds = ['user1', 'user2', 'user3'];

const friendsInfo = await RongIMLib.getFriendsInfo(userIds);
console.info('好友信息列表：', friendsInfo);

根据好友昵称搜索好友信息

调用 searchFriendsInfo 搜索好友信息。

注意

• 此接口仅支持 Electron 平台。
• 搜索时默认先搜好友备注名 remark，再搜索好友名称 name。只要其中一个字段匹配成功，即返回搜索结果。

接口

javascript

RongIMLib.searchFriendsInfo(name)

参数说明

参数名	类型	必填	说明
name	string	是	用户昵称关键字，不能为空最长不超过 64 个字符，支持模糊搜索查询，不支持搜索纯空格。

示例代码

javascript

const name = 'userName';

const searchResults = await RongIMLib.searchFriendsInfo(name);
console.info('搜索好友列表结果：', searchResults);