umbraco-property-editor-schema

Umbraco 属性编辑器架构

这是什么？

属性编辑器架构定义了属性编辑器的服务器端元数据和配置结构，本质上是数据存储和处理方式的“蓝图”。它是属性编辑器的一部分（另一部分是属性编辑器 UI）。架构决定了数据验证、存储格式，以及在呈现网站时如何提供属性数据。大多数自定义编辑器都可以使用内置架构；只有在需要特殊数据处理时才需要自定义架构。

文档

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

• 主要文档：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/backoffice-extensions/foundation
• 扩展注册表：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-registry

何时创建自定义架构

尽可能使用内置架构。在以下情况下创建自定义架构：

• 自定义服务器端验证
• 存储前进行特殊的数据转换
• 用于呈现的自定义属性值转换器
• 内置架构无法涵盖的复杂数据结构

工作流

1. 获取文档 - 对上述 URL 使用 WebFetch
2. 提问 - 内置架构是否可行？需要进行哪些数据验证？是否需要自定义值转换器？
3. 生成文件 - 如有需要，创建 C# 架构类，或使用内置架构别名
4. 说明 - 展示已创建的内容以及测试方法

内置架构别名

在属性编辑器 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

最简示例

使用内置架构（最常见）

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

自定义架构（C#）- 仅在需要时使用

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

自定义配置编辑器

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

自定义值转换器

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

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