Microsoft Graph 工具包中的分类选取器组件

项目
11/07/2024

分类选取器是一个组件，它可以查询 Microsoft 图形 API的分类，并使用术语呈现下拉列表控件，从而允许基于指定的术语集id或指定术语集id和指定术语的组合来选择单个术语id。

组件检索指定术语集或术语下存在的第一级术语。如果仅提供术语集 ID，则返回该术语集下的第一级术语。如果同时提供了术语集 ID 和术语 ID，则返回指定术语下的第一级术语。

注意此功能目前支持来自术语库 的单一术语 选择。

示例

以下示例演示了如何使用 mgt-taxonomy-picker 组件从术语集中选择术语。

HTML
React

在 mgt.dev 中打开此示例。

属性和属性

可以使用多个属性来更改组件的行为。所需的属性为 term-set-id。

属性	属性	说明	类型
term-set-id	termsetId	强制性。要从中检索一级术语的术语的 ID。	String
term-id	termId	可选。要从中检索第一级术语的术语的 ID。如果未提供，函数将检索由 `term-set-id`指定的术语集下的第一级术语。请注意，此术语必须是 ID `term-set-id`为的术语集下的术语之一。	String
site-id	siteId	可选。存在术语集的网站 ID。如果未指定，则假定术语集位于租户级别。	String
version	version	可选。发出 GET 请求时要使用的 API 版本。默认值为“`beta`”。	String
占位符	占位符	可选。在组合框中使用的占位符。默认值为 `Select a term`。	string
区域设置	区域设置	可选。需要显示的术语的区域设置。仅当术语具有不同语言的多个标签时，这才有用。	String
default-selected-term-id	defaultSelectedTermId	可选。默认情况下应选择的术语的 ID。	String
position	position	可选。下拉列表的位置。可以是“above”或“below”。默认值为 `below`	String
禁用	禁用	可选。设置是否禁用分类选取器。禁用后，用户无法搜索或选择术语。	不适用
已启用缓存	cacheEnabled	可选。设置后，它指示将缓存来自资源的响应。默认值为“`false`”。	Boolean
cache-invalidation-period	cacheInvalidationPeriod	可选。 () 毫秒数与 `cacheEnabled`结合使用时，缓存达到其失效期之前的延迟将由此值修改。默认值为 `0` ，并将使用默认无效期限。	数字

以下示例将组件的行为更改为提取指定术语集的第一级子术语。

<mgt-taxonomy-picker
  term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
></mgt-taxonomy-picker>

以下示例更改组件的行为，以提取指定术语的第一级子术语。

<mgt-taxonomy-picker
  term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
  term-id="a56caeb7-3b7d-4d22-93a9-0232e12905f6"
></mgt-taxonomy-picker>

以下示例更改组件的行为，以提取指定术语的第一级子术语的法语标签。

<mgt-taxonomy-picker
  term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
  term-id="a56caeb7-3b7d-4d22-93a9-0232e12905f6"
  locale="fr-FR"
></mgt-taxonomy-picker>

以下示例更改组件的行为，以提取指定网站中存在的指定术语集的第一级子术语。

<mgt-taxonomy-picker
  term-set-id="7889007a-fb0e-449f-b629-dedf63ae53de"
  site-id="contoso.sharepoint.com,0962bcef-48f1-4460-baa8-b7286dcb249b,ba412b3c-951a-4322-ac37-0fe6307b5987"
></mgt-taxonomy-picker>

以下示例将组件的行为更改为提取指定术语集的第一级子术语，并设置默认选择的指定术语。

<mgt-taxonomy-picker
  term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
  default-selected-term-id="7ab1d163-f691-4676-88b3-c2d8921b73eb"
></mgt-taxonomy-picker>

CSS 自定义属性

组件 mgt-taxonomy-picker 定义以下 CSS 自定义属性，用于提供替代。

<mgt-taxonomy-picker
  class="taxonomy-picker"
  term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
></mgt-taxonomy-picker>

.taxonomy-picker {
  --taxonomy-picker-background-color: grey;
  --taxonomy-picker-list-max-height: 200px;
  --taxonomy-picker-background-color: black;
  --taxonomy-picker-placeholder-color: white;
  
}

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

方法

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

事件

事件	何时发出	自定义数据	可取消	泡沫	使用自定义模板
`selectionChanged`	当用户对下拉列表中的选择进行更改时触发。	将属于该类型的所选术语 `TermStore.Term`	否	是	是

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

模板

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

数据类型	数据上下文	说明
error	来自 Microsoft Graph 的错误。	如果发出请求时出错，则使用此模板。
加载	不适用	发出请求时使用此模板。
no-data	不适用	请求未返回任何数据时使用此模板。

模板用法示例

<mgt-taxonomy-picker term-set-id="138a652e-7f23-46f6-b480-13da2308c235">
  <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-taxonomy-picker>

Microsoft Graph 权限

此组件使用以下 Microsoft Graph API 和权限。对于每个调用的 API，用户必须至少具有列出的权限之一。

配置	权限	API
默认	TermStore.Read.All、TermStore.ReadWrite.All	/termStore/sets/{setId}/children
默认	TermStore.Read.All、TermStore.ReadWrite.All	/termStore/sets/{setId}/terms/{termId}/children
`site-id` 已设置	TermStore.Read.All、TermStore.ReadWrite.All	/sites/{site-id}/termStore/sets/{set-id}/children
`site-id` 已设置	TermStore.Read.All、TermStore.ReadWrite.All	/sites/{site-id}/termStore/sets/{set-id}/terms/{term-id}/children

有关权限的详细信息，请参阅 Microsoft Graph 权限参考。

身份验证

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

缓存

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

对象存储	缓存的数据	备注
`response`	从 Microsoft Graph 检索到的术语的完整响应。

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

本地化

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

字符串名称	默认值
comboboxPlaceholder	`Select a term`
loadingMessage	`Loading...`
noTermsFound	`No terms found`
termsetIdRequired	`The termsetId property or termset-id attribute is required`

通过