每日钉钉API探索：chooseDepartments专注于部门维度的选择接口

2026/8/10 2:39:03 拓冰建站浏览量

在企业级应用开发过程中，针对组织架构中的部门进行操作是非常常见的需求。今天我们要介绍的是钉钉的chooseDepartments API，它允许用户以部门为单位进行选择，并返回所选部门的相关信息。

📌 功能概述

chooseDepartments API主要用于选取企业内部的一个或多个部门，并返回这些部门的详细信息，包括部门ID、名称以及该部门下的员工数量等。与以人为维度的选择不同，此API聚焦于部门层级的操作，非常适合用于权限设置、通知发送等场景。

💻 支持平台

平台	版本要求
Android	6.0.0+
iOS	6.0.0+
Harmony	7.0.0+
Mac	6.0.0+
Windows	6.0.0+

注意：网页应用（原H5微应用）和小程序均从6.0.0版本开始支持此功能。

📲 应用类型支持

企业内部应用：支持
第三方企业应用：支持
第三方个人应用：支持

这意味着无论你是为企业内部定制的应用程序，还是面向外部市场的应用程序，都可以利用这个API来增强你的应用功能。

🔒 鉴权规则

在H5应用中，需通过调用dd.config完成鉴权后使用。
对于小程序应用，可以直接调用无需额外鉴权，简化了开发流程。

⚙️ 参数说明

继承通用输入对象，并扩展以下关键参数：

参数名	类型	必填	示例值	描述
`title`	String	否	“标题”	选择页面的标题。
`multiple`	Boolean	否	true	是否允许多选：true - 多选；false - 单选（默认）。
`limitTips`	String	否	“选择数量不能超过20个”	超过限定数量返回的提示内容。
`maxDepartments`	Number	否	100	最大可选部门数。
`pickedDepartments`	Array	否	[“deptId0”,“deptId1”]	已选的部门id列表。
`disabledDepartments`	Array	否	[“deptId0”,“deptId1”]	不可选的部门id列表。
`requiredDepartments`	Array	否	[“deptId0”,“deptId1”]	必选部门（不可取消选中状态）。
`appId`	String	H5应用必填	微应用agentId	H5应用必填。
`corpId`	String	H5应用必填	企业的corpId	H5应用必填。

📤 返回结果

成功调用后，将返回包含选定部门信息的对象，具体字段如下：

字段名	类型	示例值	描述
`userCount`	Number	5	所选部门下所有员工的数量。
`departments`	Array	[{ “id”: “68094649x”, “name”: “人事部”, “number”: 10 }]	包含部门ID、名称及人数的对象数组。
`departmentsCount`	Number	2	所选部门的数量。

🛠 使用示例

以下是调用chooseDepartments的一个简单示例：

dd.chooseDepartments({appId: 'appId示例值',title: '选择部门',corpId: 'corpId示例值',multiple: true,limitTips: '选择数量不能超过20个',maxDepartments: 100,pickedDepartments: ['deptId0', 'deptId1'],disabledDepartments: ['deptId0', 'deptId1'],requiredDepartments: ['deptId0', 'deptId1'],success: (res) => {console.log('选择的部门:', res);// 输出格式：// {//   userCount: 5,//   departments: [{ id: '68094649x', name: '人事部', number: 10 }],//   departmentsCount: 2// }},fail: () => {},complete: () => {},
});

希望今天的介绍能帮助你更好地理解和使用chooseDepartments API。未来我们将继续探讨更多实用的钉钉API，敬请期待！

建站实战干货