umbraco-property-editor-ui（umbraco 属性编辑器 ui）

Umbraco Property Editor UI

What is it?

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.

Documentation

Always fetch the latest docs before implementing:

• Main docs: https://docs.umbraco.com/umbraco-cms/customizing/property-editors
• Tutorial: https://docs.umbraco.com/umbraco-cms/tutorials/creating-a-property-editor
• Configuration: https://docs.umbraco.com/umbraco-cms/tutorials/creating-a-property-editor/adding-configuration-to-a-property-editor
• Foundation: https://docs.umbraco.com/umbraco-cms/customizing/foundation
• Extension Registry: https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-registry

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.

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

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

Minimal Examples

Manifest (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.

{
  "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)

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

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

{
  "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)

The propertyEditorSchemaAlias in your manifest must reference a schema that exists on the server:

• 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:

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.