umbraco-property-editor-ui

Umbraco 属性编辑器 UI

它是什么？

属性编辑器 UI 是用户在 Umbraco 后台中交互，用于输入和管理内容数据的可视化组件。它是属性编辑器的一半——UI（客户端 TypeScript）与定义数据存储的 Schema（服务器端 C#）配对使用。

文档

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

• 主要文档：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/property-editors
• 教程：https://docs.umbraco.com/umbraco-cms/extend-your-project/tutorials/creating-a-property-editor
• 配置：https://docs.umbraco.com/umbraco-cms/extend-your-project/tutorials/creating-a-property-editor/adding-configuration-to-a-property-editor
• 基础：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/property-editor/

此示例演示了一个带配置的完整属性编辑器 UI 实现。可参考其中适用于生产环境的模式。

相关基础技能

• Umbraco Element：使用 UmbElementMixin 实现 UI 元素时

  • 参考技能：umbraco-umbraco-element

• 状态管理：实现响应式值更新时

  • 参考技能：umbraco-state-management

• 本地化：为标签添加多语言支持时

  • 参考技能：umbraco-localization

工作流

1. 获取文档 - 对上述 URL 使用 WebFetch
2. 提问 - 数据类型是什么？需要哪些 UI 组件？有哪些配置选项？
3. 生成文件 - 根据最新文档创建 manifest 和元素
4. 说明 - 展示创建的内容及测试方法

最小示例

Manifest（umbraco-package.json）

**WARNING：**下面的 propertyEditorSchemaAlias 使用内置 Schema Umbraco.Plain.String。 如果使用 MyPackage.CustomSchema 这样的自定义别名，服务器上必须有对应的 C# DataEditor，否则创建 Data Type 时会出现 404 错误。

{
  "name": "My Property Editor",
  "extensions": [
    {
      "type": "propertyEditorUi",
      "alias": "My.PropertyEditorUi.Custom",
      "name": "My Custom Editor",
      "element": "/App_Plugins/MyEditor/editor.js",
      "elementName": "my-editor-ui",
      "meta": {
        "label": "My Custom Editor",
        "icon": "icon-edit",
        "group": "common",
        "propertyEditorSchemaAlias": "Umbraco.Plain.String"
      }
    }
  ]
}

元素实现（editor.ts）

import { LitElement, html, css, customElement, property } from '@umbraco-cms/backoffice/external/lit';
import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api';
import { UmbChangeEvent } from '@umbraco-cms/backoffice/event';
import type { UmbPropertyEditorUiElement } from '@umbraco-cms/backoffice/property-editor';

@customElement('my-editor-ui')
export default class MyEditorElement extends UmbElementMixin(LitElement) implements UmbPropertyEditorUiElement {
  @property({ type: String })
  public value = '';

  #onChange(e: Event) {
    const input = e.target as HTMLInputElement;
    this.value = input.value;
    this.dispatchEvent(new UmbChangeEvent());
  }

  render() {
    return html`
      <uui-input
        .value=${this.value || ''}
        @change=${this.#onChange}
      ></uui-input>
    `;
  }

  static styles = css`
    :host {
      display: block;
    }
  `;
}

declare global {
  interface HTMLElementTagNameMap {
    'my-editor-ui': MyEditorElement;
  }
}

带配置的示例

import type { UmbPropertyEditorConfigCollection } from '@umbraco-cms/backoffice/property-editor';

@customElement('my-editor-ui')
export default class MyEditorElement extends UmbElementMixin(LitElement) implements UmbPropertyEditorUiElement {
  @property({ type: String })
  public value = '';

  @state()
  private _maxChars?: number;

  @state()
  private _placeholder?: string;

  @property({ attribute: false })
  public set config(config: UmbPropertyEditorConfigCollection) {
    this._maxChars = config.getValueByAlias('maxChars');
    this._placeholder = config.getValueByAlias('placeholder');
  }

  render() {
    return html`
      <uui-input
        .value=${this.value || ''}
        .placeholder=${this._placeholder || ''}
        .maxlength=${this._maxChars}
        @change=${this.#onChange}
      ></uui-input>
    `;
  }
}

Manifest 中的配置

{
  "type": "propertyEditorUi",
  "alias": "My.PropertyEditorUi.Custom",
  "name": "My Custom Editor",
  "element": "/App_Plugins/MyEditor/editor.js",
  "elementName": "my-editor-ui",
  "meta": {
    "label": "My Custom Editor",
    "propertyEditorSchemaAlias": "Umbraco.Plain.String",
    "settings": {
      "properties": [
        {
          "alias": "maxChars",
          "label": "Maximum Characters",
          "propertyEditorUiAlias": "Umb.PropertyEditorUi.Integer"
        },
        {
          "alias": "placeholder",
          "label": "Placeholder Text",
          "propertyEditorUiAlias": "Umb.PropertyEditorUi.TextBox"
        }
      ],
      "defaultData": [
        { "alias": "maxChars", "value": 100 }
      ]
    }
  }
}

内置 Schema 别名（安全默认值）

Manifest 中的 propertyEditorSchemaAlias 必须引用服务器上存在的 Schema：

部分	位置	语言
属性编辑器 UI	客户端	TypeScript
属性编辑器 Schema	服务器	C#

• 内置 Schema（如下所列）始终可用——简单存储需求可使用这些 Schema
• 自定义 Schema需要 C# DataEditor 类——仅在需要自定义验证或转换时才需要

以下内置 Schema 始终可用：

Schema 别名	存储类型	使用场景
Umbraco.Plain.String	string	简单文本值
Umbraco.Integer	int	数字、评分、计数
Umbraco.Decimal	decimal	价格、百分比
Umbraco.Plain.Json	object	复杂 JSON 数据
Umbraco.DateTime	DateTime	日期和时间
Umbraco.TrueFalse	bool	切换开关、复选框
Umbraco.TextBox	string	带验证的文本框
Umbraco.TextArea	string	多行文本

故障排除

常见问题请参阅 TROUBLESHOOTING.md，包括：

• 创建 Data Type 时出现 404 错误
• 使用 Umbraco.Plain.Json 时值无法持久保存

UUI 组件问题（组合框、输入框等）请参阅 UUI-GOTCHAS.md。

---

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