Microsoft Graph 工具包中的人员选取器组件People-Picker component in the Microsoft Graph Toolkit

您可以使用 mgt-people-picker web 组件搜索人员和/或组。You can use the mgt-people-picker web component to search for people and/or groups. 默认情况下,该组件将搜索组织中的所有人员和用户,但您也可以将该行为更改为同时搜索组或仅搜索组。By default, the component will search for all people and users in the organization, but you can change the behavior to also search for groups, or only groups. 您还可以将搜索筛选到特定的组。You can also filter the search to a specific group.


下面的示例演示了该 mgt-people-picker 组件。The following example shows the mgt-people-picker component. 开始搜索名称以查看结果呈现,并使用代码编辑器查看属性如何更改组件的行为。Start searching for a name to see the results render and use the code editor to see how properties change the behavior of the component.

在 "dev" 中打开此示例Open this example in


默认情况下, mgt-people-picker 组件从 /me/people/users 终结点提取人员。By default, the mgt-people-picker component fetches people from the /me/people and /users endpoints. 使用以下属性来更改此行为。Use the following attributes to change this behavior.

属性Attribute 属性Property 说明Description
show-maxshow-max showMaxshowMax 一个指示要显示的最大用户数的数字值。A number value to indicate the maximum number of people to show. 默认值为6。the default value is 6.
组 idgroup-id groupIdgroupId 一个 string 值,属于 Microsoft Graph 定义的组,用于进一步筛选搜索结果。A string value that belongs to a Microsoft Graph defined group for further filtering of the search results.
typetype typetype 要搜索的实体的类型。The type of entities to search for. 可用选项包括: persongroupanyAvailable options are: person, group, any. 默认值为 personDefault value is person. 如果设置了属性,则此属性不起作用 group-idThis attribute has no effect if group-id property is set.
group 类型group-type groupTypegroupType 要搜索的组类型。The group type to search for. 可用选项包括: unifiedsecuritymailenabledsecuritydistributionanyAvailable options are: unified, security, mailenabledsecurity, distribution, any. 默认值为 anyDefault value is any. 如果该 type 属性设置为,则此属性不起作用 personThis attribute has no effect if the type property is set to person.
选定-人员selected-people selectedPeopleselectedPeople 选定人员的数组。An array of selected people. 将此值设置为以编程方式选择人员。Set this value to select people programmatically.
peoplepeople peoplepeople 在搜索结果中找到并呈现的人员的数组An array of people found and rendered in the search result
默认选择的用户 iddefault-selected-user-ids defaultSelectedUserIdsdefaultSelectedUserIds 当提供了以逗号分隔的 Microsoft Graph 用户 Id 的字符串时,组件将呈现在初始化时选择的各个用户。When provided a string of comma-separated Microsoft Graph user IDs, the component renders the respective users as selected upon initialization.

下面是一个 show-max 示例。The following is a show-max example.

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

选定人员Selected people

组件的 "选定人员" 部分将呈现由开发人员或用户选择的每个人。The selected people section of the component renders each person chosen by the developer or user.


您可以通过执行下列操作之一来填充所选的人员数据:You can populate selected people data by doing one of the following:

  • 直接设置 selectedPeople 属性,如下面的示例所示。Setting the selectedPeople property directly, as shown in the following example.

    // personObject = User or Person from Microsoft Graph
  • 使用此 selectUsersById() 方法可接受 Microsoft graph用户 id的数组,以查找有关所选内容的相关用户详细信息。Using the selectUsersById() method, which accepts an array of Microsoft graph user ids to find associated user details for selection.

    注意: 如果找不到用户,则 id 不会为其呈现任何数据 idNote: If no user is found for an id, no data will be rendered for that id.

    // id = Mirosoft graph User "id"


将从组件中触发以下事件。The following events are fired from the component.

事件Event 说明Description
selectionChanged 用户在所选/选取的人员列表中添加或删除了人员。The user added or removed a person from the list of selected/picked people.

CSS 自定义属性CSS custom properties

mgt-people-picker组件定义以下 CSS 自定义属性。The mgt-people-picker component defines the following CSS custom properties.

mgt-people-picker {
    --input-border: 2px rgba(255, 255, 255, 0.5) solid; /* sets all input area border */

      /* OR individual input border sides */
    --input-border-bottom: 2px rgba(255, 255, 255, 0.5) solid;
    --input-border-right: 2px rgba(255, 255, 255, 0.5) solid;
    --input-border-left: 2px rgba(255, 255, 255, 0.5) solid;
    --input-border-top: 2px rgba(255, 255, 255, 0.5) solid;

    --input-background-color: #1f1f1f; /* input area background color */
    --input-hover-color: #008394; /* input area border hover color */
    --input-focus-color: #0f78d4; /* input area border focus color */

    --dropdown-background-color: #1f1f1f; /* selection area background color */
    --dropdown-item-hover-background: #333d47; /* person background color on hover */
    --selected-person-background-color: #f1f1f1; /* person item background color */
    --font-color: white; /* input area border focus color */
    --placeholder-default-color: #f1f1f1; /* placeholder text color default*/
    --placeholder-focus-color: rgba(255, 255, 255, 0.8); /* placeholder text focus color */


mgt-people-picker支持多个模板,这些模板可用于替换组件的某些部分。mgt-people-picker supports several templates that you can use to replace certain parts of the component. 若要指定模板,请在 <template> 组件内添加一个元素,并将 data-type 值设置为下列值之一。To specify a template, include a <template> element inside a component and set the data-type value to one of the following.

数据类型Data type 数据上下文Data context 说明Description
默认值default null:无数据null: no data 用于覆盖整个组件的呈现的模板。The template used to override the rendering of the entire component.
装载loading null:无数据null: no data 在发出对 graph 的请求时用于呈现选取器状态的模板。The template used to render the state of picker while request to graph is being made.
errorerror null:无数据null: no data 用户搜索不返回用户时使用的模板。The template used if user search returns no users.
无数据no-data null:无数据null: no data 如果用户搜索不返回用户,则使用备用模板。An alternative template used if user search returns no users.
选定的人员selected-person 人员:人员详细信息对象person: The person details object 呈现所选人员的模板。The template to render selected people.
personperson 人员:人员详细信息对象person: The person details object 用于在下拉列表中呈现人员的模板。The template to render people in the dropdown.

下面的示例演示如何使用 error 模板。The following examples shows how to use the error template.

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

Microsoft Graph 权限Microsoft Graph permissions

此组件使用以下 Microsoft Graph Api 和权限。This component uses the following Microsoft Graph APIs and permissions.

APIAPI 权限Permission
/me/people/me/people People.ReadPeople.Read
/users/users User.ReadBasic.AllUser.ReadBasic.All
/groups/groups Group.Read.AllGroup.Read.All
/groups/ $ {groupId}/members/groups/${groupId}/members User.ReadBasic.AllUser.ReadBasic.All
/users/$ {userPrincipleName}/users/${userPrincipleName} User.ReadUser.Read


该控件使用身份验证文档中介绍的全局身份验证提供程序。The control uses the global authentication provider described in the authentication documentation.

扩展以实现更多控制Extend for more control

对于更复杂的方案或真正的自定义 UX,此组件将公开几种 protected render* 用于在组件扩展中进行重写的方法。For more complex scenarios or a truly custom UX, this component exposes several protected render* methods for override in component extensions.

方法Method 说明Description
renderInputrenderInput 呈现输入文本框。Renders the input text box.
renderSelectedPeoplerenderSelectedPeople 呈现所选人员标记。Renders the selected people tokens.
renderSelectedPersonrenderSelectedPerson 呈现单个人员标记。Renders an individual person token.
renderFlyoutrenderFlyout 呈现浮出控件的镶边。Renders the flyout chrome.
renderFlyoutContentrenderFlyoutContent 在 "结果" 浮出控件中呈现适当的状态。Renders the appropriate state in the results flyout.
renderLoadingrenderLoading 呈现加载状态。Renders the loading state.
renderNoDatarenderNoData 在未找到搜索查询的结果时呈现状态。Renders the state when no results are found for the search query.
renderSearchResultsrenderSearchResults 呈现搜索结果的列表。Renders the list of search results.
renderPersonResultrenderPersonResult 呈现单个个人的搜索结果。Renders an individual person search result.