Microsoft Graph Toolkit のピッカーコンポーネント

注意

Microsoft Graph Toolkit は非推奨です。 2025 年 9 月 1 日から、2026 年 8 月 28 日に完全な退職が予定されています。開発者は、Web エクスペリエンスを構築するために、Microsoft Graph SDK またはその他のサポートされている Microsoft Graph ツールを使用して移行する必要があります。詳細については、非推奨のお知らせを参照してください。

ピッカーコンポーネントは、mgt-getを使用して Microsoft Graph APIを照会し、ドロップダウンコントロールをレンダリングして、リソースの配列から 1 つのリソースを選択できるようにします。

例

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

HTML
React

mgt.dev でこの例を開きます。

プロパティと属性

いくつかの属性を使用して、コンポーネントの動作を変更することができます。コンポーネントには、 resource などの必須の属性 ( /users や key-name など) があります (たとえば、 displayName)。

key-name では、入れ子になった値もサポートされます。たとえば、次の応答では次のようになります。

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications/$entity",
    "id": "03ef14b0-ca33-4840-8f4f-d6e91916010e",
    "verifiedPublisher": {
            "displayName": "publisher_contoso",
            "verifiedPublisherId": "9999999",
             "addedDateTime": "2021-04-24T17:49:44Z"
    },
    "certification": {
           "isPublisherAttested": true,
           "isCertifiedByMicrosoft": true,
           "lastCertificationDateTime": "2021-05-11T23:26:20Z",
           "certificationExpirationDateTime": "2022-05-11T23:26:20Z",
           "certificationDetailsUrl": "https://learn.microsoft.com/microsoft-365-app-certification/forward/azure/631a96bc-a705-4eda-9f99-fdaf9f54f6a2"
    },
    "tags": [],
    "tokenEncryptionKeyId": null,
    "api": {
        "requestedAccessTokenVersion": 2,
        "acceptMappedClaims": null,
        "knownClientApplications": [],
        "oauth2PermissionScopes": [],
        "preAuthorizedApplications": []
    },
    "appRoles": [],
    "web": {
        "redirectUris": [],
        "homePageUrl": null,
        "logoutUrl": null,
        "implicitGrantSettings": {
            "enableIdTokenIssuance": false,
            "enableAccessTokenIssuance": false
        }
    }
}

key-name属性値は、web.homePageUrlまたはverifiedPublisher.displayNameできます。

属性	プロパティ	説明
リソース	resource	Microsoft Graph から取得するリソース ( `/me` や `/users`など)。
placeholder	placeholder	ピッカーでレンダリングされるプレースホルダー (たとえば、 `Select a user` や `Select a task list`)。
key-name	keyName	ピッカーでレンダリングされるキー (たとえば、 `displayName`)。
selected-value	selectedValue	省略可能。ピッカーで現在選択されているオプションとして設定する値。 Microsoft Graph クエリから提供されるオプションに存在する必要があります。
scopes	scopes	プロパティを使用している場合は文字列の配列、属性を使用している場合はコンマ区切りのスコープ (オプション)。コンポーネントとサポートされているプロバイダーは、ユーザーが指定されたアクセス許可の少なくとも 1 つに同意していることを確認します。
version	version	`GET`要求を行うときに使用する省略可能な API バージョン。既定値は `v1.0` です。
max-pages	maxPages	ページ数 (ページングをサポートするリソースの場合のオプション)。既定値は 3 です。この値を 0 に設定すると、すべてのページが取得されます。
cache-enabled	cacheEnabled	ブール値 (オプション)。設定すると、リソースからの応答がキャッシュされることを示します。 `refresh()`が呼び出された場合、または`pollingRate`が使用中の場合はオーバーライドします。既定値は `false` です。
cache-invalidation-period	cacheInvalidationPeriod	オプションのミリ秒単位。 `cacheEnabled`と組み合わせて設定すると、キャッシュが無効化期間に達するまでの遅延によって、この値が変更されます。既定値は `0` で、既定の無効化期間が使用されます。
該当なし	response	要求が成功した場合の Microsoft Graph からの読み取り専用の応答。
該当なし	error	要求が成功しなかった場合の Microsoft Graph からの読み取り専用エラー。

CSS カスタムプロパティ

mgt-picker コンポーネントは、オーバーライドを提供するために、次の CSS カスタムプロパティを定義します。

<mgt-picker
  class="picker"
  resource="me/todo/lists"
  scopes="tasks.read, tasks.readwrite"
  key-name="displayName"
></mgt-picker>

.picker {
  --picker-background-color: grey;
  --picker-list-max-height: 200px;
}

詳細については、「コンポーネントのスタイリング」を参照してください。

メソッド

メソッド	説明
refresh(force?: boolean)	メソッドを呼び出してデータを更新します。既定では、UI はデータが変更された場合にのみ更新されます。強制的にコンポーネントを更新するには、`true` を渡します。

イベント

イベント	いつ出力されるか	カスタムデータ	キャンセル	泡	カスタムテンプレートを使用する
`selectionChanged`	ドロップダウンで選択したリソースに変更がある場合に発生します。	`{ response: any, error: any }`. `response` プロパティには、Microsoft Graph から取得した応答が含まれています。 `error` プロパティには、エラーが発生した場合のエラーに関する情報が含まれます	不要	はい	はい

ヒント

response プロパティで返されるデータの詳細については、Picker コンポーネントの resource プロパティで使用した API の API リファレンスを参照してください。

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

テンプレート

mgt-picker コンポーネントは、外観を定義するために使用できるいくつかのテンプレートをサポートしています。テンプレートを指定するには、コンポーネント内に <template> 要素を含め、 data-type を次のいずれかの値に設定します。

データ型	データコンテキスト	説明
error	Microsoft Graph からのエラー。	このテンプレートは、要求の作成中にエラーが発生した場合に使用されます。
loading	該当なし	このテンプレートは要求が行われている間に使用されます。
no-data	該当なし	このテンプレートは、要求がデータを返さなかった場合に使用されます。

テンプレートの使用例

<mgt-picker resource="me/todo/lists" scopes="tasks.read, tasks.readwrite" key-name="displayName">
  <div>Loading template</div>
    <template data-type="loading">
      Loading
    </template>
    <template data-type="no-data">
      <div>No data</div>
    </template>
    <template data-type="error">
      <div>Error</div>
    </template>
  </div>
</mgt-picker>

Microsoft Graph のアクセス許可

このコンポーネントに必要なアクセス許可は、Microsoft Graph から取得するデータによって異なります。 Microsoft Graph Toolkit は、現在のユーザーが提供された scopesの少なくとも 1 つに同意したことを確認します。 Microsoft Graph で使用できるアクセス許可の詳細については、「Microsoft Graph のアクセス許可のリファレンス」を参照してください。

認証

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

キャッシュ

キャッシュを有効にして構成するには、 cacheEnabled プロパティと cacheInvalidationPeriod プロパティを使用します。既定では、 mgt-picker コンポーネントは応答をキャッシュしません。

オブジェクトストア	キャッシュされたデータ	解説
`response`	の `resource` プロパティで指定されたクエリに対して、Microsoft Graph から取得した完全な応答 `mgt-picker`

詳細については、「キャッシュ」を参照してください。

ローカリゼーション

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

文字列名	既定値
comboboxPlaceholder	`Select an item`

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-08-12