人员选择控件

接口

HttpPost：api/FrontEnd/person-selector/organizations

根据表单人员选择控件的范围配置，获取组织树的下级节点；传入 Keyword 时搜索组织节点。

HttpPost：api/FrontEnd/person-selector/users

根据表单人员选择控件的范围配置，获取指定组织下的人员；传入 Keyword 时搜索人员。接口仅返回人员选择所需的基础字段，不返回手机号、邮箱、身份证等敏感信息。

两个接口均会校验当前登录用户是否有 MenuId 对应菜单的访问权限，且 FieldCode 必须是关联表单中的人员选择控件。

请求参数

获取组织节点

参数名	参数位置	类型	是否必填	说明
Authorization	Header	string	是	调用者身份凭据，传入已获取的 token。
TnCode	Header	string	是	租户编码。
MenuId	Body	string	是	功能菜单编码，用于校验当前用户的菜单访问权限并定位关联表单。
FieldCode	Body	string	是	人员选择控件的字段编码或控件唯一编码。
ParentUnitId	Body	string	否	要加载下级节点的父组织 ID；不传时从根组织开始加载。搜索组织时不参与筛选。
Keyword	Body	string	否	组织搜索关键词；不传或为空时加载组织树节点。
OnlyLeaf	Body	boolean	否	仅在组织搜索时生效；传 true 时只返回叶子组织，默认 false。
ScopeUnitIds	Body	string[]	否	固定组织范围。
Categories	Body	string[]	否	组织类别范围。
OriginatorParses	Body	string[]	否	动态人员范围表达式。
ContainsSub	Body	boolean	否	是否将范围扩展至下级组织，默认 false。

获取人员

参数名	参数位置	类型	是否必填	说明
Authorization	Header	string	是	调用者身份凭据，传入已获取的 token。
TnCode	Header	string	是	租户编码。
MenuId	Body	string	是	功能菜单编码，用于校验当前用户的菜单访问权限并定位关联表单。
FieldCode	Body	string	是	人员选择控件的字段编码或控件唯一编码。
ParentUnitId	Body	string	否	要获取人员的组织 ID；不传时使用根组织。搜索人员时不参与筛选。
Keyword	Body	string	否	人员搜索关键词；不传或为空时按组织获取人员。支持姓名、账号、工号匹配。
ScopeUnitIds	Body	string[]	否	固定组织范围。
Categories	Body	string[]	否	组织类别范围。
OriginatorParses	Body	string[]	否	动态人员范围表达式。
ContainsSub	Body	boolean	否	是否将范围扩展至下级组织，默认 false。
PageIndex	Body	int	否	页码，从 1 开始；不传时默认 1。
PageSize	Body	int	否	每页条数，取值范围 1 到 200；不传时默认 20。

请求示例

加载组织树节点

{
  "MenuId": "46b97a76f61338bd",
  "FieldCode": "Applicant",
  "ParentUnitId": "department-id",
  "ScopeUnitIds": [
    "department-id"
  ],
  "Categories": [],
  "OriginatorParses": [],
  "ContainsSub": true
}

搜索组织

{
  "MenuId": "46b97a76f61338bd",
  "FieldCode": "Applicant",
  "Keyword": "研发",
  "OnlyLeaf": false,
  "ScopeUnitIds": [
    "department-id"
  ],
  "ContainsSub": true
}

获取组织下的人员

{
  "MenuId": "46b97a76f61338bd",
  "FieldCode": "Applicant",
  "ParentUnitId": "department-id",
  "ScopeUnitIds": [
    "department-id"
  ],
  "Categories": [],
  "OriginatorParses": [],
  "ContainsSub": true,
  "PageIndex": 1,
  "PageSize": 20
}

搜索人员

{
  "MenuId": "46b97a76f61338bd",
  "FieldCode": "Applicant",
  "Keyword": "张",
  "ScopeUnitIds": [
    "department-id"
  ],
  "ContainsSub": true,
  "PageIndex": 1,
  "PageSize": 20
}

返回结果

获取组织节点

参数名	类型	说明
objectId	string	组织或群组 ID。
name	string	组织或群组名称。
parentId	string	父节点 ID。
unitType	string	节点类型，例如 OrganizationUnit、Group。
hasChildren	boolean	是否存在可继续加载的子节点。

返回示例（成功）

[
  {
    "objectId": "sub-department-id",
    "name": "研发一部",
    "parentId": "department-id",
    "unitType": "OrganizationUnit",
    "hasChildren": true
  }
]

获取人员

参数名	类型	说明
Datas	array	人员数据集合。
Datas[].objectId	string	人员 ID。
Datas[].code	string	人员登录账号。
Datas[].name	string	人员名称。
Datas[].parentId	string	人员所属组织 ID。
Datas[].parentName	string	人员所属组织名称。
PagingInfo	object	分页信息。
PagingInfo.PageIndex	int	当前页码。
PagingInfo.PageSize	int	每页条数。
PagingInfo.PageCount	int	总页数。
PagingInfo.DataCount	int	符合条件的人员总数。

返回示例（成功）

{
  "Datas": [
    {
      "objectId": "user-id",
      "code": "zhangsan",
      "name": "张三",
      "parentId": "department-id",
      "parentName": "研发一部"
    }
  ],
  "PagingInfo": {
    "PageIndex": 1,
    "PageSize": 20,
    "PageCount": 1,
    "DataCount": 1
  }
}

返回示例（失败）

{
  "Code": 500,
  "Message": "当前用户无权访问该菜单",
  "ExceptionSeqNo": null,
  "Result": null,
  "Status": 3,
  "MessageShowType": null
}

调用说明

• 当前登录用户由 Authorization 令牌识别，接口不接受调用方指定查询用户。
• ScopeUnitIds、Categories、OriginatorParses 和 ContainsSub 的含义与原 /Organization 人员选择接口的 ChildDeptAndGroupRequest 一致，应由表单人员控件的人员范围配置解析后传入。
• 人员控件开启“过滤组”时，组织节点结果会自动排除群组，调用方无需额外传入过滤参数。
• 组织和人员均按启用状态查询；人员结果还会按当前用户的组织角色可见范围过滤。
• 人员搜索结果按人员排序号和名称排序。按组织加载人员时，是否递归加载子组织由系统设置 OrgDeptChildUserType 决定。
• PageIndex 和 PageSize 不合法时返回：分页参数不合法。
• 用户无菜单权限时返回：当前用户无权访问该菜单；字段不是人员控件时返回：字段[FieldCode]不是人员选择控件。