umbraco-property-editor-schema

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Umbraco Property Editor Schema

What is it?

什么是属性编辑器模式？

A Property Editor Schema defines the server-side metadata and configuration structure for a property editor - essentially the "blueprint" for how data is stored and processed. It's one half of a property editor (paired with a Property Editor UI). The schema determines data validation, storage format, and how property data is made available when rendering the website. Most custom editors can use built-in schemas; custom schemas are needed for specialized data handling.

Property Editor Schema定义了属性编辑器的服务器端元数据和配置结构——本质上是数据存储和处理方式的“蓝图”。它是属性编辑器的组成部分之一（与Property Editor UI配对）。该模式决定了数据验证规则、存储格式，以及在渲染网站时如何提供属性数据。大多数自定义编辑器可以使用内置模式；只有在需要特殊数据处理时才需要自定义模式。

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
Foundation: https://docs.umbraco.com/umbraco-cms/customizing/foundation
Extension Registry: https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-registry

在开始实现前，请务必获取最新文档：

主文档：https://docs.umbraco.com/umbraco-cms/customizing/property-editors
教程：https://docs.umbraco.com/umbraco-cms/tutorials/creating-a-property-editor
基础指南：https://docs.umbraco.com/umbraco-cms/customizing/foundation
扩展注册表：https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-registry

When to Create a Custom Schema

何时创建自定义模式

Use a built-in schema when possible. Create a custom schema when you need:

Custom server-side validation
Special data transformation before storage
Custom property value converters for rendering
Complex data structures not covered by built-in schemas

尽可能使用内置模式。在以下场景下需要创建自定义模式：

自定义服务器端验证
存储前的特殊数据转换
用于渲染的自定义属性值转换器
内置模式未覆盖的复杂数据结构

Workflow

工作流程

Fetch docs - Use WebFetch on the URLs above
Ask questions - Can a built-in schema work? What data validation needed? Custom value converter?
Generate files - Create C# schema class if needed, or use built-in schema alias
Explain - Show what was created and how to test

获取文档 - 使用WebFetch访问上述URL获取文档
确认需求 - 内置模式是否适用？需要哪些数据验证？是否需要自定义值转换器？
生成文件 - 如有需要，创建C#模式类，或使用内置模式别名
说明解释 - 展示创建的内容以及测试方法

Built-in Schema Aliases

内置模式别名

Use these in your Property Editor UI manifest's

propertyEditorSchemaAlias

Alias	Use Case
`Umbraco.Plain.String`	Simple string, no validation
`Umbraco.Plain.Integer`	Simple integer
`Umbraco.Plain.Decimal`	Decimal numbers
`Umbraco.Plain.DateTime`	Date/time values
`Umbraco.Plain.Json`	JSON objects/arrays
`Umbraco.TextBox`	String with maxlength validation
`Umbraco.TextArea`	Multi-line text
`Umbraco.TrueFalse`	Boolean values
`Umbraco.ColorPicker`	Color values
`Umbraco.ContentPicker`	Content node references
`Umbraco.MediaPicker`	Media references
`Umbraco.MultiUrlPicker`	Multiple URL links
`Umbraco.Tags`	Tag collections
`Umbraco.RichText`	Rich text HTML

在Property Editor UI清单的

propertyEditorSchemaAlias

中使用以下别名：

别名	使用场景
`Umbraco.Plain.String`	简单字符串，无验证
`Umbraco.Plain.Integer`	简单整数
`Umbraco.Plain.Decimal`	十进制数字
`Umbraco.Plain.DateTime`	日期/时间值
`Umbraco.Plain.Json`	JSON对象/数组
`Umbraco.TextBox`	带最大长度验证的字符串
`Umbraco.TextArea`	多行文本
`Umbraco.TrueFalse`	布尔值
`Umbraco.ColorPicker`	颜色值
`Umbraco.ContentPicker`	内容节点引用
`Umbraco.MediaPicker`	媒体资源引用
`Umbraco.MultiUrlPicker`	多个URL链接
`Umbraco.Tags`	标签集合
`Umbraco.RichText`	富文本HTML

Minimal Examples

最简示例

Using Built-in Schema (Most Common)

使用内置模式（最常用）

json

{
  "type": "propertyEditorUi",
  "alias": "My.PropertyEditorUi.Custom",
  "name": "My Custom Editor",
  "element": "/App_Plugins/MyEditor/editor.js",
  "meta": {
    "propertyEditorSchemaAlias": "Umbraco.Plain.String"
  }
}

json

{
  "type": "propertyEditorUi",
  "alias": "My.PropertyEditorUi.Custom",
  "name": "My Custom Editor",
  "element": "/App_Plugins/MyEditor/editor.js",
  "meta": {
    "propertyEditorSchemaAlias": "Umbraco.Plain.String"
  }
}

Custom Schema (C#) - Only When Needed

自定义模式（C#）- 仅在必要时使用

csharp

using Umbraco.Cms.Core.IO;
using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Cms.Core.Services;

namespace MyPackage.PropertyEditors;

[DataEditor(
    alias: "My.PropertyEditor.Custom",
    name: "My Custom Editor",
    view: "~/App_Plugins/MyEditor/editor.html")]
public class MyPropertyEditor : DataEditor
{
    private readonly IIOHelper _ioHelper;
    private readonly IEditorConfigurationParser _editorConfigurationParser;

    public MyPropertyEditor(
        IDataValueEditorFactory dataValueEditorFactory,
        IIOHelper ioHelper,
        IEditorConfigurationParser editorConfigurationParser)
        : base(dataValueEditorFactory)
    {
        _ioHelper = ioHelper;
        _editorConfigurationParser = editorConfigurationParser;
        SupportsReadOnly = true;
    }

    protected override IConfigurationEditor CreateConfigurationEditor() =>
        new MyConfigurationEditor(_ioHelper, _editorConfigurationParser);
}

csharp

using Umbraco.Cms.Core.IO;
using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Cms.Core.Services;

namespace MyPackage.PropertyEditors;

[DataEditor(
    alias: "My.PropertyEditor.Custom",
    name: "My Custom Editor",
    view: "~/App_Plugins/MyEditor/editor.html")]
public class MyPropertyEditor : DataEditor
{
    private readonly IIOHelper _ioHelper;
    private readonly IEditorConfigurationParser _editorConfigurationParser;

    public MyPropertyEditor(
        IDataValueEditorFactory dataValueEditorFactory,
        IIOHelper ioHelper,
        IEditorConfigurationParser editorConfigurationParser)
        : base(dataValueEditorFactory)
    {
        _ioHelper = ioHelper;
        _editorConfigurationParser = editorConfigurationParser;
        SupportsReadOnly = true;
    }

    protected override IConfigurationEditor CreateConfigurationEditor() =>
        new MyConfigurationEditor(_ioHelper, _editorConfigurationParser);
}

Custom Configuration Editor

自定义配置编辑器

csharp

using Umbraco.Cms.Core.IO;
using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Cms.Core.Services;

namespace MyPackage.PropertyEditors;

public class MyConfigurationEditor : ConfigurationEditor<MyConfiguration>
{
    public MyConfigurationEditor(
        IIOHelper ioHelper,
        IEditorConfigurationParser editorConfigurationParser)
        : base(ioHelper, editorConfigurationParser)
    {
    }
}

public class MyConfiguration
{
    [ConfigurationField("maxItems", "Maximum Items", "number")]
    public int MaxItems { get; set; } = 10;

    [ConfigurationField("allowNull", "Allow Empty", "boolean")]
    public bool AllowNull { get; set; } = true;
}

csharp

using Umbraco.Cms.Core.IO;
using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Cms.Core.Services;

namespace MyPackage.PropertyEditors;

public class MyConfigurationEditor : ConfigurationEditor<MyConfiguration>
{
    public MyConfigurationEditor(
        IIOHelper ioHelper,
        IEditorConfigurationParser editorConfigurationParser)
        : base(ioHelper, editorConfigurationParser)
    {
    }
}

public class MyConfiguration
{
    [ConfigurationField("maxItems", "Maximum Items", "number")]
    public int MaxItems { get; set; } = 10;

    [ConfigurationField("allowNull", "Allow Empty", "boolean")]
    public bool AllowNull { get; set; } = true;
}

Custom Value Converter

自定义值转换器

csharp

using Umbraco.Cms.Core.Models.PublishedContent;
using Umbraco.Cms.Core.PropertyEditors;

namespace MyPackage.PropertyEditors;

public class MyValueConverter : PropertyValueConverterBase
{
    public override bool IsConverter(IPublishedPropertyType propertyType)
        => propertyType.EditorAlias == "My.PropertyEditor.Custom";

    public override Type GetPropertyValueType(IPublishedPropertyType propertyType)
        => typeof(MyModel);

    public override object? ConvertSourceToIntermediate(
        IPublishedElement owner,
        IPublishedPropertyType propertyType,
        object? source,
        bool preview)
    {
        if (source is string json && !string.IsNullOrEmpty(json))
        {
            return JsonSerializer.Deserialize<MyModel>(json);
        }
        return null;
    }
}

That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.

csharp

using Umbraco.Cms.Core.Models.PublishedContent;
using Umbraco.Cms.Core.PropertyEditors;

namespace MyPackage.PropertyEditors;

public class MyValueConverter : PropertyValueConverterBase
{
    public override bool IsConverter(IPublishedPropertyType propertyType)
        => propertyType.EditorAlias == "My.PropertyEditor.Custom";

    public override Type GetPropertyValueType(IPublishedPropertyType propertyType)
        => typeof(MyModel);

    public override object? ConvertSourceToIntermediate(
        IPublishedElement owner,
        IPublishedPropertyType propertyType,
        object? source,
        bool preview)
    {
        if (source is string json && !string.IsNullOrEmpty(json))
        {
            return JsonSerializer.Deserialize<MyModel>(json);
        }
        return null;
    }
}

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