umbraco-sorter

Umbraco 排序器

这是什么？

UmbSorterController 为 Umbraco 后台中的项目列表提供拖放排序功能。它可以处理容器内的项目重新排序、在容器之间移动项目，并支持嵌套排序场景。这适用于区块编辑器、内容树，以及任何需要用户自行调整顺序的 UI。

文档

实现前务必获取最新文档：

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

参考示例

Umbraco 源代码中包含可运行的示例：

嵌套容器：/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/sorter-with-nested-containers/

此示例演示了嵌套排序，项目可以包含子项目。

两个容器：/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/sorter-with-two-containers/

此示例展示了如何在两个独立容器之间移动项目。

相关基础技能

• 状态管理：用于顺序变化时的响应式更新

  • 参考技能：umbraco-state-management

• Umbraco 元素：用于创建可排序的项目元素

  • 参考技能：umbraco-umbraco-element

工作流

1. 获取文档 - 对上述 URL 使用 WebFetch
2. 提出问题 - 单个还是多个容器？是否有嵌套项目？数据模型是什么？
3. 生成文件 - 创建容器元素 + 项目元素 + 排序器设置
4. 说明 - 展示已创建的内容以及排序的工作方式

---

基础排序器设置

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

interface MyItem {
  id: string;
  name: string;
}

@customElement('my-sortable-list')
export class MySortableListElement extends UmbLitElement {
  #sorter = new UmbSorterController<MyItem, HTMLElement>(this, {
    // Get unique identifier from DOM element
    getUniqueOfElement: (element) => {
      return element.getAttribute('data-id') ?? '';
    },
    // Get unique identifier from data model
    getUniqueOfModel: (modelEntry) => {
      return modelEntry.id;
    },
    // Identifier shared by all connected sorters (for cross-container dragging)
    identifier: 'my-sortable-list',
    // CSS selector for sortable items
    itemSelector: '.sortable-item',
    // CSS selector for the container
    containerSelector: '.sortable-container',
    // Called when order changes
    onChange: ({ model }) => {
      this._items = model;
      this.requestUpdate();
      this.dispatchEvent(new CustomEvent('change', { detail: { items: model } }));
    },
  });

  @property({ type: Array, attribute: false })
  public get items(): MyItem[] {
    return this._items;
  }
  public set items(value: MyItem[]) {
    this._items = value;
    this.#sorter.setModel(value);
    this.requestUpdate();
  }
  private _items: MyItem[] = [];

  override render() {
    return html`
      <div class="sortable-container">
        ${repeat(
          this._items,
          (item) => item.id,
          (item) => html`
            <div class="sortable-item" data-id=${item.id}>
              ${item.name}
            </div>
          `
        )}
      </div>
    `;
  }
}

---

嵌套排序器（含子项目）

import { UmbSorterController } from '@umbraco-cms/backoffice/sorter';
import { html, customElement, property, repeat, css } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';

export interface NestedItem {
  name: string;
  children?: NestedItem[];
}

@customElement('my-sorter-group')
export class MySorterGroupElement extends UmbLitElement {
  #sorter = new UmbSorterController<NestedItem, MySorterItemElement>(this, {
    getUniqueOfElement: (element) => element.name,
    getUniqueOfModel: (modelEntry) => modelEntry.name,
    // IMPORTANT: Same identifier allows items to move between all nested groups
    identifier: 'my-nested-sorter',
    itemSelector: 'my-sorter-item',
    containerSelector: '.sorter-container',
    onChange: ({ model }) => {
      const oldValue = this._value;
      this._value = model;
      this.requestUpdate('value', oldValue);
      this.dispatchEvent(new CustomEvent('change'));
    },
  });

  @property({ type: Array, attribute: false })
  public get value(): NestedItem[] {
    return this._value ?? [];
  }
  public set value(value: NestedItem[]) {
    this._value = value;
    this.#sorter.setModel(value);
    this.requestUpdate();
  }
  private _value?: NestedItem[];

  override render() {
    return html`
      <div class="sorter-container">
        ${repeat(
          this.value,
          (item) => item.name,
          (item) => html`
            <my-sorter-item .name=${item.name}>
              
              <my-sorter-group
                .value=${item.children ?? []}
                @change=${(e: Event) => {
                  item.children = (e.target as MySorterGroupElement).value;
                }}
              ></my-sorter-group>
            </my-sorter-item>
          `
        )}
      </div>
    `;
  }

  static override styles = css`
    :host {
      display: block;
      min-height: 20px;
      border: 1px dashed rgba(122, 122, 122, 0.25);
      border-radius: var(--uui-border-radius);
      padding: var(--uui-size-space-1);
    }
  `;
}

---

可排序项目元素

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

@customElement('my-sorter-item')
export class MySorterItemElement extends UmbLitElement {
  @property({ type: String })
  name = '';

  override render() {
    return html`
      <div class="item-wrapper">
        <div class="drag-handle">
          <uui-icon name="icon-navigation"></uui-icon>
        </div>
        <div class="item-content">
          <span>${this.name}</span>
          <slot name="action"></slot>
        </div>
        <div class="children">
          <slot></slot>
        </div>
      </div>
    `;
  }

  static override styles = css`
    :host {
      display: block;
      background: var(--uui-color-surface);
      border: 1px solid var(--uui-color-border);
      border-radius: var(--uui-border-radius);
      margin: var(--uui-size-space-1) 0;
    }

    .item-wrapper {
      padding: var(--uui-size-space-3);
    }

    .drag-handle {
      cursor: grab;
      display: inline-block;
      margin-right: var(--uui-size-space-2);
    }

    .drag-handle:active {
      cursor: grabbing;
    }

    .children {
      margin-left: var(--uui-size-space-5);
      margin-top: var(--uui-size-space-2);
    }
  `;
}

declare global {
  interface HTMLElementTagNameMap {
    'my-sorter-item': MySorterItemElement;
  }
}

---

两个容器（跨容器排序）

@customElement('my-dual-sorter-dashboard')
export class MyDualSorterDashboard extends UmbLitElement {
  listOneItems: MyItem[] = [
    { id: '1', name: 'Apple' },
    { id: '2', name: 'Banana' },
  ];

  listTwoItems: MyItem[] = [
    { id: '3', name: 'Carrot' },
    { id: '4', name: 'Date' },
  ];

  override render() {
    return html`
      <div class="container">
        <my-sortable-list
          .items=${this.listOneItems}
          @change=${(e: CustomEvent) => {
            this.listOneItems = e.detail.items;
          }}
        ></my-sortable-list>

        <my-sortable-list
          .items=${this.listTwoItems}
          @change=${(e: CustomEvent) => {
            this.listTwoItems = e.detail.items;
          }}
        ></my-sortable-list>
      </div>
    `;
  }
}

要点：两个列表的 UmbSorterController 都使用相同的 identifier，才能在它们之间拖动项目。

---

UmbSorterController 选项

选项	类型	描述
identifier	string	关联排序器共用的 ID（启用跨容器拖动）
itemSelector	string	可排序项目的 CSS 选择器
containerSelector	string	容器的 CSS 选择器
getUniqueOfElement	(element) => string	从 DOM 元素中提取唯一 ID
getUniqueOfModel	(model) => string	从数据模型中提取唯一 ID
onChange	({ model }) => void	顺序变化时调用
onStart	() => void	开始拖动时调用
onEnd	() => void	结束拖动时调用

---

关键方法

// Set the model (call when items change externally)
this.#sorter.setModel(items);

// Get current model
const currentItems = this.#sorter.getModel();

// Disable sorting temporarily
this.#sorter.disable();

// Re-enable sorting
this.#sorter.enable();

---

拖动时应用的 CSS 类

类	应用于	时机
.umb-sorter-dragging	容器	任意项目正在拖动时
.umb-sorter-placeholder	占位元素	指示放置位置

---

最佳实践

1. 使用唯一标识符 - 每个项目都必须有唯一 ID
2. 谨慎匹配选择器 - itemSelector 和 containerSelector 必须与 DOM 匹配
3. 共用 identifier - 关联的排序器使用相同的 identifier
4. 处理嵌套更新 - 沿嵌套结构向上传递变更
5. 使用 repeat 指令 - 始终将 repeat() 与键函数搭配使用，以正确进行 DOM 差异比对
6. 提供视觉反馈 - 清晰地设置拖动手柄和放置区域的样式

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