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
• 基础知识：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/

此示例展示了一个包含存储库、视图和上下文的完整自定义集合。请参考此示例了解生产环境中的模式。

相关基础技能

• 存储库模式：集合需要存储库来访问数据

  • 参考技能：umbraco-repository-pattern

• 上下文 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',
  },
],

就是这样！务必获取最新文档，保持示例简洁，并生成完整可运行的代码。