umbraco-picker-data-source

Umbraco ピッカーデータソース

これは何ですか？

ピッカーデータソースは、ピッカーベースのプロパティエディターにデータを提供します。コンテンツピッカーに項目を供給するカスタムデータソースを作成でき、項目がどのように取得、検索、ツリーまたはコレクション形式で表示されるかを定義できます。これは、カスタムエンティティ、外部 API、または既存コンテンツのフィルタリングされたサブセットから選択するピッカーを作成するのに便利です。

ドキュメント

実装する前に、常に最新のドキュメントを取得してください：

• Foundation: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation
• Extension Registry: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-registry
• Property Editors: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/property-editors

リファレンス例

Umbraco のソースには動作する例が含まれています：

場所: /Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/picker-data-source/

この例では、複数のピッカーデータソースの実装を示しています：

• カスタムコレクションピッカー
• 検索付きカスタムツリーピッカー
• スタートノード構成付きドキュメントピッカー
• メディア、言語、Webhook、ユーザーピッカー

関連する Foundation スキル

• Repository Pattern: データ取得パターン向け

  • 参照スキル: umbraco-repository-pattern

• Tree: ツリーベースのピッカーデータソース向け

  • 参照スキル: umbraco-tree

ワークフロー

1. ドキュメントを取得 - 上記の URL に対して WebFetch を使用します
2. 質問する - どのデータを選択しますか？ ツリーまたはコレクション？ 検索は必要ですか？ 構成オプションは？
3. ファイルを生成 - 最新のドキュメントに基づいてマニフェスト + データソースクラスを作成します
4. 説明 - 作成された内容と、プロパティエディターでの使用方法を示します

---

マニフェストの例

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',
    },
  },
];

---

ツリーピッカーデータソース

親子関係を持つ階層データ向け：

import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';
import type {
  UmbPickerSearchableDataSource,
  UmbPickerTreeDataSource,
} from '@umbraco-cms/backoffice/picker-data-source';
import type { UmbSearchRequestArgs, UmbSearchResultItemModel } from '@umbraco-cms/backoffice/search';
import type { UmbTreeChildrenOfRequestArgs, UmbTreeItemModel } from '@umbraco-cms/backoffice/tree';

export class MyPickerTreeDataSource
  extends UmbControllerBase
  implements UmbPickerTreeDataSource, UmbPickerSearchableDataSource
{
  // Filter function to determine which items can be picked
  treePickableFilter: (treeItem: UmbTreeItemModel) => boolean = (treeItem) =>
    !!treeItem.unique && treeItem.entityType === 'my-entity';

  searchPickableFilter: (searchItem: UmbSearchResultItemModel) => boolean = (searchItem) =>
    !!searchItem.unique && searchItem.entityType === 'my-entity';

  // Return the root node (container for all items)
  async requestTreeRoot() {
    return {
      data: {
        unique: null,
        name: 'My Items',
        icon: 'icon-folder',
        hasChildren: true,
        entityType: 'my-entity-root',
        isFolder: true,
      },
    };
  }

  // Return items at the root level
  async requestTreeRootItems() {
    const rootItems = myItems.filter((item) => item.parent.unique === null);
    return {
      data: {
        items: rootItems,
        total: rootItems.length,
      },
    };
  }

  // Return children of a specific item
  async requestTreeItemsOf(args: UmbTreeChildrenOfRequestArgs) {
    const items = myItems.filter(
      (item) =>
        item.parent.entityType === args.parent.entityType &&
        item.parent.unique === args.parent.unique
    );
    return {
      data: {
        items: items,
        total: items.length,
      },
    };
  }

  // Return ancestors for breadcrumb navigation
  async requestTreeItemAncestors() {
    return { data: [] };
  }

  // Return specific items by their unique IDs
  async requestItems(uniques: Array<string>) {
    const items = myItems.filter((x) => uniques.includes(x.unique));
    return { data: items };
  }

  // Search items by query string
  async search(args: UmbSearchRequestArgs) {
    const result = myItems.filter((item) =>
      item.name.toLowerCase().includes(args.query.toLowerCase())
    );
    return {
      data: {
        items: result,
        total: result.length,
      },
    };
  }
}

export { MyPickerTreeDataSource as api };

// Sample data
const myItems: Array<UmbTreeItemModel> = [
  {
    unique: '1',
    entityType: 'my-entity',
    name: 'Item 1',
    icon: 'icon-document',
    parent: { unique: null, entityType: 'my-entity-root' },
    isFolder: false,
    hasChildren: false,
  },
  {
    unique: '2',
    entityType: 'my-entity',
    name: 'Item 2',
    icon: 'icon-document',
    parent: { unique: null, entityType: 'my-entity-root' },
    isFolder: false,
    hasChildren: false,
  },
];

---

コレクションピッカーデータソース

階層のないフラットなリスト向け：

import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';
import type { UmbPickerCollectionDataSource } from '@umbraco-cms/backoffice/picker-data-source';
import type { UmbCollectionItemModel } from '@umbraco-cms/backoffice/collection';

export class MyPickerCollectionDataSource
  extends UmbControllerBase
  implements UmbPickerCollectionDataSource
{
  async requestCollection() {
    const items: UmbCollectionItemModel[] = [
      { unique: '1', entityType: 'my-entity', name: 'Item 1', icon: 'icon-document' },
      { unique: '2', entityType: 'my-entity', name: 'Item 2', icon: 'icon-document' },
      { unique: '3', entityType: 'my-entity', name: 'Item 3', icon: 'icon-document' },
    ];

    return {
      data: {
        items,
        total: items.length,
      },
    };
  }

  async requestItems(uniques: Array<string>) {
    // Return specific items by unique IDs
    const allItems = await this.requestCollection();
    const items = allItems.data.items.filter((x) => uniques.includes(x.unique));
    return { data: items };
  }
}

export { MyPickerCollectionDataSource as api };

---

構成付きデータソース

ピッカーデータソースに設定を追加します：

export const manifests: Array<UmbExtensionManifest> = [
  {
    type: 'propertyEditorDataSource',
    dataSourceType: UMB_PICKER_DATA_SOURCE_TYPE,
    alias: 'My.PropertyEditorDataSource.ConfigurablePicker',
    name: 'Configurable Picker Data Source',
    api: () => import('./my-configurable-picker-data-source.js'),
    meta: {
      label: 'Configurable Items',
      icon: 'icon-settings',
      description: 'Pick items with configuration options',
      settings: {
        properties: [
          {
            alias: 'startNode',
            label: 'Start Node',
            description: 'Select where to start picking from',
            propertyEditorUiAlias: 'Umb.PropertyEditorUi.ContentPicker.Source',
          },
          {
            alias: 'filter',
            label: 'Filter Types',
            description: 'Select which types can be picked',
            propertyEditorUiAlias: 'Umb.PropertyEditorUi.ContentPicker.SourceType',
          },
        ],
      },
    },
  },
];

---

インターフェース

interface UmbPickerTreeDataSource {
  treePickableFilter?: (treeItem: UmbTreeItemModel) => boolean;
  requestTreeRoot(): Promise<{ data: UmbTreeItemModel }>;
  requestTreeRootItems(): Promise<{ data: { items: UmbTreeItemModel[]; total: number } }>;
  requestTreeItemsOf(args: UmbTreeChildrenOfRequestArgs): Promise<{ data: { items: UmbTreeItemModel[]; total: number } }>;
  requestTreeItemAncestors(): Promise<{ data: UmbTreeItemModel[] }>;
  requestItems(uniques: string[]): Promise<{ data: UmbTreeItemModel[] }>;
}

interface UmbPickerSearchableDataSource {
  searchPickableFilter?: (searchItem: UmbSearchResultItemModel) => boolean;
  search(args: UmbSearchRequestArgs): Promise<{ data: { items: UmbSearchResultItemModel[]; total: number } }>;
}

interface UmbPickerCollectionDataSource {
  requestCollection(): Promise<{ data: { items: UmbCollectionItemModel[]; total: number } }>;
  requestItems(uniques: string[]): Promise<{ data: UmbCollectionItemModel[] }>;
}

---

主要な概念

概念	説明
dataSourceType	ピッカーデータソースの場合は UMB_PICKER_DATA_SOURCE_TYPE である必要があります
treePickableFilter	どのツリー項目を選択できるかを決定する関数
searchPickableFilter	どの検索結果を選択できるかを決定する関数
requestItems	一意の ID によって項目を返します（選択された値の表示用）
entityType	エンティティの種類を識別します（フィルタリングとルーティングに使用）

---

ベストプラクティス

1. 検索を実装する - 項目が多いピッカーでは、ユーザーは検索できることを期待します
2. 適切なアイコンを使用する - ユーザーが項目の種類を視覚的に識別できるようにします
3. 選択可能な項目をフィルタリングする - すべてのツリー項目が選択可能であるべきではありません（例：フォルダー）
4. 構成を処理する - 該当する場合はスタートノードと種類フィルターをサポートします
5. 一貫したデータを返す - requestItems がツリー/コレクションと同じ形式を返すようにします

以上です！ 常に最新のドキュメントを取得し、例は最小限に保ち、完全に動作するコードを生成してください。