网易云信即时通讯 SDK（NetEase IM SDK，以下简称 NIM SDK）支持好友信息的管理，支持添加/删除好友，接受/拒绝好友申请，设置好友信息等。

本文介绍好友信息相关的 API。更多好友相关功能请参考开发指南文档 好友关系。

API 概览

好友关系监听

API	说明	起始版本
listen	注册好友关系相关监听器	v10.3.0
cancel	取消注册好友关系相关监听器	v10.3.0

好友关系操作

API	说明	起始版本
addFriend	添加好友	v10.3.0
deleteFriend	删除好友	v10.3.0
acceptAddApplication	接受好友申请	v10.3.0
rejectAddApplication	拒绝好友申请	v10.3.0
setFriendInfo	设置好友信息	v10.3.0
getFriendList	获取好友列表	v10.3.0
getFriendByIds	根据账号 ID 获取好友信息列表	v10.3.0
checkFriend	根据账号 ID 查询好友状态	v10.3.0
getAddApplicationList	获取申请添加好友信息列表	v10.3.0
getAddApplicationUnreadCount	获取未读的好友申请数量	v10.3.0
setAddApplicationRead	设置好友申请已读	v10.3.0
searchFriendByOption	根据关键字信息搜索好友信息	v10.3.0
clearAllAddApplication	清空所有好友申请	v10.5.0
deleteAddApplication	删除指定的好友申请	v10.9.0

接口类

FriendService 类提供好友关系相关接口，包括注册好友关系监听，添加、删除好友，接受、拒绝好友申请，获取、设置好友信息等接口。

listen

接口描述

注册好友关系相关监听。

注册成功后，当事件发生时，SDK 会返回对应的回调。

• 建议在初始化后调用该方法。
• 全局只需注册一次。
• 该方法为同步。

回调事件

• onFriendAdded：添加好友成功回调，返回添加成功的好友信息列表，包括本端直接添加好友和其他端同步添加的好友。
• onFriendDeleted：删除好友回调，返回删除的好友信息，包括本端直接删除好友、其他端同步删除的好友以及对方好友删除自己。
• onFriendAddApplication：申请添加好友回调，返回申请添加为好友的信息。
• onFriendAddRejected：被对方拒绝好友添加申请的回调，被拒绝的好友申请信息。
• onFriendInfoChanged：好友信息更新回调，返回变更的好友信息，包括本端直接更新的好友信息和其他端同步更新的好友信息。

示例代码

dartsubsriptions.add(NimCore.instance.friendService.onFriendAddApplication.listen((e){
    //do something
  }));

  subsriptions.add(NimCore.instance.friendService.onFriendAdded.listen((e){
    //do something
  }));

  subsriptions.add(NimCore.instance.friendService.onFriendAddRejected.listen((e){
    //do something
  }));

  subsriptions.add(NimCore.instance.friendService.onFriendDeleted.listen((e){
    //do something
  }));

  subsriptions.add(NimCore.instance.friendService.onFriendInfoChanged.listen((e){
    //do something
  }));

cancel

接口描述

取消注册好友关系相关监听。

该方法为同步。

示例代码

dartsubsriptions.forEach((subsription) {
      subsription.cancel();
    });

addFriend

接口描述

添加好友。添加好友分为以下两种模式（NIMFriendAddMode）：

• 直接添加为好友，对应枚举为 nimFriendModeTypeAdd。

  该模式下，调用接口成功后，本端和对端（被添加的好友）都会收到 onFriendAdded 回调。

• 请求添加对方为好友，需要对方验证通过才能添加，对应枚举为 nimFriendModeTypeApply。

  该模式下，调用接口成功后，对端（被添加的好友）会收到 onFriendAddApplication 回调。

参数说明

dartFuture<NIMResult<void>> addFriend(
    String accountId, NIMFriendAddParams? params) async {
  return _platform.addFriend(accountId, params);
}

参数名称	类型	是否必填	说明
accountId	String	是	需要添加为好友的账号 ID。
params	NIMFriendAddParams	是	添加好友的配置参数。

示例代码

dartawait NimCore.instance.friendService.addFriend(accountId, params);

返回值

NIMResult<void>

相关回调

• onFriendAdded：添加好友回调
• onFriendAddApplication：好友添加申请的回调

deleteFriend

接口描述

删除好友。当前的删除是指双向删除，即当一个用户将另一个用户从好友列表中删除时，双方的好友关系都会被解除。

调用接口成功后，本端和对端（被删除的好友）都会收到 onFriendDeleted 回调。

参数说明

dartFuture<NIMResult<void>> deleteFriend(
    String accountId, NIMFriendDeleteParams? params) async {
  return _platform.deleteFriend(accountId, params);
}

参数名称	类型	是否必填	说明
accountId	String	是	需要删除的好友的账号 ID。
params	NIMFriendDeleteParams	是	删除好友的配置参数。

示例代码

dartawait NimCore.instance.friendService.deleteFriend(accountId, params);

返回值

NIMResult<void>

相关回调

onFriendDeleted：删除好友回调

acceptAddApplication

接口描述

接受好友申请。调用接口成功后，本端和对端（发起好友申请的用户）都会收到 onFriendAdded 回调。

操作完成后，SDK 内部会更新申请添加好友信息（applicationInfo）相关操作的状态（NIMFriendAddApplicationStatus）并处理相关错误码。

参数说明

dartFuture<NIMResult<void>> acceptAddApplication(
    NIMFriendAddApplication application) async {
  return _platform.acceptAddApplication(application);
}

参数名称	类型	是否必填	说明
application	NIMFriendAddApplication	是	申请添加好友的相关信息。

示例代码

dartawait NimCore.instance.friendService.acceptAddApplication(application);

返回值

NIMResult<void>

相关回调

onFriendAdded：添加好友回调

rejectAddApplication

接口描述

拒绝好友申请。调用接口成功后，对端（发起好友申请的用户）会收到 onFriendAddRejected 回调。

操作完成后，SDK 内部会更新申请添加好友信息（applicationInfo）相关操作的状态（NIMFriendAddApplicationStatus）并处理相关错误码。

参数说明

dartFuture<NIMResult<void>> rejectAddApplication(
    NIMFriendAddApplication application, String postscript) async {
  return _platform.rejectAddApplication(application, postscript);
}

参数名称	类型	是否必填	说明
application	NIMFriendAddApplication	是	申请添加好友的相关信息。
postscript	String	否	拒绝好友申请的附言。

示例代码

dartawait NimCore.instance.friendService.rejectAddApplication(application, postscript);

返回值

NIMResult<void>

相关回调

onFriendAddRejected：被对方拒绝好友添加申请的回调

setFriendInfo

接口描述

设置好友信息。调用该接口成功后，本端会收到 onFriendInfoChanged 回调。

参数说明

dartFuture<NIMResult<void>> setFriendInfo(
    String accountId, NIMFriendSetParams params) async {
  return _platform.setFriendInfo(accountId, params);
}

参数名称	类型	是否必填	说明
accountId	String	是	申请添加好友的相关信息。
params	NIMFriendSetParams	否	设置好友信息的配置参数。

示例代码

dartawait NimCore.instance.friendService.setFriendInfo(accountId, params);

返回值

NIMResult<void>

相关回调

onFriendInfoChanged：好友信息更新回调

getFriendList

接口描述

本地查询好友列表。

用户登录后，SDK 开始同步好友信息，建议同步完成后，调用该接口拉取完整的好友信息列表。

参数说明

dartFuture<NIMResult<List<NIMFriend>>> getFriendList() async {
  return _platform.getFriendList();
}

示例代码

dartawait NimCore.instance.friendService.getFriendList();

返回值

NIMResult<List<NIMFriend>>：好友信息列表

相关回调

无

getFriendByIds

接口描述

根据账号 ID 获取好友信息列表，只返回账号 ID 存在的好友信息。

参数说明

dartFuture<NIMResult<List<NIMFriend>>> getFriendByIds(
    List<String> accountIds) async {
  return _platform.getFriendByIds(accountIds);
}

参数名称	类型	是否必填	说明
accountIds	List<String>	是	需要查询信息的好友 ID 列表。

示例代码

dartawait NimCore.instance.friendService.getFriendByIds(accountIds);

返回值

NIMResult<List<NIMFriend>>：好友信息列表

相关回调

无

checkFriend

接口描述

根据账号 ID 查询好友状态。

参数说明

dartFuture<NIMResult<Map<String, bool>>> checkFriend(
    List<String> accountIds) async {
  return _platform.checkFriend(accountIds);
}

参数名称	类型	是否必填	说明
accountIds	List<String>	是	需要查询好友状态的账号 ID 列表。

示例代码

dartawait NimCore.instance.friendService.checkFriend(accountIds);

返回值

NIMResult<Map<String, bool>>：好友关系

相关回调

无

getAddApplicationList

接口描述

获取申请添加好友信息列表。

SDK 将按照从新到旧的顺序进行查询。

参数说明

dartFuture<NIMResult<NIMFriendAddApplicationResult>> getAddApplicationList(
    NIMFriendAddApplicationQueryOption option) async {
  return _platform.getAddApplicationList(option);
}

参数名称	类型	是否必填	说明
option	NIMFriendAddApplicationQueryOption	是	查询申请添加好友信息的相关配置参数。

示例代码

dartawait NimCore.instance.friendService.getAddApplicationList(option);

返回值

NIMResult<NIMFriendAddApplicationResult>：添加好友申请的结果信息

相关回调

无

getAddApplicationUnreadCount

接口描述

获取未读的好友申请（状态为未处理）数量。

参数说明

dartFuture<NIMResult<int>> getAddApplicationUnreadCount() async {
  return _platform.getAddApplicationUnreadCount();
}

示例代码

dartawait NimCore.instance.friendService.getAddApplicationUnreadCount();

返回值

NIMResult<int>

相关回调

无

setAddApplicationRead

接口描述

设置好友申请已读。

调用该方法，历史未读的好友申请数据均标记为已读。

参数说明

dartFuture<NIMResult<void>> setAddApplicationRead() async {
  return _platform.setAddApplicationRead();
}

示例代码

dartawait NimCore.instance.friendService.setAddApplicationRead();

返回值

NIMResult<void>

相关回调

无

searchFriendByOption

接口描述

根据关键字信息搜索好友信息。

参数说明

dartFuture<NIMResult<List<NIMFriend>>> searchFriendByOption(
    NIMFriendSearchOption friendSearchOption) async {
  return _platform.searchFriendByOption(friendSearchOption);
}

参数名称	类型	是否必填	说明
friendSearchOption	NIMFriendSearchOption	是	好友搜索的相关配置参数。

示例代码

dartawait NimCore.instance.friendService.searchFriendByOption(friendSearchOption);

返回值

NIMResult<List<NIMFriend>>：好友信息列表

相关回调

无

clearAllAddApplication

接口描述

清空所有好友申请。

调用该方法，历史所有的好友申请数据均被清空。

参数说明

dartFuture<NIMResult<void>> clearAllAddApplication()

无参数。

示例代码

dartawait NimCore.instance.friendService.clearAllAddApplication();

返回值

NIMResult<void>

相关回调

无

deleteAddApplication

接口描述

删除指定的好友申请。

参数说明

dartFuture<NIMResult<void>> deleteAddApplication( NIMFriendAddApplication application )

参数名称	类型	是否必填	说明
application	NIMFriendAddApplication	是	申请添加好友的相关信息。

示例代码

dartNimCore.instance.friendService.deleteAddApplication(application).then((result){

    });

返回值

NIMResult<void>

相关回调

无