Люди компонент средства выбора в наборе средств Microsoft Graph

Статья
03/16/2023

Веб-компонент mgt-people-picker можно использовать для поиска людей и (или) групп. По умолчанию компонент ищет всех людей и пользователей в организации, но вы можете изменить его поведение, чтобы также искать группы или только группы. Вы также можете отфильтровать поиск по определенной группе. Кроме того, можно разрешить пользователю ввести и выбрать любой адрес электронной почты.

Пример

В примере ниже показан компонент mgt-people-picker. Начните поиск имени, чтобы отобразить результаты, и используйте редактор кода, чтобы увидеть, как свойства изменяют поведение компонента.

Открыть этот пример в mgt.dev

Свойства

По умолчанию компонент mgt-people-picker извлекает людей из конечных точек /me/people и /users. Используйте следующие атрибуты, чтобы изменить его поведение.

Атрибут	Свойство	Описание
show-max	showMax	Числовое значение, указывающее максимальное количество отображаемых людей. Значение по умолчанию — 6.
group-id	groupId	Значение строки, принадлежащее определенной группе Microsoft Graph для дальнейшей фильтрации результатов поиска.
transitive-search	transitiveSearch	Логическое значение для выполнения транзитивного поиска, возвращающего плоский список всех вложенных элементов. По умолчанию транзитивный поиск не используется.
type	type	Тип объектов, которые необходимо найти. Доступные варианты — `person`, `group`, `any`. Значение по умолчанию — `person`. Этот атрибут не оказывает влияния, если задано свойство `group-id`.
тип пользователя	userType	Тип пользователя для поиска. Доступны следующие варианты: `any`, `user` для пользователей организации или `contact` для контактов. Значение по умолчанию — `any`.
group-type	groupType	Тип группы, которую необходимо найти. Доступные варианты — `unified`, `security`, `mailenabledsecurity`, `distribution`, `any`. Значение по умолчанию — `any`. Этот атрибут не оказывает влияния, если для свойства `type` задано значение `person`.
selected-people	selectedPeople	Массив выбранных людей. Установите это значение, чтобы выбрать людей программным образом.
people	people	Массив людей, найденных и отображенных в результатах поиска.
placeholder	placeholder	Текст по умолчанию, который объясняет, как использовать компонент. Значение по умолчанию — `Start typing a name`.
default-selected-user-ids	defaultSelectedUserIds	При предоставлении строки разделенных запятой ИД пользователей Microsoft Graph, компонент отображает соответствующих пользователей как выбранных после инициализации.
default-selected-group-ids	defaultSelectedGroupIds	Как и в случае с выбранными по умолчанию идентификаторами пользователей, при указании строки идентификаторов групп Microsoft Graph, разделенных запятыми, компонент отрисовывает соответствующие группы, выбранные при инициализации.
selection-mode	selectionMode	Используется, чтобы указать следует ли разрешить выбирать несколько элементов (пользователей или групп) или только один элемент. Доступные варианты — `single`, `multiple`. Значение по умолчанию — `multiple`.
отключено	отключено	Задает значение, отключаемое средство выбора людей. Если этот параметр отключен, пользователь не сможет искать или выбирать людей.
disable-images	disableImages	Указывает, следует ли отключить получение и отображение изображений пользователей. Если задано значение `true`, вместо этого отображаются пользовательские инициалы.
allow-any-email	allowAnyEmail	Указывает, может ли средство выбора людей принимать адреса электронной почты без выбора пользователя. Значение по умолчанию — `false`. Завершив ввод адреса электронной почты, можно нажать клавишу запятую (`,`), точку с запятой (`;`), вкладку или ввести клавиши, чтобы добавить его.
user-ids	userIds	Строка идентификаторов пользователей, разделенных запятыми. Они будут отображаться только в раскрывающемся меню или в результатах поиска при вводе запроса. Например, `48d31887-5fad-4d73-a9f5-3c356e68a038,24fcbca3-c3e2-48bf-9ffc-c7f81b81483d` два пользователя будут отображаться в раскрывающемся списке только при сосредоточении входных данных. При вводе текста поиска будут возвращены результаты, соответствующие только пользователям в двух идентификаторах пользователей.
пользовательские фильтры	userFilters	Указывает критерии фильтра, используемые при запросе конечной точки пользователей. Требуется, чтобы для `user-type` параметра было задано значение `user` или `contact`. По умолчанию объект имеет значение `any` , и это приводит к тому, `user-type` что запрос выполняется в блоке конечной `people` точки. Пример: `user-filters="startsWith(displayName,'a')"`. Этот атрибут является необязательным. Узнайте больше о поддержке фильтрации свойств пользователей объектов каталога Azure AD.
group-filters	groupFilters	Указывает критерии фильтра, используемые при запросе к конечной точке `groups` . Требуется, чтобы для `type` параметра было задано значение `group`. Пример: `group-filters="startsWith(displayName,'a')"`. Этот атрибут является необязательным.
фильтры людей	peopleFilters	Указывает критерии фильтра, используемые при запросе к конечной точке `people` . Используется как есть. Пример: `people-filters="jobTitle eq 'Web Marketing Manager'"`. Этот атрибут является необязательным. Узнайте больше о фильтрации и поддерживаемых возможностях ресурса "Люди".
идентификаторы групп	groupIds	Строка идентификаторов групп, разделенных запятыми. Доступные результаты должны быть ограничены указанными группами. Пользователи, которые будут отображаться в раскрывающемся меню и в интерфейсе поиска, должны поступать только из указанных идентификаторов групп. Например, будут отображаться только пользователи, `02bd9fd6-8f93-4758-87c3-1fb73740a315,06f62f70-9827-4e6e-93ef-8e0f2d9b7b23` принадлежащие к этим группам. При вводе текста поиска будут возвращены результаты, которые соответствуют только пользователям в двух идентификаторах групп. Это свойство не используется, если `group-id` задано значение . Если свойство задано, `type` по умолчанию используется `group` значение , а `transitive-search` значение — `true` по умолчанию. `group-type` Если задано со свойством , `type` может иметь значение `any` или `group`. `type` Если имеет значение `person`, свойство не используется.
aria-label	ariaLabel	Строка, предоставляемая для помощи в аситивных технологиях, предоставляет контекст для средства выбора людей.

Ниже приведен пример show-max.

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

Выбранные люди

В разделе "Выбранные люди" компонента отображаются люди, выбранные разработчиком или пользователем.

mgt-people-picker

Вы можете заполнить данные о выбранных людях, выполнив одно из следующих действий.

Задайте свойство selectedPeople напрямую, как показано в примере ниже.

// personObject = User or Person from Microsoft Graph
document.querySelector('mgt-people-picker').selectedPeople.push(personObject);

Используйте метод selectUsersById(), принимающий массив ИД пользователей Microsoft Graph, чтобы найти сведения о связанных пользователях для выбора.

Примечание. Если пользователь не найден по id, данные для этого id не будут отображаться.
```
// id = Microsoft graph User "id"
document.querySelector('mgt-people-picker').selectUsersById(["id","id"])
```
selectGroupsById() Использование метода , который принимает массив идентификаторов групп Microsoft Graph для поиска групп со связанными пользователями.
```
// groupid = Microsoft graph group "id"
document.querySelector('mgt-people-picker').selectGroupsById(["groupid","groupid"])
```

События

Из компонента инициируются следующие события.

Событие	Когда он генерируется	Пользовательские данные	Отменяемым	Пузыри	Работает с пользовательским шаблоном
`selectionChanged`	Пользователь добавил или удалил пользователя из списка выбранных или выбранных пользователей	Массив выбранных людей, где пользователь может быть пользователем Graph, пользователем или контактом с дополнительным `personImage` свойством, содержащим URL-адрес фотографии пользователя	Нет	Нет	Да, если вы не переопределяете шаблон по умолчанию

Дополнительные сведения об обработке событий см. в разделе События.

Настраиваемые свойства CSS

Компонент mgt-people-picker определяет следующие настраиваемые свойства CSS.

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-border-color--hover: #008394; /* input area border hover color */
    --input-border-color--focus: #0f78d4; /* input area border focus color */

    --dropdown-background-color: #ca00ca; /* selection area background color */
    --dropdown-item-hover-background: purple; /* person background color on hover */
    --dropdown-item-text-color: white; /* person item text color */
    --dropdown-item-text-hover-color: gold; /* person item text color on hover */
    --selected-person-background-color: #f1f1f1; /* person item background color */
    
    --color: white; /* input area border focus color */
    --placeholder-color: #f1f1f1; /* placeholder text color */
    --placeholder-color--focus: rgba(255, 255, 255, 0.8); /* placeholder text focus color */
}

Шаблоны

Компонент mgt-people-picker поддерживает несколько шаблонов, позволяющих заменить его определенные части. Чтобы указать шаблон, добавьте элемент <template> в компонент и присвойте параметру data-type одно из следующих значений.

Тип данных	Контекст данных	Описание
default	null: нет данных	Шаблон, используемый для переопределения отображения всего компонента.
loading	null: нет данных	Шаблон, используемый для отображения состояния средства выбора при выполнении запроса к Microsoft Graph.
error	null: нет данных	Шаблон, используемый в том случае, если поиск не возвращает пользователей.
no-data	null: нет данных	Альтернативный шаблон, используемый в том случае, если поиск не возвращает пользователей.
selected-person	person: объект сведений о пользователе	Шаблон, отображающий выбранных людей.
person	person: объект сведений о пользователе	Шаблон, отображающий людей в раскрывающемся списке.

В следующих примерах показано, как использовать шаблон error.

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

Разрешения Microsoft Graph

Этот компонент использует следующие API и разрешения Microsoft Graph.

Конфигурация	Разрешение	API
`group-id` Установить	Люди. Read, User.Read.All, GroupMember.Read.All	/groups/${groupId}/members
`type` задайте значение `Person` или `any`	People.Read	/me/people
`type` задайте значение `Group` или выполните поиск пользователей, а `type` для — `Group` или `any`	Group.Read.All	/groups
`default-selected-user-ids` Установить	User.ReadBasic.All	/users
поиск пользователей и `type` установка значения `Person` или `any`	Люди. Read, User.ReadBasic.All	/me/people, /users

Проверка подлинности

В элементе управления используется глобальный поставщик проверки подлинности, описанный в документации по проверке подлинности.

Кэш

Хранилище объектов	Кэшированные данные	Замечания
`groups`	Список групп	Используется, если `type` задано значение `PersonType.group`
`people`	List of people	Используется, если `type` задано значение `PersonType.person` или `PersonType.any`
`users`	Список пользователей	Используется при `groupId` указании

Дополнительные сведения о настройке кэша см. в разделе Кэширование .

Расширение для дополнительного управления

В более сложных сценариях или настраиваемых пользовательских интерфейсах этот компонент предоставляет несколько методов protected render* для переопределения в расширениях компонента.

Метод	Описание
renderInput	Отображает поле ввода.
renderSelectedPeople	Отображает маркеры выбранных людей.
renderSelectedPerson	Отображает маркер одного пользователя.
renderFlyout	Отображает хром всплывающего окна.
renderFlyoutContent	Отображает соответствующее состояние во всплывающем окне результатов.
renderLoading	Отображает состояние загрузки.
renderNoData	Отображает состояние, если для поискового запроса не найдено результатов.
renderSearchResults	Отображает список результатов поиска.
renderPersonResult	Отображает результаты поиска для одного пользователя.