Microsoft Graph 工具包中的人员选取器组件

可以使用 mgt-people-picker Web 组件搜索人员、组或两者。 默认情况下,组件搜索组织中的所有用户和用户,但你可以将行为更改为同时搜索组或仅搜索组。 还可以将搜索筛选到特定组。 还可以允许用户输入和选择任何电子邮件地址。

示例

以下示例显示了 组件 mgt-people-picker 。 开始搜索名称以查看结果呈现,并使用代码编辑器查看 属性 如何更改组件的行为。

属性

默认情况下, mgt-people-picker 组件从 /me/people/users 终结点提取人员。 使用以下属性更改此行为。

属性 属性 说明
show-max showMax 一个数字值,指示要显示的最大人数。 默认值为 6。
group-id groupId 属于 Microsoft Graph 定义的组的字符串值,用于进一步筛选搜索结果。
transitive-search transitiveSearch 一个布尔值,用于执行可传递搜索,返回所有嵌套成员的平面列表 - 默认情况下不使用可传递搜索。
type type 要搜索的实体类型。 可用选项包括: persongroupany。 默认值为 any。 如果此属性设置为 groupgroup-id 设置为 或 group-ids ,则 userFilterspeopleFilters 无效。
user-type userType 要搜索的用户类型。 可用选项包括: anyuser 用于组织用户或 contact 联系人。 默认值为 any
group-type groupType 要搜索的组类型。 可用选项包括:unified、、securitydistributionmailenabledsecurityany。 默认值为 any。 如果 type 属性设置为 person,则此属性不起作用。 此属性接受以逗号分隔的值列表;属性接受数组或值。
selected-people selectedPeople 所选人员数组。 设置此值以编程方式选择人员。
people people 在搜索结果中找到并呈现的人员数组
占 位 符 占 位 符 显示用于说明如何使用组件的默认文本。 默认值为 Start typing a name
default-selected-user-ids defaultSelectedUserIds 当提供逗号分隔Microsoft Graph 用户 ID 的字符串时,组件会在初始化时按所选方式呈现相应的用户。
default-selected-group-ids defaultSelectedGroupIds 与 default-selected-user-id 类似,当提供逗号分隔Microsoft Graph 组 ID 的字符串时,组件会在初始化时呈现所选的相应组。
selection-mode selectionMode 用于指示是允许选择多个项 (用户或组) 还是仅允许单个项目。 可用选项包括: singlemultiple。 默认值为 multiple
禁用 禁用 设置是否禁用人员选取器。 禁用后,用户无法搜索或选择人员。 默认值为“false”。
disable-images disableImages 设置是否禁用人员图像的提取和显示。 设置为 true时,将改为显示用户姓名缩写。 默认值为“false”。
person-card personCardInteraction 设置显示所选人员的人员卡片的行为。 允许的值为 nonehoverclick。 默认值为“none”。
allow-any-email allowAnyEmail 指示人员选取器是否可以在不选择人员的情况下接受电子邮件地址。 默认值为 false。 键入完电子邮件地址后,可以按逗号 () , 、分号 () ; 、tab 或输入键进行添加。
user-ids userIds 逗号分隔的用户 ID 字符串。 它们仅在键入查询时显示在下拉菜单或搜索结果中。 例如, 48d31887-5fad-4d73-a9f5-3c356e68a038,24fcbca3-c3e2-48bf-9ffc-c7f81b81483d 仅当输入处于焦点时,才会在下拉列表中显示两个用户。 键入搜索文本时,它将返回仅与两个用户 ID 中的用户匹配的结果。
user-filters userFilters 指定查询用户终结点时要使用的筛选条件。 它要求 user-type 将 设置为 usercontact。 默认情况下, user-typeany ,并引导在终结点块中 people 执行查询。 示例:user-filters="startsWith(displayName,'a')"。 此特性是可选的。 详细了解对 目录对象的用户属性进行筛选的支持

如果仅 User.ReadBasic.All 使用 权限,可用属性的列表将受到限制,组件会相应地进行调整。 在 User.ReadBasic.All 范围下,限制为以下属性:id、、displayNamegivenNamemailsecurityIdentifiersurnameuserPrincipalName。 默认情况下,此组件使用 jobTitledepartment 属性。 属性mail用作正在使用且未呈现其他属性时的User.ReadBasic.All回退jobTitleUser.Read.All使用 权限查询更多属性。
group-filters groupFilters 指定查询 groups 终结点时要使用的筛选条件。 它要求 type 将 设置为 group。 示例:group-filters="startsWith(displayName,'a')"。 此特性是可选的。
people-filters peopleFilters 指定查询 people 终结点时要使用的筛选条件。 它按原样使用。 示例:people-filters="jobTitle eq 'Web Marketing Manager'"。 此特性是可选的。 详细了解 人员资源上的筛选和支持的功能
group-ids groupIds 逗号分隔组 ID 的字符串。 可用结果应限制为指定的组。 显示在下拉菜单上并通过搜索体验的用户应仅来自指定的组 ID。 例如, 02bd9fd6-8f93-4758-87c3-1fb73740a315,06f62f70-9827-4e6e-93ef-8e0f2d9b7b23 仅显示属于这些组的用户。 键入搜索文本时,它将返回仅与两个组 ID 中的用户匹配的结果。 如果 group-id 定义了 ,则不使用此属性。 如果设置了 属性, type 则 默认为 group ,默认情况下 transitive-searchtruegroup-type如果使用 属性设置 , type 可以是 anygrouptype如果 为 person,则不使用 属性。
aria-label ariaLabel 提供的一个字符串,可帮助辅助技术为人员选取器提供上下文。

以下示例显示了 属性 show-max

<mgt-people-picker show-max="4"> </mgt-people-picker>

所选人员

组件的选定人员部分呈现由开发人员或用户选择的每个人。

mgt-people-picker

可以使用以下选项填充所选人员数据:

  • selectedPeople直接设置 属性,如以下示例所示。

    // personObject is the User or Person object from Microsoft Graph
    document.querySelector("mgt-people-picker").selectedPeople.push(personObject);
    
  • selectUsersById()使用 方法,该方法接受Microsoft图形用户 ID 数组,以查找相关用户详细信息以供选择。

    注意: 如果未找到用户 id,则不会为该 id呈现任何数据。

    // id = Microsoft graph User "id"
    document.querySelector("mgt-people-picker").selectUsersById(["id", "id"]);
    
  • selectGroupsById()使用 方法,该方法接受Microsoft图形组 ID 数组,以查找具有关联用户的组 () 。

    // groupid = Microsoft graph group "id"
    document
      .querySelector("mgt-people-picker")
      .selectGroupsById(["groupid", "groupid"]);
    

CSS 自定义属性

组件 mgt-people-picker 定义以下 CSS 自定义属性。

<mgt-people-picker class="people-picker"></mgt-people-picker>
.people-picker {
  --people-picker-selected-option-background-color: orange;
  --people-picker-selected-option-highlight-background-color: red;
  --people-picker-dropdown-background-color: blue;
  --people-picker-dropdown-result-background-color: yellow;
  --people-picker-dropdown-result-hover-background-color: gold;
  --people-picker-dropdown-result-focus-background-color: green;
  --people-picker-no-results-text-color: orange;
  --people-picker-input-background: gray;
  --people-picker-input-border-color: yellow;
  --people-picker-input-hover-background: green;
  --people-picker-input-hover-border-color: red;
  --people-picker-input-focus-background: purple;
  --people-picker-input-focus-border-color: orange;

  --people-picker-input-placeholder-focus-text-color: yellow;
  --people-picker-input-placeholder-hover-text-color: gold;
  --people-picker-input-placeholder-text-color: white;
  --people-picker-search-icon-color: yellow;
  --people-picker-remove-selected-close-icon-color: blue;

  /** Style for the avatar-size in the people-picker **/
  --people-picker-result-person-avatar-size: 50px;
  --people-picker-selected-person-avatar-size: 30px;

  /** You can also change the person tokens **/
  --person-line1-text-color: blue;
  --person-line2-text-color: red;
}

若要了解详细信息,请参阅 设置组件样式

事件

从 组件触发以下事件。

事件 何时发出 自定义数据 可取消 泡沫 使用自定义模板
selectionChanged 用户从所选人员列表中添加或删除人员 所选人员数组,其中一个人可以是 Graph 用户人员或具有包含用户照片 URL 的其他personImage属性的联系人 是,除非重写默认模板

有关处理事件的详细信息,请参阅 事件

模板

mgt-people-picker 支持多个 模板 ,可用于替换组件的某些部分。 若要指定模板,请在组件中包含元素 <template> ,并将 设置为 data-type 以下值之一。

数据类型 数据上下文 说明
违约 null:无数据 用于替代整个组件的呈现的模板。
装载 null:无数据 在发出图形请求时用于呈现选取器状态的模板。
error null:无数据 如果用户搜索未返回任何用户,则使用的模板。
no-data null:无数据 如果用户搜索未返回任何用户,则使用的替代模板。
selected-person person:人员详细信息对象 用于呈现所选人员的模板。
person:人员详细信息对象 用于在下拉列表中呈现人员的模板。

以下示例演示如何使用 error 模板。

<mgt-people-picker>
  <template data-type="error">
    <p>Sorry, no people were found</p>
  </template>
</mgt-people-picker>

Microsoft Graph 权限

此组件可能会根据配置和状态进行许多查询。 为了简单起见,下表将所需的 Microsoft Graph API 和权限拆分为三个部分。 对于每个调用的 API,用户必须至少具有列出的权限之一。

无论用户输入状态如何

配置 权限 API 其他选项
default-selected-user-ids 设置 User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All /users/$ ({userId} 设置 时 user-filters ,会将其作为 $filter 参数添加到请求, $count=true 并在 ConsistencyLevel: 'eventual' 请求上设置标头
default-selected-group-ids 设置 GroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All /组 设置 时 people-filters ,其值作为 $filter 参数添加到请求
当以下配置依赖于user-ids设置时,如果 中存在 的条目,meuser-ids User.Read、User.ReadWrite /我

当不存在用户输入时

配置 权限 API 其他选项
group-id 设置 GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All /groups/${groupId}/members 当 为 persongroup/microsoft.graph.user/microsoft.graph.group 将追加到请求路径时type
group-id set AND transitive-search is true GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All /groups/${groupId}/transitiveMembers 当 为 persongroup/microsoft.graph.user/microsoft.graph.group 将追加到请求路径时type
group-ids set AND type is group GroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All /groups/${id}
group-ids set AND type IS NOT group GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All /groups/${groupId}/members person然后/microsoft.graph.user, 将 追加到请求路径时type
group-ids set AND type IS NOT group AND is transitive-search true GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All /groups/${groupId}/transitiveMembers person然后/microsoft.graph.user, 将 追加到请求路径时type
typegroup ,且均未group-id设置 或group-ids GroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All /组
type 设置为 personany 并且 userIds 已设置 User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All /users/$ ({userId} 设置 时 user-filters ,会将其作为 $filter 参数添加到请求, $count=true 并在 ConsistencyLevel: 'eventual' 请求上设置标头
type将 设置为 personanyuser-filters并且 设置为 或user-typeusercontact User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All /用户 设置 时 user-filters ,会将其作为 $filter 参数添加到请求, $count=true 并在 ConsistencyLevel: 'eventual' 请求上设置标头
type 设置为 personanyuser-filters 并且未设置 或 user-type 设置为 既不 usercontact People.Read、People.Read.All /me/people people-filters 设置为 或 user-type 不是 any 时,$filter参数将添加到请求中。 如果 user-type 不是 contact ,则 X-PeopleQuery-QuerySources: 'Mailbox,Directory' 对请求设置标头

当用户提供搜索词时

配置 权限 API 其他选项
group-id 已设置 GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All /groups/${groupId}/members 当 或 persongroup/microsoft.graph.user/microsoft.graph.group 追加到请求路径时type$filter参数由用户输入值组成
group-id 设置为 ,且 transitive-search 为 true GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All /groups/${groupId}/transitiveMembers 当 或 persongroup/microsoft.graph.user/microsoft.graph.group 追加到请求路径时type$filter参数由用户输入值组成
group-id 未设置为 ,未 type 设置为 personany ,并且 user-type 设置为 anygroup-ids 已设置 GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All /groups/${groupId}/members person然后将 type/microsoft.graph.user 追加到请求路径时,会使用用户输入值组成参数$filter
group-id 未设置为 , type 未设置为 personany 设置为 ,并且 user-type 设置为 anygroup-ids 并且 transitive-search 为 true GroupMember.Read.All、Group.Read.All、Directory.Read.All、GroupMember.ReadWrite.All、Group.ReadWrite.All /groups/${groupId}/transitiveMembers person然后将 type/microsoft.graph.user 追加到请求路径时,会使用用户输入值组成参数$filter
type 设置为 personanyuser-type 不设置为 any ,并且 user-ids 已设置 User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All /users/$ ({userId} 设置 时 user-filters ,会将其作为 $filter 参数添加到请求, $count=true 并在 ConsistencyLevel: 'eventual' 请求上设置标头
type 设置为 personanyuser-type 设置为 anygroup-ids 未设置且 user-ids 已设置 User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All /users/$ ({userId} 设置 时 user-filters ,会将其作为 $filter 参数添加到请求, $count=true 并在 ConsistencyLevel: 'eventual' 请求上设置标头
group-id 未设置,为 typegrouptypeany ,结果比 show-max 找到的结果少 GroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All /组 使用 $filter 提供的用户输入 group-filters、 和 group-type 值组成
group-id 未设置,且 group-ids 已设置,为 typegrouptypeany ,结果数低于 show-max 找到的结果数 GroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All /组 使用 $filter 提供的用户输入 user-filters、 和 group-type 值组成

子组件

组件 mgt-people-picker 由一个或多个子组件组成,这些子组件可能需要除前面列出的权限以外的其他权限。 有关详细信息,请参阅每个子组件的文档: mgt-person

身份验证

控件使用身份验证文档中所述的全局 身份验证提供程序。

缓存

对象存储 缓存的数据 备注
groups 组列表 在 设置为 时 type 使用 PersonType.group
people 人员列表 在 设置为 PersonType.person 或 时type使用PersonType.any
users 用户列表 在指定时 groupId 使用

有关如何配置缓存的详细信息,请参阅 缓存

扩展以获得更多控制

对于更复杂的方案或真正自定义的 UX,此组件公开了组件扩展中的多种 protected render* 替代方法。

方法 说明
renderInput 呈现输入文本框。
renderSelectedPeople 呈现所选人员令牌。
renderSelectedPerson 呈现个人令牌。
renderFlyout 呈现浮出控件版式。
renderFlyoutContent 在结果浮出控件中呈现适当的状态。
renderLoading 呈现加载状态。
renderNoData 如果未找到搜索查询的结果,则呈现状态。
renderSearchResults 呈现搜索结果的列表。
renderPersonResult 呈现个人搜索结果。

本地化

控件公开以下可本地化的变量。 有关本地化的详细信息,请参阅 本地化组件

字符串名称 默认值
inputPlaceholderText Search for a name
maxSelectionsPlaceHolder Max contacts added
maxSelectionsAriaLabel Maximum contact selections reached
noResultsFound We didn't find any matches.
loadingMessage Loading...
选择 selected
removeSelectedUser Remove
selectContact select a contact
suggestionsTitle Suggested contacts