Back to Details

umbraco-property-editor-ui

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Umbraco Property Editor UI

Umbraco 属性编辑器UI

What is it?

什么是属性编辑器UI？

A Property Editor UI is the visual component that users interact with in the Umbraco backoffice to input and manage content data. It's one half of a property editor - the UI (client-side TypeScript) pairs with a Schema (server-side C#) that defines data storage.
属性编辑器UI是用户在Umbraco后台中与之交互的可视化组件，用于输入和管理内容数据。它是属性编辑器的组成部分之一——UI（客户端TypeScript）与定义数据存储的Schema（服务器端C#）配对使用。

Documentation

文档资料

Always fetch the latest docs before implementing:
在实现前请务必获取最新文档：

Reference Example

参考示例

The Umbraco source includes a working example:
Location: 
/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/property-editor/
This example demonstrates a complete property editor UI implementation with configuration. Study this for production patterns.
Umbraco源码中包含一个可用示例：
位置：
/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/property-editor/
该示例展示了一个完整的带配置的属性编辑器UI实现。可参考此示例学习生产环境中的开发模式。

Related Foundation Skills

相关基础技能

  • Umbraco Element: When implementing the UI element with UmbElementMixin
    • Reference skill: 
      umbraco-umbraco-element
  • State Management: When implementing reactive value updates
    • Reference skill: 
      umbraco-state-management
  • Localization: When adding multi-language support to labels
    • Reference skill: 
      umbraco-localization
  • Umbraco Element：使用UmbElementMixin实现UI元素时
    • 参考技能：
      umbraco-umbraco-element
  • 状态管理：实现响应式值更新时
    • 参考技能：
      umbraco-state-management
  • 本地化：为标签添加多语言支持时
    • 参考技能：
      umbraco-localization

Workflow

工作流程

  1. Fetch docs - Use WebFetch on the URLs above
  2. Ask questions - What data type? What UI components needed? Configuration options?
  3. Generate files - Create manifest + element based on latest docs
  4. Explain - Show what was created and how to test
  1. 获取文档 - 使用WebFetch访问上述URL
  2. 明确需求 - 确定数据类型？需要哪些UI组件？配置选项有哪些？
  3. 生成文件 - 根据最新文档创建清单（manifest）和元素文件
  4. 说明解释 - 展示创建的内容以及测试方法

Minimal Examples

最简示例

Manifest (umbraco-package.json)

清单文件（umbraco-package.json）

WARNING: The 
propertyEditorSchemaAlias
below uses 
Umbraco.Plain.String
, a built-in schema. If you use a custom alias like 
MyPackage.CustomSchema
, you MUST have a corresponding C# 
DataEditor
on the server or you'll get a 404 error when creating a Data Type.
json
{
  "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"
      }
    }
  ]
}
警告： 下方的
propertyEditorSchemaAlias
使用了内置的Schema
Umbraco.Plain.String
。 如果使用自定义别名如
MyPackage.CustomSchema
，则必须在服务器端有对应的C# 
DataEditor
类，否则在创建数据类型时会出现404错误。
json
{
  "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"
      }
    }
  ]
}

Element Implementation (editor.ts)

元素实现（editor.ts）

typescript
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;
  }
}
typescript
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;
  }
}

With Configuration

带配置的实现

typescript
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>
    `;
  }
}
typescript
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>
    `;
  }
}

Configuration in Manifest

清单中的配置

json
{
  "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 }
      ]
    }
  }
}
json
{
  "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 }
      ]
    }
  }
}

Built-in Schema Aliases (Safe Defaults)

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

The 
propertyEditorSchemaAlias
in your manifest must reference a schema that exists on the server:
PartLocationLanguage
Property Editor UIClientTypeScript
Property Editor SchemaServerC#
  • Built-in schemas (listed below) are always available - use these for simple storage needs
  • Custom schemas require a C# 
    DataEditor
    class - only needed for custom validation/conversion
These built-in schemas are always available:
Schema AliasStoresUse Case
Umbraco.Plain.String
string
Simple text values
Umbraco.Integer
int
Numbers, ratings, counts
Umbraco.Decimal
decimal
Prices, percentages
Umbraco.Plain.Json
object
Complex JSON data
Umbraco.DateTime
DateTime
Dates and times
Umbraco.TrueFalse
bool
Toggles, checkboxes
Umbraco.TextBox
string
Textbox with validation
Umbraco.TextArea
string
Multi-line text
清单中的
propertyEditorSchemaAlias
必须引用服务器端已存在的Schema：
组件位置语言
属性编辑器UI客户端TypeScript
属性编辑器Schema服务器端C#
  • 内置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

故障排除

See TROUBLESHOOTING.md for common issues including:
  • 404 errors when creating Data Types
  • Values not persisting with 
    Umbraco.Plain.Json
See UUI-GOTCHAS.md for UUI component issues (combobox, input, etc.).
That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.
请查看TROUBLESHOOTING.md了解常见问题，包括：
  • 创建数据类型时出现404错误
  • 使用
    Umbraco.Plain.Json
    时值无法持久化
请查看UUI-GOTCHAS.md了解UUI组件相关问题（如下拉框、输入框等）。
以上就是全部内容！请务必获取最新文档，保持示例简洁，生成可运行的完整代码。