Componente pessoa no Microsoft Graph Toolkit

Artigo
11/07/2024

O componente da pessoa é utilizado para apresentar uma pessoa ou contacto utilizando a respetiva fotografia, nome, endereço de e-mail ou quaisquer outros detalhes da pessoa.

O componente de pessoa também utiliza o cartão mgt-person-card para apresentar um cartão de lista de opções com informações adicionais sobre o utilizador. Para obter detalhes, consulte a secção Cartão de Pessoa .

Exemplo

O exemplo seguinte mostra uma pessoa a utilizar o mgt-person componente . Pode utilizar o editor de código para ver como as propriedades alteram o comportamento do componente.

HTML
React

Abra este exemplo no mgt.dev.

Definir os detalhes da pessoa

Pode utilizar três propriedades para definir os detalhes da pessoa. Utilize apenas uma das seguintes propriedades por instância:

Defina o user-id atributo ou userId propriedade para obter o utilizador do Microsoft Graph com o respetivo ID.
Defina o person-query atributo ou personQuery propriedade para procurar no Microsoft Graph uma determinada pessoa. Escolhe a primeira pessoa disponível e obtém os detalhes da pessoa. Um e-mail funciona melhor para garantir que a pessoa certa é consultada, mas um nome também funciona.
Defina o person-presence atributo ou personPresence propriedade para adicionar manualmente um distintivo de presença ao avatar da pessoa.
Defina o avatar-size atributo ou avatarSize propriedade como small ou large para determinar o tamanho do avatar. Isto ajuda a adicionar o distintivo de presença correto ao avatar. Tem de escolher as propriedades personalizadas css correspondentes corretas mostradas abaixo para personalizar ainda mais o tamanho do avatar. Por predefinição, o valor está definido para auto o qual decidirá automaticamente como compor a presença com base na view propriedade . Recomendamos que utilize small se o seu avatar for inferior a 32 px por 32 px.
Utilize o person-details atributo ou personDetails propriedade para definir manualmente os detalhes da pessoa, conforme mostrado no exemplo seguinte.
```
let personControl = document.getElementById('myPersonControl');
personControl.personDetails = {
    displayName: 'Nikola Metulev',
    mail: 'nikola@contoso.com',
    personImage: 'url'
}
```
Se não for fornecida nenhuma imagem, será obtida uma (se disponível).
Por predefinição, o componente de pessoa apenas pede o conjunto de propriedades padrão do utilizador do Microsoft Graph. Para pedir propriedades adicionais, declare-as como qualquer parte do line(x)Property.

Propriedades

Pode utilizar várias propriedades para personalizar o componente.

Atributo	Propriedade	Descrição
user-id	userId	Defina como um ID de utilizador para obter os detalhes e a imagem desse utilizador a partir do Microsoft Graph.
person-query	personQuery	Defina como um nome ou e-mail de uma pessoa para procurar uma pessoa no Microsoft Graph e obter os detalhes e a imagem da primeira pessoa.
detalhes da pessoa	personDetails	Defina como um objeto que representa uma pessoa. Trabalha com objetos de pessoas, utilizadores, contactos ou grupo, recursos.
fallback-details	fallbackDetails	Definido como um objeto que representa uma pessoa quando não é encontrado nenhum utilizador/pessoa/contacto no Microsoft Graph.
pessoa-imagem	personImage	Defina a imagem a mostrar para a pessoa.
presença de pessoas	personPresence	Defina a presença da pessoa.
fetch-image	fetchImage	Defina o sinalizador para obter `personImage` automaticamente a partir do Microsoft Graph com base no `personDetails` objeto fornecido pelo utilizador.
disable-image-fetch	disableImageFetch	Defina o sinalizador para desativar a obtenção da imagem de pessoa. Pode ser utilizado para evitar obtenções desnecessárias do Microsoft Graph ao especificar a `personImage` propriedade.
avatar-type	avatarType	Defina como `initials` ou `photo` para compor o estado de apresentação – a predefinição é a fotografia.
tamanho do avatar	avatarSize	Defina o tamanho do avatar como `small`, `large`ou `auto`, ajudando também a determinar o tamanho correto para o distintivo de presença. O valor padrão é `auto`. Se o `view` atributo estiver definido como `threelines` ou `fourlines`, `avatar-size` será automaticamente tratado como `large`, independentemente do valor real.
esquema vertical	VerticalLayout	Defina o esquema do componente como vertical.
modo de exibição	modo de exibição	Defina para controlar a forma como a pessoa é composta. O padrão é `image`. `image` - mostrar apenas avatar `oneline` - mostrar avatar e primeira linha (`displayName` por predefinição) `twolines` - mostrar avatar e duas linhas de texto (`displayName` e `jobTitle` por predefinição) `threelines`- mostrar avatar e três linhas de texto (`displayName`e`department`, `jobTitle` por predefinição) `fourlines`- mostrar avatar e quatro linhas de texto (`displayName`, `jobTitle`e `emaildepartment` por predefinição) Em `vertical-layout`, veja as alterações. `twolines` - mostrar avatar e duas linhas de texto (`displayName` e `email` por predefinição) `threelines`- mostrar avatar e três linhas de texto (`displayName` e `departmentemail` por predefinição)
propriedade line1	line1Property	Define a propriedade de personDetails a utilizar para a primeira linha de texto. O padrão é `displayName`.
propriedade line2	line2Property	Define a propriedade de personDetails a utilizar para a segunda linha de texto. O padrão é `jobTitle`.
propriedade line3	line3Property	Define a propriedade de personDetails a utilizar para a terceira linha de texto. O padrão é `department`.
propriedade line4	line4Property	Define a propriedade de personDetails a utilizar para a quarta linha de texto. O padrão é `email`.
mostrar presença	showPresence	Defina o sinalizador para apresentar a presença de pessoas – a predefinição é `false`.
utilização	utilização	Especifique onde o componente está a ser utilizado para adicionar personalização personalizada para o mesmo. Atualmente, só é `people` suportado conforme utilizado no componente pessoas.
cartão de pessoa	personCardInteraction	Define o comportamento para mostrar o cartão de pessoa no componente de pessoa composta. Os valores permitidos são `none`, `hover` ou `click`. O padrão é `none`.

Propriedades personalizadas do CSS

O mgt-person componente define as seguintes propriedades personalizadas do 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;
}

Para saber mais, veja Componentes de estilo.

Eventos

Os seguintes eventos são acionados a partir do componente.

Evento	Quando é emitido	Dados personalizados	Cancelável	Bolhas	Funciona com um modelo personalizado
`line1clicked`	Acionado quando a linha1 é clicada	O `person` objeto que pode ser um utilizador, pessoa ou contacto do Microsoft Graph com uma propriedade adicional `personImage` que contém o URL da fotografia do utilizador.	Não	Não	Sim, a menos que substitua o modelo predefinido.
`line2clicked`	Acionado quando a linha2 é clicada	O `person` objeto que pode ser um utilizador, pessoa ou contacto do Microsoft Graph com uma propriedade adicional `personImage` que contém o URL da fotografia do utilizador.	Não	Não	Sim, a menos que substitua o modelo predefinido.
`line3clicked`	Acionado quando a linha3 é clicada	O `person` objeto, que pode ser um utilizador, pessoa ou contacto do Microsoft Graph com uma propriedade adicional `personImage` que contém o URL da fotografia do utilizador.	Não	Não	Sim, a menos que substitua o modelo predefinido.
`line4clicked`	Acionado quando a linha4 é clicada	O `person` objeto, que pode ser um utilizador, pessoa ou contacto do Microsoft Graph com uma propriedade adicional `personImage` que contém o URL da fotografia do utilizador.	Não	Não	Sim, a menos que substitua o modelo predefinido.

Para obter mais informações sobre o processamento de eventos, veja eventos.

Modelos

O mgt-person componente suporta vários modelos que lhe permitem substituir determinadas partes do componente. Para especificar um modelo, inclua um <template> elemento dentro de um componente e defina como data-type um dos seguintes valores:

Tipo de dados	Contexto de dados	Descrição
a carregar	none	O modelo a compor enquanto o componente está num estado de carregamento.
sem dados	none	O modelo a compor quando não existem dados ou imagens de pessoas disponíveis.
Padrão.	pessoa: O objeto de detalhes da pessoa `personImage`: o URL da imagem `personPresence`: o objeto de detalhes de presença para a pessoa.	O modelo predefinido substitui todo o componente pelo seu próprio.
cartão de pessoa	pessoa: O objeto de detalhes da pessoa `personImage`: o URL da imagem.	O modelo para atualizar o cartão mgt-person apresentado ao pairar ou clicar.
linha1	pessoa: O objeto de detalhes da pessoa	O modelo para a primeira linha de metadados de pessoa.
linha2	pessoa: O objeto de detalhes da pessoa	O modelo para a segunda linha de metadados de pessoas.
linha3	pessoa: O objeto de detalhes da pessoa	O modelo para a terceira linha de metadados de pessoas.
linha4	pessoa: O objeto de detalhes da pessoa	O modelo para a quarta linha de metadados de pessoas.

O exemplo seguinte define um modelo para o componente de pessoa.

<!-- 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>

Cartão pessoal

O mgt-person componente pode mostrar um mgt-person-card ao pairar ou clicar.

Adicionar o controlo à página HTML

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

Atributo	Propriedade	Descrição
cartão de pessoa	personCardInteraction	Uma enumeração para determinar a ação do utilizador necessária para ativar o painel de lista de opções - `hover` ou `click`. O valor padrão é `none`.

Para obter mais informações sobre modelos, estilos e atributos, veja Componente do Cartão de Pessoa.

Configuração de componente global

A MgtPerson classe expõe um objeto estático config que configura todos os componentes da pessoa na aplicação.

O exemplo seguinte mostra como utilizar o objeto de configuração.

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

MgtPerson.config.useContactApis = false;

As seguintes propriedades estão disponíveis no objeto de configuração.

Propriedade	Descrição
useContactApis	`boolean` - Indica se o componente de pessoa pode utilizar a API de contactos pessoais do Microsoft Graph para procurar detalhes de contacto e fotografias. O valor padrão é `true`.

Permissões do Microsoft Graph

Este controlo utiliza as seguintes APIs e permissões do Microsoft Graph. Para cada API chamada, o utilizador tem de ter, pelo menos, uma das permissões listadas. Algumas configurações podem resultar em várias chamadas para o Microsoft Graph. Quando estas chamadas podem utilizar permissões diferentes, cada API e conjunto de permissões encontra-se numa linha separada.

Configuração	Permissão	API
`personDetails` set without image, `fetchImage` set to `true`, `avatarType` set to `photo`, retrieved person is a contact and `useContactApis` set to `true`	Contacts.Read, Contacts.ReadWrite	/me/contacts/*
`personDetails` definir sem imagem, `fetchImage` definido como `true`, `avatarType` definido como e a `photo` pessoa não é um contacto ou `useContactApis` está definido como `false`	User.ReadBasic.All, User.Read.All, User.ReadWrite.All	/users/{id}/photo/$value
`personDetails` definir sem imagem, `fetchImage` definido como `true`, `avatarType` definido como `photo` e utilizador especificado por e-mail	User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/users?$search=
`personDetails` definir sem imagem, `fetchImage` definido como `true`, `avatarType` definido como `photo` e utilizador especificado por e-mail	User.ReadBasic.All, User.Read.All, User.ReadWrite.All	/users/{id}/photo/$value
`personDetails` defina sem imagem, `fetchImage` defina como `true`, `avatarType` defina como `photo` e contacte especificado por e-mail e `useContactApis` defina como verdadeiro	Contacts.Read, Contacts.ReadWrite	/me/contacts/*
`personDetails` defina sem imagem para um grupo, `fetchImage` defina como `true`, `avatarType` defina como `photo`	Group.Read.All, Group.ReadWrite.All'	/groups/${groupId}/photo/$value
`userId` definir	User.ReadBasic.All	/users/{id}
`userId` definir ou `personQuery` definir como `me` e `avatarType` definido como `photo` e `disableImageFetch` é `false`	User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/users/{id}
`userId` definir ou `personQuery` definir como `me` e `avatarType` definido como `photo` e `disableImageFetch` é `false`	User.ReadBasic.All, User.Read.All, User.ReadWrite.All	utilizadores/${userId}/photo/*
`userId` definido como `me` e `avatarType` definido como `photo` e `disableImageFetch` é `false`	User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/me
`userId` definido como `me` e `avatarType` definido como `photo` e `disableImageFetch` é `false`	User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All	/me/photo/$value
`personQuery` definir como `me` e `avatarType` definir como algo diferente de `photo`	User.Read, User.ReadWrite	/me
`personQuery` definir para um valor diferente `me` de e `avatarType` definido como algo diferente de `photo`	People.Read, People.Read.All	/me/people
`personQuery` definido para um valor diferente `me` de e `avatarType` definido como algo diferente `photo` de e `/me/people` não devolveu dados que correspondam aos fornecidos `personQuery`	User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/user?$search=
`personQuery` definir para um valor diferente de `me` e `useContactApis` definido como `false`	People.Read, User.ReadBasic.All	/me/people/?$search=, /users?$search=
`showPresence` definir como `true` e `personQuery` definir como `me`	Presence.Read	/me/presença
`showPresence` definir como `true` e `personQuery` definir para um valor diferente de `me`	Presence.Read.All	/users/{id}/presence
`personCardInteraction` definir para um valor diferente de `PersonCardInteraction.none`	Ver permissões de cartão de pessoa	Ver chamadas à API de cartão de pessoa

Subcomponentes

O mgt-person componente é composto por um ou mais subcomponentes que podem exigir outras permissões do que as listadas anteriormente. Para obter mais informações, consulte a documentação para cada subcomponente: mgt-person-card.

Autenticação

O controlo utiliza o fornecedor de autenticação global descrito na documentação de autenticação para obter os dados necessários.

Cache

Arquivo de objetos	Dados em cache	Comentários
`photos`	Fotografia da pessoa	Utilizado quando `avatarType` está definido como `photo` e `fetchImage` está definido como `true`.
`presence`	Presença da pessoa	Utilizado quando `showPresence` está definido como `true`.
`users`	Informações de utilizador da pessoa.

Veja Colocação em cache para obter mais detalhes sobre como configurar a cache.

Expandir para obter mais controlo

Para cenários mais complexos ou um UX verdadeiramente personalizado, este componente expõe vários protected render* métodos de substituição em extensões de componentes.

Método	Descrição
renderLoading	Compõe o estado de carregamento.
renderNoData	É composto quando não existem dados de imagem ou pessoa disponíveis.
renderAvatar	Compõe o avatar.
renderDetails	Compõe a parte de detalhes da pessoa.

Localização

O controlo expõe as seguintes variáveis que podem ser localizadas. Para obter detalhes sobre como configurar a localização, veja Localizar componentes.

Nome da cadeia	Valor padrão
photoFor	`Photo for`
emailAddress	`Email address`

Partilhar via