Компонент Person в Microsoft Graph Toolkit

Статья
11/07/2024

Компонент пользователя используется для отображения пользователя или контакта с помощью его фотографии, адреса электронной почты и любых других сведений о пользователе.

Кроме того, в компоненте пользователя используется mgt-person-card для отображения карточки всплывающего окна с дополнительной информации о пользователе. Дополнительные сведения см. в разделе Карточка пользователя.

Пример

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

HTML
React;

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

Настройка сведений о пользователе

Чтобы задать сведения о пользователе, можно использовать три свойства. Используйте только одно из указанных далее свойств для одного случая:

Задайте атрибут user-id или свойство userId, чтобы получить данные пользователя из Microsoft Graph, используя его идентификатор.
Чтобы выполнить поиск определенного пользователя в Microsoft Graph, задайте атрибут person-query или свойство personQuery. Он выбирает первого доступного человека и извлекает сведения о нем. Электронная почта лучше всего подходит для того, чтобы найти нужного пользователя, но можно использовать и имя.
Задайте атрибут person-presence или свойство personPresence, чтобы добавить значок присутствия в аватар пользователя вручную.
Чтобы определить размер аватара, задайте для атрибута avatar-size или свойства avatarSize значение small или large. Это помогает добавить в аватар правильный значок присутствия . Чтобы дополнительно настроить размер аватара, необходимо выбрать правильные соответствующие настраиваемые свойства css, показанные ниже. Для этого параметра по умолчанию задано значение auto, благодаря которому присутствие будет обрабатываться автоматически с учетом свойства view. Рекомендуем использовать small, если аватар меньше 32 на 32 пикс.
Чтобы вручную задать сведения о пользователе, используйте атрибут person-details или свойство personDetails, как показано в приведенном далее примере.
```
let personControl = document.getElementById('myPersonControl');
personControl.personDetails = {
    displayName: 'Nikola Metulev',
    mail: 'nikola@contoso.com',
    personImage: 'url'
}
```
Если изображение не предоставлено, оно извлекается (если доступно).
По умолчанию компонент person запрашивает только стандартный набор свойств пользователя Microsoft Graph. Чтобы запросить дополнительные свойства, объявите их как любую часть line(x)Propertyобъекта .

Свойства

Для настройки компонента можно использовать несколько свойств.

Атрибут	Свойство	Описание
user-id	userId	Задайте идентификатор пользователя, чтобы получить сведения о пользователе и его изображение из Microsoft Graph.
person-query	personQuery	Чтобы найти пользователя в Microsoft Graph, установите его имя или адрес электронной почты пользователя и получите сведения о первом пользователе и его изображение.
person-details	personDetails	Установите объект, представляющий пользователя. Работает с объектами из людей, пользователей, контактов или групп, ресурсов.
сведения о резерве	fallbackDetails	Задайте для объекта, представляющего пользователя, если в Microsoft Graph не найдено пользователя, пользователя или контакта.
person-image	personImage	Задать изображение, которое будет отображаться для пользователя.
person-presence	personPresence	Установка присутствия для пользователя.
fetch-image	fetchImage	Установите флажок для автоматического получения `personImage` из Microsoft Graph на основе объекта `personDetails`, предоставленного пользователем.
disable-image-fetch	disableImageFetch	Установите флаг, чтобы отключить получение изображения пользователя. Его можно использовать, чтобы избежать ненужной выборки из Microsoft Graph при указании `personImage` свойства.
аватар-тип	avatarType	Задайте значение `initials` или `photo` для отрисовки любого состояния отображения. По умолчанию используется значение photo.
Размер аватара	avatarSize	Задайте для размера аватара значение `small`, `large`или `auto`, чтобы также определить правильный размер значка присутствия. Значение по умолчанию — `auto`. `view` Если атрибут имеет значение `threelines` или `fourlines`, `avatar-size` автоматически обрабатывается как `large`, независимо от его фактического значения.
вертикальный макет	verticalLayout	Задайте для макета компонента вертикальное значение.
представление	представление	Установите, чтобы настроить, как выглядит пользователь. Значение по умолчанию: `image`. `image` — Показывать только аватар `oneline` — Показывать аватар и первую строку (`displayName` по умолчанию) `twolines` — Показывать аватар и две строки текста (`displayName` и `jobTitle` по умолчанию) `threelines`— отображение аватара и трех строк текста (`displayNamejobTitle`и `department` по умолчанию); `fourlines` — отображение аватара и четырех строк текста (`displayName`, `jobTitle`и `departmentemail` по умолчанию) В `vertical-layout`просмотрите изменения. `twolines` — Показывать аватар и две строки текста (`displayName` и `email` по умолчанию) `threelines` — отображение аватара и трех строк текста (`displayName` и `emaildepartment` по умолчанию)
line1-property	line1Property	Задает свойство personDetails для использования для первой строки текста. Значение по умолчанию: `displayName`.
line2-property	line2Property	Задает свойство personDetails для использования для второй строки текста. Значение по умолчанию: `jobTitle`.
line3-property	line3Property	Задает свойство personDetails для использования для третьей строки текста. Значение по умолчанию: `department`.
свойство line4	line4Property	Задает свойство personDetails, используемое для четвертой строки текста. Значение по умолчанию: `email`.
show-presence	showPresence	Установить флажок отображения присутствия пользователя — по умолчанию `false`.
употребление	употребление	Укажите, где используется компонент, чтобы добавить настраиваемую персонализацию для него. В настоящее время поддерживается `people` только в том виде, в который используется компонент people.
person-card	personCardInteraction	Задает поведение для отображения карточки пользователя в компоненте отрисованного пользователя. Допустимые значения: `none`или `hoverclick`. Значение по умолчанию: `none`.

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

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

<mgt-person class="person" person-query="me" view="fourlines" id="online" show-presence></mgt-person>

.person {
  --person-background-color: #616161;
  --person-background-border-radius: 30%;
  --person-avatar-size: 40px;
  --person-avatar-border: 3px solid yellow;
  --person-avatar-border-radius: 54%;
  --person-initials-text-color: white;
  --person-initials-background-color: blue;
  --person-line1-font-size: 32px;
  --person-line1-font-weight: 600;
  --person-line1-text-color: red;
  --person-line1-text-transform: capitalize;
  --person-line1-text-line-height: 20px;
  --person-line2-font-size: 28px;
  --person-line2-font-weight: 500;
  --person-line2-text-color: orange;
  --person-line2-text-transform: full-width;
  --person-line2-text-line-height: 16px;
  --person-line3-font-size: 24px;
  --person-line3-font-weight: 400;
  --person-line3-text-color: blue;
  --person-line3-text-transform: uppercase;
  --person-line3-text-line-height: 12px;
  --person-line4-font-size: 20px;
  --person-line4-font-weight: 300;
  --person-line4-text-color: green;
  --person-line4-text-transform: lowercase;
  --person-line4-text-line-height: 12px;
  --person-details-spacing: 30px;
}

Дополнительные сведения см. в статье Компоненты стиля.

События

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

Событие	Когда он генерируется	Пользовательские данные	Отменяемым	Пузыри	Работает с пользовательским шаблоном
`line1clicked`	Срабатывает при щелчке строки 1	Объект `person` , который может быть пользователем Microsoft Graph, пользователем или контактом с дополнительным `personImage` свойством, содержащим URL-адрес фотографии пользователя.	Нет	Нет	Да, если вы не переопределяете шаблон по умолчанию.
`line2clicked`	Срабатывает при щелчке строки 2	Объект `person` , который может быть пользователем Microsoft Graph, пользователем или контактом с дополнительным `personImage` свойством, содержащим URL-адрес фотографии пользователя.	Нет	Нет	Да, если вы не переопределяете шаблон по умолчанию.
`line3clicked`	Срабатывает при щелчке строки 3	Объект `person` , который может быть пользователем Microsoft Graph, пользователем или контактом с дополнительным `personImage` свойством, содержащим URL-адрес фотографии пользователя.	Нет	Нет	Да, если вы не переопределяете шаблон по умолчанию.
`line4clicked`	Срабатывает при щелчке строки 4	Объект `person` , который может быть пользователем Microsoft Graph, пользователем или контактом с дополнительным `personImage` свойством, содержащим URL-адрес фотографии пользователя.	Нет	Нет	Да, если вы не переопределяете шаблон по умолчанию.

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

Шаблоны

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

Тип данных	Контекст данных	Описание
загрузка	Нет	Шаблон для отображения состояния загрузки компонента.
no-data	Нет	Шаблон для использования, если изображения или данные не доступны.
default	пользователь: объект сведений о пользователе `personImage`: URL-адрес изображения. `personPresence`: объект сведений о присутствии для пользователя.	Шаблон по умолчанию заменяет весь компонент вашим собственным компонентом.
person-card	пользователь: объект сведений о пользователе `personImage`: URL-адрес изображения.	Шаблон для обновления карточки mgt-person-card, отображаемой при наведении указателя мыши или щелчке мышью.
строка1	person: объект сведений о пользователе	Шаблон для первой строки метаданных пользователя.
строка 2	person: объект сведений о пользователе	Шаблон для второй строки метаданных пользователя.
строка 3	person: объект сведений о пользователе	Шаблон для третьей строки метаданных пользователя.
строка 4	person: объект сведений о пользователе	Шаблон для четвертой строки метаданных пользователя.

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

<!-- Retemplate the entire person component -->
<mgt-person>
  <template>
    <div data-if="personImage">
      <img src="{{personImage}}" />
    </div>
    <div data-else>
      {{person.displayName}}
    </div>
  </template>
</mgt-person>

<!-- Retemplate the line properties -->
<mgt-person view="threeLines">
  <template data-type="line1">
    <div>
      Hello, my name is: {{person.displayName}}
    </div>
  </template>
  <template data-type="line2">
    <div>
      Super cool
    </div>
  </template>
  <template data-type="line3">
    <div>
      Loves MGT
    </div>
  </template>
</mgt-person>

<mgt-person view="fourLines">
  <template data-type="line1">
    <div>
      Hello, my name is: {{person.displayName}}
    </div>
  </template>
  <template data-type="line2">
    <div>
      Musician
    </div>
  </template>
  <template data-type="line3">
    <div>
      Calif records
    </div>
  </template>
  <template data-type="line4">
    <div>
      {{person.mail}}
    </div>
  </template>
</mgt-person>

<!-- Person-card template -->
<mgt-person person-query="me" view="twolines" person-card="hover">
	<template data-type="person-card">
		My custom person card experience
	</template>
</mgt-person>

Карточка пользователя

mgt-person Компонент может отображатьсяmgt-person-card при либо наведении указателя мыши, либо щелчка мышью.

Добавьте средство управления на HTML-страницу.

<mgt-person person-query="me" person-card="hover"></mgt-person>

Атрибут	Свойство	Описание
person-card	personCardInteraction	Перечисление для определения действия пользователя, необходимого для активации всплывающей панели , или `hoverclick`. Значение по умолчанию — `none`.

Дополнительные сведения о шаблонах, стилях и атрибутах см. в статье Компонент карточки пользователя.

Конфигурация глобального компонента

Класс MgtPerson предоставляет статический объект config, который конфигурирует все компоненты пользователя в приложении.

В приведенном ниже примере показано, как использовать объект конфигурации.

import { MgtPerson } from '@microsoft/mgt-components';

MgtPerson.config.useContactApis = false;

Ниже указаны свойства, доступные в объекте конфигурации.

Свойство	Описание
useContactApis	`boolean` — Указывает, может ли компонент person использовать API личных контактов Microsoft Graph для поиска контактных данных и фотографий. Значение по умолчанию: `true`.

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

Этот элемент управления использует следующие API и разрешения Microsoft Graph. Для каждого вызываемого API пользователь должен иметь по крайней мере одно из указанных разрешений. Некоторые конфигурации могут привести к нескольким вызовам Microsoft Graph. Если эти вызовы могут использовать разные разрешения, каждый API и набор разрешений находится в отдельной строке.

Конфигурация	Разрешение	API
`personDetails` задать без изображения, `fetchImage` задать значение `true`, `avatarType` задать значение `photo`, извлеченный пользователь является контактом и `useContactApis` задать значение `true`	Contacts.Read, Contacts.ReadWrite	/me/contacts/*
`personDetails` задать без изображения, `fetchImage` задать значение `true`, `avatarType` а `photo` пользователь не является контактом или `useContactApis` имеет значение `false`	User.ReadBasic.All, User.Read.All, User.ReadWrite.All	/users/{id}/photo/$value
`personDetails` задать без изображения, `fetchImage` задать значение `true`, `avatarType` задать значение `photo` и пользователя, указанного по электронной почте	User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/users?$search=
`personDetails` задать без изображения, `fetchImage` задать значение `true`, `avatarType` задать значение `photo` и пользователя, указанного по электронной почте	User.ReadBasic.All, User.Read.All, User.ReadWrite.All	/users/{id}/photo/$value
`personDetails` задать без изображения, `fetchImage` задать значение `true`, `avatarType` задать `photo` значение и связаться, указанные по электронной почте, и `useContactApis` установить значение true	Contacts.Read, Contacts.ReadWrite	/me/contacts/*
`personDetails`параметр без изображения — в группу, `fetchImage` параметр — `true`в . `avatarTypephoto`	Group.Read.All, Group.ReadWrite.All'	/groups/${groupId}/photo/$value
`userId` набор	User.ReadBasic.All	/users/{id}
`userId`задать или `personQuery` задать значение `me` и `avatarType` имеет значение `photo` и имеет значение .`disableImageFetchfalse`	User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/users/{id}
`userId`задать или `personQuery` задать значение `me` и `avatarType` имеет значение `photo` и имеет значение .`disableImageFetchfalse`	User.ReadBasic.All, User.Read.All, User.ReadWrite.All	users/${userId}/photo/*
`userId` задать значение `me` , а `avatarType` — `photo` и `disableImageFetch` — `false`	User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/me
`userId` задать значение `me` , а `avatarType` — `photo` и `disableImageFetch` — `false`	User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All	/me/photo/$value
`personQuery` задайте значение `me` , а `avatarType` — что-то другое, чем `photo`	User.Read, User.ReadWrite	/me
`personQuery` задайте значение, отличное от `me` , и `avatarType` задайте значение, отличное от `photo`	People.Read, People.Read.All	/me/people
`personQuery` присвоить значение, отличное `me` от , и `avatarType` задать значение , `photo` отличное от `/me/people` и не возвратив данные, соответствующие предоставленному `personQuery`	User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/user?$search=
`personQuery` задайте значение, отличное от `me` , а `useContactApis` — `false`	People.Read, User.ReadBasic.All	/me/people/?$search=, /users?$search=
`showPresence` задайте значение `true` , а `personQuery` — `me`	Presence.Read	/me/presence
`showPresence` задайте значение `true` , а `personQuery` — значение, отличное от `me`	Presence.Read.All	/users/{id}/presence
`personCardInteraction` задайте значение, отличное от `PersonCardInteraction.none`	Просмотр разрешений на карточку пользователя	Просмотр вызовов API карточки пользователя

Подкомпоненты

Компонент mgt-person состоит из одного или нескольких подкомпонентов, для которых могут потребоваться другие разрешения, отличные от перечисленных ранее. Дополнительные сведения см. в документации по каждому подкомпоненту: mgt-person-card.

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

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

Кэш

Хранилище объектов	Кэшированные данные	Замечания
`photos`	Фотография человека	Используется, если `avatarType` имеет значение `photo` и `fetchImage` имеет значение `true`.
`presence`	Присутствие пользователя	Используется, если `showPresence` задано значение `true`.
`users`	Сведения о пользователе пользователя.

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

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

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

Метод	Описание
renderLoading	Отображает состояние загрузки.
renderNoData	Отображается, если изображение или данные о пользователе недоступны.
renderAvatar	Отображает аватар.
renderDetails	Отображает сведения о пользователе.

Локализация

Элемент управления предоставляет следующие переменные, которые можно локализовать. Дополнительные сведения о настройке локализации см. в разделе Локализация компонентов.

Имя строки	Значение по умолчанию
photoFor	`Photo for`
emailAddress	`Email address`

Поделиться через