Microsoft Graph Toolkit の Person コンポーネント

  • [アーティクル]

ユーザー コンポーネントは、写真、名前、電子メールアドレス、またはその他のユーザーの詳細を使用して、ユーザーまたは連絡先を表示するために使用されます。

ユーザー コンポーネントは、mgt-person-card を使用して、ユーザーに関する追加情報を含むポップアップ カードを表示します。 詳細については、「ユーザー カード」のセクションを参照してください。

例

次の例は、mgt-person コンポーネントを使用しているユーザーを示しています。 コード エディターを使用して、プロパティ がコンポーネントの動作をどのように変更させるかを確認することができます。

ユーザー情報の設定

3 つのプロパティを使用して、ユーザーの詳細を設定できます。 インスタンスごとに以下のプロパティの 1 つのみを使用してください。

  • user-id属性またはuserIdプロパティを設定して、ID を使用して Microsoft Graph からユーザーをフェッチします。

  • person-query属性またはpersonQueryプロパティを設定して、Microsoft Graph で特定のユーザーを検索します。 利用可能な最初のユーザーを選択し、ユーザーの詳細を取得します。 電子メールは、適切な人に質問するのに最適ですが、名前も同様に機能します。

  • person-presence 属性または personPresence プロパティを設定して、個人アバターにプレゼンス バッジを手動で追加します。

  • avatar-size属性またはavatarSizeプロパティをsmallまたはlargeに設定して、アバターのサイズを決定します。 これは、アバターに正しいプレゼンス バッジを追加するのに役立ちます。 アバターのサイズをさらにカスタマイズするには、以下に示す正しく対応する css カスタム プロパティを選択する必要があります。 既定では、値はautoに設定されており、viewプロパティに基づいてプレゼンスをレンダリングする方法を自動的に決定します。 アバターが 32 pxx 32 px より小さい場合は、smallを使用することをお勧めします。

  • 次の例に示すように、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 ユーザー ID に設定すると、そのユーザーの詳細とイメージが Microsoft Graph からフェッチされます。
person-query personQuery ユーザーの名前またはメールに設定して、Microsoft Graph でユーザーを検索し、最初のユーザーの詳細と画像を取得します。
person-details personDetails ユーザーを表すオブジェクトに設定します。 人物、ユーザー、連絡先、またはグループのリソースからのオブジェクトを操作します。
fallback-details fallbackDetails Microsoft Graph でユーザー/ユーザー/連絡先が見つからない場合に、人を表すオブジェクトに設定します。
person-image personImage そのユーザーに表示する画像を設定します。
person-presence personPresence ユーザーのプレゼンスを設定します。
fetch-image fetchImage ユーザーが提供したpersonDetailsオブジェクトに基づいて Microsoft Graph からpersonImageを自動的にフェッチするようにフラグを設定します。
disable-image-fetch disableImageFetch フラグを設定して、人物イメージのフェッチを無効にします。 プロパティを指定するときに、Microsoft Graph からの不要なフェッチを personImage 回避するために使用できます。
avatar-type avatarType または photo にinitials設定すると、表示状態がレンダリングされます。既定値は写真です。
avatar-size avatarSize アバターのサイズを 、、largeまたは autoにsmall設定すると、プレゼンス バッジの正しいサイズも決定できます。 既定値は auto です。 属性が view または fourlinesavatar-size にthreelines設定されている場合は、実際の値に関係なく、自動的に としてlarge扱われます。
vertical-layout verticalLayout コンポーネント レイアウトを垂直に設定します。
view view ユーザーのレンダリング方法を制御するように設定します。 既定値は image です。
image - アバターのみを表示
oneline - アバターと最初の行を表示する (既定ではdisplayName)
twolines - アバターとテキストの最初の 2 行を表示する (既定ではdisplayNameとjobTitle)
threelines- アバターと 3 行のテキストを表示する (displayNamejobTitledepartment既定では)
fourlines- アバターと 4 行のテキスト (displayName、jobTitledepartmentおよびemail既定) を表示する
で vertical-layout、変更を表示します。
twolines - アバターとテキストの最初の 2 行を表示する (既定ではdisplayNameとemail)
threelines - アバターと 3 行のテキスト (displayName 、 email および department 既定) を表示する
line1-property line1Property テキストの最初の行に使用する personDetails のプロパティを設定します。 既定値は displayName です。
line2-property line2Property テキストの 2 行目に使用する personDetails のプロパティを設定します。 既定値は jobTitle です。
line3-property line3Property テキストの 3 行目に使用する personDetails のプロパティを設定します。 既定値は department です。
line4-property line4Property 4 行目のテキストに使用する personDetails のプロパティを設定します。 既定値は email です。
show-presence showPresence フラグを設定してユーザーのプレゼンスを表示します - 既定値は false です。
使用 使用 カスタマイズされたパーソナル化を追加するためにコンポーネントを使用する場所を指定します。 現時点では、people コンポーネントで使用されている場合にのみサポートされています people 。
person-card personCardInteraction レンダリングされた人物コンポーネントにカード人を表示する動作を設定します。 使用できる値は、 none、 hover または clickです。 既定値は 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 line1 がクリックされたときに発生します person Microsoft Graph ユーザー、ユーザー、またはユーザーの写真の URL を含む追加personImageのプロパティとの連絡先を指定できるオブジェクト。 いいえ いいえ はい。既定のテンプレートをオーバーライドしない限り。
line2clicked Line2 がクリックされたときに発生します person Microsoft Graph ユーザー、ユーザー、またはユーザーの写真の URL を含む追加personImageのプロパティとの連絡先を指定できるオブジェクト。 いいえ いいえ はい。既定のテンプレートをオーバーライドしない限り。
line3clicked line3 がクリックされたときに発生します このオブジェクトはperson、Microsoft Graph ユーザー、ユーザー、またはユーザーの写真の URL を含む追加personImageのプロパティを持つ連絡先にすることができます。 いいえ いいえ はい。既定のテンプレートをオーバーライドしない限り。
line4clicked Line4 がクリックされたときに発生します このオブジェクトはperson、Microsoft Graph ユーザー、ユーザー、またはユーザーの写真の URL を含む追加personImageのプロパティを持つ連絡先にすることができます。 いいえ いいえ はい。既定のテンプレートをオーバーライドしない限り。

イベントの処理の詳細については、「 イベント」を参照してください。

テンプレート

mgt-person コンポーネントは、いくつかの テンプレート をサポートしており、コンポーネントの特定の部分を置き換えることができます。 テンプレートを指定するには、コンポーネント内に 要素を <template> 含め、 を data-type 次のいずれかの値に設定します。

データ型 データ コンテキスト 説明
読み込み中 なし コンポーネントがロード状態のときにレンダリングするテンプレート。
no-data なし ユーザーの画像やデータが利用できない場合にレンダリングするテンプレート。
既定 ユーザー: ユーザー詳細オブジェクト
personImage: 画像の URL
personPresence: 人のプレゼンスの詳細オブジェクト。		 既定のテンプレートは、コンポーネント全体を独自のものに置き換えます。
person-card ユーザー: ユーザー詳細オブジェクト
personImage: イメージの URL。		 ホバーまたはクリックで表示される mgt-person-card を更新するためのテンプレート。
line1 ユーザー: ユーザー詳細オブジェクト ユーザーメタデータの最初の行のテンプレート。
line2 ユーザー: ユーザー詳細オブジェクト 2 行目のユーザー メタデータのテンプレート。
line3 ユーザー: ユーザー詳細オブジェクト 3 行目のユーザー メタデータのテンプレート。
line4 ユーザー: ユーザー詳細オブジェクト ユーザーメタデータの 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 ポップアップ パネルをアクティブにするために必要なユーザー アクションを決定するための列挙型 - hover または click。 既定値は、none です。

テンプレート、スタイル、および属性の詳細については、「ユーザー カード コンポーネント」を参照してください。

グローバル コンポーネント構成

MgtPerson クラスは、アプリケーション内のすべてのユーザー カード コンポーネントを構成する静的な config オブジェクトを公開します。

次の例は、config オブジェクトの使用方法を説明しています。

import { MgtPerson } from `@microsoft/mgt`;

MgtPerson.config.useContactApis = false;

config オブジェクトでは、以下のプロパティが利用可能です。

プロパティ 説明
useContactApis boolean - 連絡先コンポーネントが Microsoft Graph 個人用連絡先 API を使用して連絡先の詳細と写真を検索できるかどうかを示します。 既定値は、true です。

Microsoft Graph のアクセス許可

このコントロールは、以下の Microsoft Graph API とアクセス許可を使用します。 呼び出される API ごとに、ユーザーには少なくとも 1 つのアクセス許可が一覧表示されている必要があります。 一部の構成では、Microsoft Graph が複数呼び出される可能性があります。 これらの呼び出しで異なるアクセス許可を使用できる場合、各 API とアクセス許可セットは別々の行に配置されます。

構成 アクセス許可 API
personDetailsイメージなしで設定し、 fetchImage を に設定しtrueavatarType、 を に設定しphoto、取得したユーザーが連絡先であり、 useContactApis を に設定します。true Contacts.Read、Contacts.ReadWrite /me/contacts/*
personDetailsイメージなしで設定し、 fetchImage を に avatarTypetruephoto設定し、ユーザーが連絡先ではないかuseContactApis、 が に設定されているfalse User.ReadBasic.All、User.Read.All、User.ReadWrite.All /users/{id}/photo/$value
personDetailsイメージなしで設定し、 を に avatarTypetrue設定photoし、fetchImage電子メールでユーザーを指定します User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All /users?$search=
personDetailsイメージなしで設定し、 を に avatarTypetrue設定photoし、fetchImage電子メールでユーザーを指定します User.ReadBasic.All、User.Read.All、User.ReadWrite.All /users/{id}/photo/$value
personDetailsイメージなしで設定し、 を に avatarTypetrue設定photoし、fetchImage電子メールuseContactApisで指定された連絡先を true に設定します Contacts.Read、Contacts.ReadWrite /me/contacts/*
personDetailsイメージなしでグループに設定し、 fetchImage を に設定しますtrueavatarType。photo 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設定します。disableImageFetchfalse User.Read、User.ReadWrite、User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All /me
userIdを にme設定し、 avatarType を にphoto設定します。disableImageFetchfalse 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以外の値に設定し、 avatarType 以外meの値に設定します。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に設定し、 personQuery にtrue設定しますme Presence.Read /me/presence
showPresence を に true 設定し personQuery 、 以外の値に設定します。 me Presence.Read.All /users/{id}/presence
personCardInteraction 以外の値に設定する PersonCardInteraction.none ユーザーカードアクセス許可を表示する API 呼び出しカードユーザーを表示する

サブコンポーネント

コンポーネントは mgt-person 1 つ以上のサブコンポーネントで構成され、前に一覧に示した権限以外のアクセス許可が必要な場合があります。 詳細については、各サブコンポーネント (mgt-person-カード) のドキュメントを参照してください。

認証

このコントロールは、認証ドキュメントに記述されているグローバル認証プロバイダーを使用して、必要なデータを取得します。

キャッシュ

オブジェクト ストア キャッシュされたデータ 注釈
photos 人の写真 が に設定され、 fetchImage が にphoto設定されている場合avatarTypeにtrue使用されます。
presence 人のプレゼンス が に設定されている場合 showPresence に true使用されます。
users ユーザーのユーザー情報。

キャッシュを構成する方法の詳細については、「キャッシュ」を参照してください。

より制御を行うために拡張する

より複雑なシナリオや真にカスタムな UX のために、このコンポーネントは、コンポーネント拡張でオーバーライドするためのいくつかのprotected render* メソッドを公開しています。

メソッド 説明
renderLoading 読み込み状態を表示します。
renderNoData 画像またはユーザー データが利用できない場合にレンダリングします。
renderAvatar アバターをレンダリングします。
renderDetails ユーザーの詳細部分をレンダリングします。

ローカリゼーション

コントロールは、ローカライズできる次の変数を公開します。 ローカライズを設定する方法の詳細については、「 コンポーネントのローカライズ」を参照してください。

文字列名 既定値
photoFor Photo for
emailAddress Email address