umbraco-collection

Umbraco コレクション

これは何ですか？

コレクションは、Umbraco バックオフィスでエンティティのリストを表示するもので、複数のビュー（テーブル、グリッド）、フィルタリング、ページネーション、選択、一括アクションを標準でサポートしています。コレクションはデータのためにリポジトリに接続し、アイテムのリストを閲覧して操作するための標準化された方法を提供します。

ドキュメント

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

• メインドキュメント: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections
• コレクションビュー: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection-view
• Foundation: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation
• 拡張機能レジストリ: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-registry

コレクションのアーキテクチャ

完全なコレクションは以下のコンポーネントで構成されます：

collection/
├── manifests.ts              # Main collection manifest
├── constants.ts              # Alias constants
├── types.ts                  # Item and filter types
├── my-collection.context.ts  # Collection context (extends UmbDefaultCollectionContext)
├── my-collection.element.ts  # Collection element (extends UmbCollectionDefaultElement)
├── repository/
│   ├── manifests.ts
│   ├── my-collection.repository.ts    # Implements UmbCollectionRepository
│   └── my-collection.data-source.ts   # API calls
├── views/
│   ├── manifests.ts
│   └── table/
│       └── my-table-view.element.ts   # Table view
└── action/
    ├── manifests.ts
    └── my-action.element.ts           # Collection action

リファレンス例

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

場所: /Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/collection/

この例では、リポジトリ、ビュー、コンテキストを備えた完全なカスタムコレクションを示しています。本番環境のパターンとしてこれを研究してください。

関連する Foundation スキル

• リポジトリパターン: コレクションはデータアクセスのためにリポジトリを必要とします

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

• Context API: ビューでコレクションコンテキストにアクセスするために使用します

  • 参照スキル: umbraco-context-api

• 状態管理: オブザーバブルとリアクティブデータを理解するために使用します

  • 参照スキル: umbraco-state-management

ワークフロー

1. ドキュメントを取得 - 上記の URL に対して WebFetch を使用します
2. 質問する - どのエンティティですか？どのリポジトリですか？どのビューが必要ですか？どのアクションですか？
3. 型を定義 - アイテムモデルとフィルターモデルのインターフェースを作成します
4. リポジトリを作成 - データソースとリポジトリを実装します
5. コンテキストを作成 - カスタム動作が必要な場合は UmbDefaultCollectionContext を拡張します
6. ビューを作成 - テーブル/グリッドビューを実装します
7. アクションを作成 - コレクションアクション（作成、更新など）を追加します
8. 説明 - 作成した内容とテスト方法を示します

完全な例

1. 定数 (constants.ts)

export const MY_COLLECTION_ALIAS = 'My.Collection';
export const MY_COLLECTION_REPOSITORY_ALIAS = 'My.Collection.Repository';

2. 型 (types.ts)

export interface MyCollectionItemModel {
  unique: string;
  entityType: string;
  name: string;
  // Add other fields
}

export interface MyCollectionFilterModel {
  skip?: number;
  take?: number;
  filter?: string;
  orderBy?: string;
  orderDirection?: 'asc' | 'desc';
  // Add custom filters
}

3. データソース (repository/my-collection.data-source.ts)

import type { MyCollectionItemModel, MyCollectionFilterModel } from '../types.js';
import type { UmbCollectionDataSource } from '@umbraco-cms/backoffice/collection';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';

export class MyCollectionDataSource implements UmbCollectionDataSource<MyCollectionItemModel> {
  #host: UmbControllerHost;

  constructor(host: UmbControllerHost) {
    this.#host = host;
  }

  async getCollection(filter: MyCollectionFilterModel) {
    // Call your API here
    const response = await fetch(`/api/my-items?skip=${filter.skip}&take=${filter.take}`);
    const data = await response.json();

    const items: MyCollectionItemModel[] = data.items.map((item: any) => ({
      unique: item.id,
      entityType: 'my-entity',
      name: item.name,
    }));

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

4. リポジトリ (repository/my-collection.repository.ts)

import type { MyCollectionFilterModel } from '../types.js';
import { MyCollectionDataSource } from './my-collection.data-source.js';
import { UmbRepositoryBase } from '@umbraco-cms/backoffice/repository';
import type { UmbCollectionRepository } from '@umbraco-cms/backoffice/collection';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';

export class MyCollectionRepository extends UmbRepositoryBase implements UmbCollectionRepository {
  #dataSource: MyCollectionDataSource;

  constructor(host: UmbControllerHost) {
    super(host);
    this.#dataSource = new MyCollectionDataSource(host);
  }

  async requestCollection(filter: MyCollectionFilterModel) {
    return this.#dataSource.getCollection(filter);
  }
}

export default MyCollectionRepository;

5. リポジトリマニフェスト (repository/manifests.ts)

import { MY_COLLECTION_REPOSITORY_ALIAS } from '../constants.js';

export const manifests: Array<UmbExtensionManifest> = [
  {
    type: 'repository',
    alias: MY_COLLECTION_REPOSITORY_ALIAS,
    name: 'My Collection Repository',
    api: () => import('./my-collection.repository.js'),
  },
];

6. コレクションコンテキスト (my-collection.context.ts)

import type { MyCollectionItemModel, MyCollectionFilterModel } from './types.js';
import { UmbDefaultCollectionContext } from '@umbraco-cms/backoffice/collection';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';

// Default view alias - must match one of your collectionView aliases
const MY_TABLE_VIEW_ALIAS = 'My.CollectionView.Table';

export class MyCollectionContext extends UmbDefaultCollectionContext<
  MyCollectionItemModel,
  MyCollectionFilterModel
> {
  constructor(host: UmbControllerHost) {
    super(host, MY_TABLE_VIEW_ALIAS);
  }

  // Override or add custom methods if needed
}

export { MyCollectionContext as api };

7. コレクション要素 (my-collection.element.ts)

import { customElement } from '@umbraco-cms/backoffice/external/lit';
import { UmbCollectionDefaultElement } from '@umbraco-cms/backoffice/collection';

@customElement('my-collection')
export class MyCollectionElement extends UmbCollectionDefaultElement {
  // Override renderToolbar() to customize header
  // protected override renderToolbar() {
  //   return html`<umb-collection-toolbar slot="header"></umb-collection-toolbar>`;
  // }
}

export default MyCollectionElement;
export { MyCollectionElement as element };

declare global {
  interface HTMLElementTagNameMap {
    'my-collection': MyCollectionElement;
  }
}

8. テーブルビュー (views/table/my-table-view.element.ts)

import type { MyCollectionItemModel } from '../../types.js';
import { UMB_COLLECTION_CONTEXT } from '@umbraco-cms/backoffice/collection';
import { css, customElement, html, state } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import type { UmbTableColumn, UmbTableConfig, UmbTableItem } from '@umbraco-cms/backoffice/components';

@customElement('my-table-collection-view')
export class MyTableCollectionViewElement extends UmbLitElement {
  @state()
  private _tableItems: Array<UmbTableItem> = [];

  @state()
  private _selection: Array<string> = [];

  #collectionContext?: typeof UMB_COLLECTION_CONTEXT.TYPE;

  private _tableConfig: UmbTableConfig = {
    allowSelection: true,
  };

  private _tableColumns: Array<UmbTableColumn> = [
    { name: 'Name', alias: 'name', allowSorting: true },
    { name: '', alias: 'entityActions', align: 'right' },
  ];

  constructor() {
    super();
    this.consumeContext(UMB_COLLECTION_CONTEXT, (context) => {
      this.#collectionContext = context;
      // IMPORTANT: Call setupView for workspace modal routing
      context?.setupView(this);
      this.#observeItems();
      this.#observeSelection();
    });
  }

  #observeItems() {
    if (!this.#collectionContext) return;

    this.observe(
      this.#collectionContext.items,
      (items) => {
        this._tableItems = (items as MyCollectionItemModel[]).map((item) => ({
          id: item.unique,
          icon: 'icon-document',
          entityType: item.entityType,
          data: [
            { columnAlias: 'name', value: item.name },
            {
              columnAlias: 'entityActions',
              value: html`<umb-entity-actions-table-column-view
                .value=${{ entityType: item.entityType, unique: item.unique }}
              ></umb-entity-actions-table-column-view>`,
            },
          ],
        }));
      },
      '_observeItems',
    );
  }

  #observeSelection() {
    if (!this.#collectionContext) return;

    this.observe(
      this.#collectionContext.selection.selection,
      (selection) => {
        this._selection = selection as string[];
      },
      '_observeSelection',
    );
  }

  #handleSelect(event: CustomEvent) {
    event.stopPropagation();
    const table = event.target as any;
    this.#collectionContext?.selection.setSelection(table.selection);
  }

  #handleDeselect(event: CustomEvent) {
    event.stopPropagation();
    const table = event.target as any;
    this.#collectionContext?.selection.setSelection(table.selection);
  }

  override render() {
    return html`
      <umb-table
        .config=${this._tableConfig}
        .columns=${this._tableColumns}
        .items=${this._tableItems}
        .selection=${this._selection}
        @selected=${this.#handleSelect}
        @deselected=${this.#handleDeselect}
      ></umb-table>
    `;
  }
}

export default MyTableCollectionViewElement;

declare global {
  interface HTMLElementTagNameMap {
    'my-table-collection-view': MyTableCollectionViewElement;
  }
}

9. ビューマニフェスト (views/manifests.ts)

import { MY_COLLECTION_ALIAS } from '../constants.js';
import { UMB_COLLECTION_ALIAS_CONDITION } from '@umbraco-cms/backoffice/collection';

export const manifests: Array<UmbExtensionManifest> = [
  {
    type: 'collectionView',
    alias: 'My.CollectionView.Table',
    name: 'My Table Collection View',
    element: () => import('./table/my-table-view.element.js'),
    weight: 200,
    meta: {
      label: 'Table',
      icon: 'icon-list',
      pathName: 'table',
    },
    conditions: [
      {
        alias: UMB_COLLECTION_ALIAS_CONDITION,
        match: MY_COLLECTION_ALIAS,
      },
    ],
  },
];

10. コレクションアクション (action/manifests.ts)

import { MY_COLLECTION_ALIAS } from '../constants.js';
import { UMB_COLLECTION_ALIAS_CONDITION } from '@umbraco-cms/backoffice/collection';

export const manifests: Array<UmbExtensionManifest> = [
  {
    type: 'collectionAction',
    kind: 'button',
    alias: 'My.CollectionAction.Refresh',
    name: 'Refresh Collection Action',
    element: () => import('./refresh-action.element.js'),
    weight: 100,
    meta: {
      label: 'Refresh',
    },
    conditions: [
      {
        alias: UMB_COLLECTION_ALIAS_CONDITION,
        match: MY_COLLECTION_ALIAS,
      },
    ],
  },
];

11. メインコレクションマニフェスト (manifests.ts)

import { manifests as repositoryManifests } from './repository/manifests.js';
import { manifests as viewManifests } from './views/manifests.js';
import { manifests as actionManifests } from './action/manifests.js';
import { MY_COLLECTION_ALIAS, MY_COLLECTION_REPOSITORY_ALIAS } from './constants.js';

export const manifests: Array<UmbExtensionManifest> = [
  {
    type: 'collection',
    alias: MY_COLLECTION_ALIAS,
    name: 'My Collection',
    api: () => import('./my-collection.context.js'),
    element: () => import('./my-collection.element.js'),
    meta: {
      repositoryAlias: MY_COLLECTION_REPOSITORY_ALIAS,
    },
  },
  ...repositoryManifests,
  ...viewManifests,
  ...actionManifests,
];

ダッシュボードでのコレクションのレンダリング

import { html, customElement } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';

@customElement('my-dashboard')
export class MyDashboardElement extends UmbLitElement {
  override render() {
    return html`<umb-collection alias="My.Collection"></umb-collection>`;
  }
}

組み込み機能

コレクションシステムはこれらの機能を自動的に提供します：

機能	説明
選択	context.selection 上の UmbSelectionManager
ページネーション	context.pagination 上の UmbPaginationManager
読み込み状態	context.loading 経由のオブザーバブル
アイテム	context.items 経由のオブザーバブル
合計数	context.totalItems 経由のオブザーバブル
フィルタリング	context.setFilter() メソッド経由
ビューの切り替え	UmbCollectionViewManager による複数ビュー

主要な条件

UMB_COLLECTION_ALIAS_CONDITION を使用してコレクションをターゲットにします：

import { UMB_COLLECTION_ALIAS_CONDITION } from '@umbraco-cms/backoffice/collection';

conditions: [
  {
    alias: UMB_COLLECTION_ALIAS_CONDITION,
    match: 'My.Collection',
  },
],

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