Appearance
listGet
最后更新时间 2026-04-17
list(options) 用于获取当前账号的好友列表与同步状态。
- 接口标识：
friend.listGet - 请求类型：
FriendListGetRequest - 当前状态：可接入
该接口用于拉取当前账号的好友集合，并返回当前列表的同步状态与增量标记，适合作为联系人页、发起聊天选人页或好友同步入口。
注意事项
- 调用前必须已完成 bootstrap 和 login。
- 该接口返回的是好友列表，不包含完整的组织通讯录。
- 返回的 sync_marker 可作为后续增量更新的依据，业务方不应自行伪造。
- 当前实现阶段为 浅实现，当前可接入状态为 可接入。
- 当前方法已纳入
release/phase0正式发布承诺。
支持说明
该接口用于四端统一的好友列表加载与同步展示。
| 应用能力 | Android | iOS | Harmony | PC | 发布状态 |
|---|---|---|---|---|---|
| SDK Wrapper | 支持 | 支持 | 支持 | 支持 | 已纳入 release/phase0 |
发布基线：
- android: Android 8.0+ (API 26)
- ios: iOS 15+
- harmony: HarmonyOS NEXT API 12+
- pc: Host OS with supported native bridge runtime
输入
该接口接收 FriendListGetRequest 请求对象，字段定义如下。
| 名称 | 数据类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
owner_account_id | String | 是 | - | 好友列表所属账号标识。 |
说明
请求对象由业务方传入，用于触发上层 SDK API 调用。平台 wrapper 可以按各自语言习惯封装参数对象，但字段语义必须与 FriendListGetRequest 保持一致。
输出
该接口成功后返回 FriendListGetResponse 业务结果，字段定义如下。
| 名称 | 数据类型 | 描述 |
|---|---|---|
owner_account_id | String | 本次好友列表查询所属的账号标识。 |
entries | Vec<FriendGetProfileResponse> | 好友资料条目列表。 |
total_count | usize | 本次返回的好友条目总数。 |
list_state | String | 好友列表同步状态；浅实现返回 synced。 |
sync_marker | Option<String> | 用于下一次增量同步好友列表的标记。 |
FriendGetProfileResponse
来源：src/public_api/friend/mod.rs
| 名称 | 数据类型 | 描述 |
|---|---|---|
friend_id | String | 好友的唯一标识。 |
display_name | String | 好友展示名称。 |
avatar_reference | Option<String> | 好友头像资源引用；浅实现以 avatar://friend-... 形式返回。 |
relationship_state | String | 当前账号与该好友的关系状态。 |
availability_state | String | 好友当前可达或在线状态。 |
remark | Option<String> | 当前账号对该好友设置的备注名；未设置时为空。 |
source_state | String | 该好友资料的来源状态；当前浅实现来自 address-book 语义。 |
状态与前置条件
- 调用前置条件：
runtime.bootstrap、auth.login - 当前 SDK 状态要求：当前用户会话有效。
- 调用成功后状态：成功后不会改变 SDK 状态，但会提供当前好友列表同步快照。
- 建议后续调用：
friend.getProfile、contact.search
示例代码
平台调用示例
| 平台 | 正式入口 | 绑定方式 | 错误返回方式 |
|---|---|---|---|
| Android | com.robin.sdk.RobinSdk | kotlin-java-facade | result-error-object |
| iOS | RobinSdk | swift-facade | throws-result-enum |
| Harmony | RobinSdk | arkts-js-facade | result-code-object |
| PC | robin_sdk_bridge | native-bridge-facade | bridge-error-code |
说明
当前仓库尚未提供该方法的真实平台 facade 调用代码片段。你可以先根据以下真实入口信息接入平台 wrapper；后续如补充 docs/examples/<platform>/friend-list-get.*，页面会自动渲染对应平台示例。
错误码
| 错误码 | 描述 | 排查建议 |
|---|---|---|
action_not_enabled | 当前接口能力未开放，或当前发布范围不支持该调用。 | 检查接口是否已纳入当前发布范围，并确认目标平台已支持该能力。 |