umbraco-picker-data-source

用途

Umbraco Picker Data Source 用于为 Umbraco 后台中基于选择器的属性编辑器（property editor）提供数据。它允许开发者创建自定义数据源，为内容选择器提供可选项，并定义这些项如何被获取、搜索以及在树形或集合视图中展示。适用于需要从自定义实体、外部 API 或现有内容的筛选子集中进行选择的场景。

主要能力

支持树形（tree）数据源：适用于具有父子层级关系的数据，可实现根节点、根级项、子项、祖先项以及按唯一 ID 获取项等请求。
支持集合（collection）数据源：适用于无层级的扁平列表。
支持可搜索数据源：通过 search 方法按查询字符串搜索项。
支持可选取过滤：通过 treePickableFilter 与 searchPickableFilter 决定哪些项可被选中（例如文件夹不可选）。
支持配置项：可在清单的 meta.settings 中定义设置属性，如起始节点（startNode）和类型过滤（filter）。
通过清单注册：使用 type 为 propertyEditorDataSource、dataSourceType 为 UMB_PICKER_DATA_SOURCE_TYPE 的清单进行注册。

使用方式

获取最新文档：实现前应使用 WebFetch 访问官方文档链接（Foundation、Extension Registry、Property Editors）。
明确需求：确定要选择的数据、使用树形还是集合、是否需要搜索、需要哪些配置选项。
生成文件：依据最新文档创建清单（manifest）与数据源类。
说明用法：展示所创建的内容以及如何与属性编辑器配合使用。

清单示例：

import { UMB_PICKER_DATA_SOURCE_TYPE } from '@umbraco-cms/backoffice/picker-data-source';

export const manifests: Array<UmbExtensionManifest> = [
  {
    type: 'propertyEditorDataSource',
    dataSourceType: UMB_PICKER_DATA_SOURCE_TYPE,
    alias: 'My.PropertyEditorDataSource.CustomPicker',
    name: 'Custom Picker Data Source',
    api: () => import('./my-picker-data-source.js'),
    meta: {
      label: 'Custom Items',
      icon: 'icon-list',
      description: 'Pick from custom items',
    },
  },
];

树形数据源需实现 UmbPickerTreeDataSource（可选 UmbPickerSearchableDataSource），包含 treePickableFilter、searchPickableFilter、requestTreeRoot、requestTreeRootItems、requestTreeItemsOf、requestTreeItemAncestors、requestItems、search 等方法。

集合数据源需实现 UmbPickerCollectionDataSource，包含 requestCollection 与 requestItems 方法。

可配置数据源在清单的 meta.settings.properties 中定义设置项，例如 startNode 使用 propertyEditorUiAlias 为 'Umb.PropertyEditorUi.ContentPicker.Source'，filter 使用 'Umb.PropertyEditorUi.ContentPicker.SourceType'。

适用场景

从自定义实体中选择项。
从外部 API 获取数据供选择。
从现有内容的筛选子集中选择。
需要树形层级或扁平集合展示的选择器。
需要搜索功能的选择器。
需要起始节点或类型过滤等配置的选择器。

限制

资料未提供具体的收费、价格、平台或效果信息。
实现前必须获取最新官方文档，示例代码应保持最小化并生成完整可运行的代码。
需确保 requestItems 返回与树形/集合相同格式的数据。
并非所有树形项都应可被选中，需通过过滤函数控制。

关键概念

dataSourceType：选择器数据源必须为 UMB_PICKER_DATA_SOURCE_TYPE。
treePickableFilter：决定哪些树形项可被选中。
searchPickableFilter：决定哪些搜索结果可被选中。
requestItems：按唯一 ID 返回项（用于展示已选值）。
entityType：标识实体类型（用于过滤与路由）。

最佳实践

实现搜索功能，用户期望在项较多的选择器中进行搜索。
使用合适的图标，帮助用户从视觉上识别项类型。
过滤可选取项，并非所有树形项都应可选（如文件夹）。
处理配置，在适用时支持起始节点与类型过滤。
返回一致的数据，确保 requestItems 与树形/集合返回相同格式。