在企业级应用开发中，有时我们需要让用户从一个预定义的用户列表中选择特定的联系人。今天要介绍的是钉钉提供的chooseUserFromList API，它允许开发者创建一个自定义的用户选择界面，从中选取单个联系人。
📌 功能概述
chooseUserFromList API主要用于提供一种便捷的方式让用户从指定的用户列表中选取一名联系人。此功能特别适用于需要精确控制可选用户范围的应用场景，如内部通讯录、任务分配或审批流程等。
💻 支持平台
| 平台 | 版本要求 |
|---|---|
| Android | 6.0.0+ |
| iOS | 6.0.0+ |
| Harmony | 7.0.0+ |
| Mac | 不支持 |
| Windows | 不支持 |
注意：该API目前不支持桌面端（Mac和Windows），主要适用于移动端及H5微应用和小程序。
📲 应用类型支持
- 企业内部应用：支持
- 第三方企业应用：支持
- 第三方个人应用：支持
这意味着无论你是为企业内部定制的应用程序，还是面向外部市场的应用程序，都可以利用这个API来增强你的应用功能。
🔒 鉴权规则
- 在H5应用中，需通过调用
dd.config完成鉴权后使用。 - 对于小程序应用，可以直接调用无需额外鉴权，简化了开发流程。
⚙️ 参数说明
继承通用输入对象，并扩展以下关键参数：
| 参数名 | 类型 | 必填 | 示例值 | 描述 |
|---|---|---|---|---|
title |
String | 否 | “标题” | 选择页面的标题。 |
users |
Array | 是 | [“userId0”,“userId2”] | 自定义可以选择的用户的userId列表。 |
isShowCompanyName |
Boolean | 否 | true | 是否显示公司名称。 |
disabledUsers |
Array | 否 | [“userId0”,“userId2”] | 不可选用户的userId列表。 |
corpId |
String | H5应用必填 | 企业的corpId | H5应用必填。 |
📤 返回结果
成功调用后，将返回包含选定联系人信息的对象，具体字段如下：
| 字段名 | 类型 | 示例值 | 描述 |
|---|---|---|---|
name |
String | “钉小二” | 联系人姓名。 |
avatar |
String | “https://static.dingtalk.com/media/lADPDiCpu12oVqvNApTNApQ_660_660.jpg” | 联系人头像地址。 |
userId |
String | “22055215283702319x” | 用户ID。 |
🛠 使用示例
以下是调用chooseUserFromList的一个简单示例：
dd.chooseUserFromList({
title: '选择联系人',
users: ['userId0', 'userId2'],
corpId: 'corpId示例值',
disabledUsers: ['userId0', 'userId2'],
isShowCompanyName: true,
success: (res) => {
console.log('选择的联系人:', res);
// 输出格式：
// {
// name: '钉小二',
// avatar: 'https://static.dingtalk.com/media/lADPDiCpu12oVqvNApTNApQ_660_660.jpg',
// userId: '22055215283702319x'
// }
},
fail: () => {},
complete: () => {},
});
希望今天的介绍能帮助你更好地理解和使用chooseUserFromList API。未来我们将继续探讨更多实用的钉钉API，敬请期待！