Microsoft Graph 工具包中的 Picker 组件

项目
02/08/2024

选取器组件使用 mgt-get 查询 Microsoft 图形 API然后呈现一个下拉列表控件，允许从资源数组中选择单个资源。

示例

以下示例演示如何使用 mgt-picker 组件从用户的任务列表中选择任务列表。可以使用代码编辑器查看属性和属性如何更改组件的行为。

HTML
React

在 mgt.dev 中打开此示例。

属性和属性

可以使用多个属性来更改组件的行为。组件具有必需的属性，例如 resource 和 /userskey-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`) 。
占位符	占位符	例如，在选取器中呈现的占位符 (或 `Select a userSelect a task list`) 。
key-name	keyName	要呈现在选取器中的键 (例如 `displayName` ，) 。
selected-value	selectedValue	可选。要在选取器中设置为当前所选选项的值。必须存在于 Microsoft Graph 查询提供的选项中。
scopes	scopes	可选的字符串数组（如果使用属性）或逗号分隔的范围（如果使用属性）。组件和支持的提供程序确保用户已同意至少一个提供的权限。
version	version	发出 `GET` 请求时要使用的可选 API 版本。默认值为“`v1.0`”。
max-pages	maxPages	支持分页) 的资源的可选页数 (。默认值为 3。将此值设置为 0 将检索所有页面。
已启用缓存	cacheEnabled	可选属性，类型为 Boolean。设置后，它指示缓存了来自资源的响应。如果 `refresh()` 调用或正在使用，则 `pollingRate` 重写。默认值为“`false`”。
cache-invalidation-period	cacheInvalidationPeriod	可选的毫秒数。当与 `cacheEnabled`组合设置时，缓存达到其失效期限之前的延迟会修改此值。默认值为 `0` ，并使用默认无效期限。
不适用	响应	如果请求成功，则提供来自 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;
}

若要了解详细信息，请参阅设置组件样式。

方法

方法	说明
刷新 (force？：布尔)	调用方法以刷新数据。默认情况下，仅当数据发生更改时，UI 才会更新。传递 `true` 以强制更新组件。

事件

事件	何时发出	自定义数据	可取消	泡沫	使用自定义模板
`selectionChanged`	下拉列表中所选资源发生更改时触发。	`{ response: any, error: any }`. 属性 `response` 包含从 Microsoft Graph 检索的响应。属性 `error` 包含有关错误的信息（如果发生错误）	否	是	是

提示

有关属性中 response 返回的数据的详细信息，请参阅在 Picker 组件的属性中使用的 resource API 的 API 参考。

有关处理事件的详细信息，请参阅事件。

模板

组件 mgt-picker 支持多个模板，可用于定义外观。若要指定模板，请在组件中包含元素 <template> ，并将设置为 data-type 以下值之一。

数据类型	数据上下文	说明
error	来自 Microsoft Graph 的错误。	如果发出请求时出错，则使用此模板。
加载	不适用	发出请求时使用此模板。
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 工具包验证当前用户是否同意至少一个提供的 scopes。有关权限的详细信息，请参阅 Microsoft Graph 权限参考。

身份验证

控件使用身份验证文档中所述的全局身份验证提供程序来提取所需的数据。

缓存

若要启用和配置缓存，请使用 cacheEnabled 和 cacheInvalidationPeriod 属性。默认情况下， mgt-picker 组件不缓存任何响应。

对象存储	缓存的数据	备注
`response`	为的属性中指定的 `resource` 查询从 Microsoft Graph 检索到的完整响应 `mgt-picker`

有关详细信息，请参阅缓存。

本地化

控件公开以下可本地化的变量。有关如何设置本地化的详细信息，请参阅本地化组件。

字符串名称	默认值
comboboxPlaceholder	`Select an item`