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 | 表示状態をレンダリングするには、 initials または photo に設定します。既定値は写真です。 |
| avatar-size | avatarSize | アバターのサイズを small、 large、または autoに設定すると、プレゼンス バッジの正しいサイズも決定できます。 既定値は auto です。
view属性が threelines または fourlines に設定されている場合、avatar-sizeは実際の値に関係なく、自動的にlargeとして扱われます。 |
| vertical-layout | verticalLayout | コンポーネント レイアウトを垂直に設定します。 |
| view | view | ユーザーのレンダリング方法を制御するように設定します。 既定値は image です。 image - アバターのみを表示oneline - アバターと最初の行を表示する (既定ではdisplayName)twolines - アバターとテキストの最初の 2 行を表示する (既定ではdisplayNameとjobTitle)threelines - アバターと 3 行のテキストを表示する (既定では、displayName、 jobTitle 、 department )fourlines - アバターと 4 行のテキストを表示する (既定ではdisplayName、 jobTitle、 department 、 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: 画像の URLpersonPresence: 人のプレゼンスの詳細オブジェクト。 |
既定のテンプレートは、コンポーネント全体を独自のものに置き換えます。 |
| 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-components';
MgtPerson.config.useContactApis = false;
config オブジェクトでは、以下のプロパティが利用可能です。
| プロパティ | 説明 |
|---|---|
| useContactApis |
boolean - 連絡先コンポーネントが Microsoft Graph 個人用連絡先 API を使用して連絡先の詳細と写真を検索できるかどうかを示します。 既定値は、true です。 |
Microsoft Graph のアクセス許可
このコントロールは、以下の Microsoft Graph API とアクセス許可を使用します。 呼び出される API ごとに、ユーザーには少なくとも 1 つのアクセス許可が一覧表示されている必要があります。 一部の構成では、Microsoft Graph が複数呼び出される可能性があります。 これらの呼び出しで異なるアクセス許可を使用できる場合、各 API とアクセス許可セットは別々の行に配置されます。
| 構成 | アクセス許可 | API |
|---|---|---|
personDetailsイメージなしで設定fetchImage、trueに設定avatarType、photoに設定、取得したユーザーが連絡先であり、 に設定useContactApistrue |
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/* |
personDetailsimage をグループに設定fetchImage、trueに設定avatarTypephoto |
Group.Read.All、Group.ReadWrite.All' | /groups/${groupId}/photo/$value |
userId セット |
User.ReadBasic.All | /users/{id} |
userId
meに設定するか、personQueryに設定し、photoに設定avatarTypedisableImageFetchfalse |
User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All | /users/{id} |
userId
meに設定するか、personQueryに設定し、photoに設定avatarTypedisableImageFetchfalse |
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 を me 以外の値に設定し、 avatarType 以外の値に設定する photo |
People.Read、People.Read.All | /me/people |
personQueryを me 以外の値に設定し、photo以外の値に設定avatarType、指定/me/peopleに一致するデータが返されないpersonQuery |
User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All | /user?$search= |
personQueryを me 以外の値に設定し、 を に設定useContactApisfalse |
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 コンポーネントは、前に示したアクセス許可以外のアクセス許可を必要とする可能性がある 1 つ以上のサブコンポーネントで構成されます。 詳細については、各サブコンポーネントのドキュメント mgt-person-card を参照してください。
認証
このコントロールは、認証ドキュメントに記述されているグローバル認証プロバイダーを使用して、必要なデータを取得します。
キャッシュ
| オブジェクト ストア | キャッシュされたデータ | 注釈 |
|---|---|---|
photos |
人の写真 |
avatarTypeが photo に設定され、fetchImageが true に設定されている場合に使用されます。 |
presence |
人のプレゼンス |
showPresenceが true に設定されている場合に使用されます。 |
users |
ユーザーのユーザー情報。 |
キャッシュを構成する方法の詳細については、「キャッシュ」を参照してください。
より制御を行うために拡張する
より複雑なシナリオや真にカスタムな UX のために、このコンポーネントは、コンポーネント拡張でオーバーライドするためのいくつかのprotected render* メソッドを公開しています。
| メソッド | 説明 |
|---|---|
| renderLoading | 読み込み状態を表示します。 |
| renderNoData | 画像またはユーザー データが利用できない場合にレンダリングします。 |
| renderAvatar | アバターをレンダリングします。 |
| renderDetails | ユーザーの詳細部分をレンダリングします。 |
ローカリゼーション
コントロールは、ローカライズできる次の変数を公開します。 ローカライズを設定する方法の詳細については、「 コンポーネントのローカライズ」を参照してください。
| 文字列名 | 既定値 |
|---|---|
| photoFor | Photo for |
| emailAddress | Email address |