Partilhar via

Componente pessoa no Microsoft Graph Toolkit

  • Artigo

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.

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, largeou 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 (displayNameedepartment, jobTitle por predefinição)
fourlines- mostrar avatar e quatro linhas de texto (displayName, jobTitlee 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