umbraco-property-value-preset

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Umbraco Property Value Preset

Umbraco 属性值预设

What is it?

什么是属性值预设？

Property Value Presets provide default values when users create new content. They use an API to supply preset values for specific property editors, enabling streamlined content creation with sensible defaults. Multiple presets can work together using the

weight

property to progressively modify values.

属性值预设会在用户创建新内容时提供默认值。它们通过API为特定属性编辑器提供预设值，让内容创建流程更高效，同时使用合理的默认值。借助

weight

属性，多个预设可以协同工作，逐步修改值。

Documentation

文档参考

Always fetch the latest docs before implementing:

Main docs: https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-types/property-value-preset
Property Editors: https://docs.umbraco.com/umbraco-cms/customizing/property-editors
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/extending-overview/extension-types/property-value-preset
属性编辑器：https://docs.umbraco.com/umbraco-cms/customizing/property-editors
基础框架：https://docs.umbraco.com/umbraco-cms/customizing/foundation
扩展注册中心：https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-registry

Workflow

实施流程

Fetch docs - Use WebFetch on the URLs above
Ask questions - Which property editor? What default value? Static or dynamic?
Generate files - Create manifest + preset API based on latest docs
Explain - Show what was created and how to test

获取文档 - 使用WebFetch获取上述链接的文档
确认需求 - 确定目标属性编辑器？默认值是什么？静态还是动态？
生成文件 - 根据最新文档创建清单（manifest）和预设API
说明解释 - 展示创建的内容以及测试方法

Minimal Examples

最简示例

Manifest (manifests.ts)

清单文件 (manifests.ts)

typescript

import type { ManifestPropertyValuePreset } from '@umbraco-cms/backoffice/extension-registry';

const manifest: ManifestPropertyValuePreset = {
  type: 'propertyValuePreset',
  alias: 'My.PropertyValuePreset.DefaultText',
  name: 'Default Text Preset',
  api: () => import('./default-text-preset.js'),
  forPropertyEditorUiAlias: 'Umb.PropertyEditorUi.TextBox',
};

export const manifests = [manifest];

typescript

import type { ManifestPropertyValuePreset } from '@umbraco-cms/backoffice/extension-registry';

const manifest: ManifestPropertyValuePreset = {
  type: 'propertyValuePreset',
  alias: 'My.PropertyValuePreset.DefaultText',
  name: 'Default Text Preset',
  api: () => import('./default-text-preset.js'),
  forPropertyEditorUiAlias: 'Umb.PropertyEditorUi.TextBox',
};

export const manifests = [manifest];

Preset Implementation (default-text-preset.ts)

预设实现 (default-text-preset.ts)

typescript

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

export class DefaultTextPreset implements UmbPropertyValuePresetApi {
  async processValue(value: unknown, config: unknown): Promise<unknown> {
    // Return default if no value exists
    return value ? value : 'Default text value';
  }

  destroy() {
    // Cleanup if needed
  }
}

export default DefaultTextPreset;

typescript

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

export class DefaultTextPreset implements UmbPropertyValuePresetApi {
  async processValue(value: unknown, config: unknown): Promise<unknown> {
    // 如果没有值则返回默认值
    return value ? value : 'Default text value';
  }

  destroy() {
    // 如有需要进行清理
  }
}

export default DefaultTextPreset;

Dynamic Default Based on Config

基于配置的动态默认值

typescript

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

export class DynamicPreset implements UmbPropertyValuePresetApi {
  async processValue(value: unknown, config: UmbPropertyEditorConfigCollection): Promise<unknown> {
    if (value) return value;

    // Use configuration to determine default
    const defaultFromConfig = config?.getValueByAlias('defaultValue');
    return defaultFromConfig || 'Fallback default';
  }

  destroy() {}
}

export default DynamicPreset;

typescript

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

export class DynamicPreset implements UmbPropertyValuePresetApi {
  async processValue(value: unknown, config: UmbPropertyEditorConfigCollection): Promise<unknown> {
    if (value) return value;

    // 使用配置确定默认值
    const defaultFromConfig = config?.getValueByAlias('defaultValue');
    return defaultFromConfig || 'Fallback default';
  }

  destroy() {}
}

export default DynamicPreset;

Async Default (e.g., from API)

异步默认值（例如从API获取）

typescript

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

export class ApiPreset implements UmbPropertyValuePresetApi {
  async processValue(value: unknown, config: unknown): Promise<unknown> {
    if (value) return value;

    // Fetch default from server
    const response = await fetch('/api/defaults/text');
    const data = await response.json();
    return data.defaultValue;
  }

  destroy() {}
}

export default ApiPreset;

typescript

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

export class ApiPreset implements UmbPropertyValuePresetApi {
  async processValue(value: unknown, config: unknown): Promise<unknown> {
    if (value) return value;

    // 从服务器获取默认值
    const response = await fetch('/api/defaults/text');
    const data = await response.json();
    return data.defaultValue;
  }

  destroy() {}
}

export default ApiPreset;

Target by Schema Alias

按Schema别名定位

typescript

const manifest: ManifestPropertyValuePreset = {
  type: 'propertyValuePreset',
  alias: 'My.PropertyValuePreset.JsonDefault',
  name: 'JSON Default Preset',
  api: () => import('./json-preset.js'),
  forPropertyEditorSchemaAlias: 'Umbraco.Plain.Json', // Target schema instead of UI
};

typescript

const manifest: ManifestPropertyValuePreset = {
  type: 'propertyValuePreset',
  alias: 'My.PropertyValuePreset.JsonDefault',
  name: 'JSON Default Preset',
  api: () => import('./json-preset.js'),
  forPropertyEditorSchemaAlias: 'Umbraco.Plain.Json', // 定位Schema而非UI
};

Multiple Presets with Weight

带权重的多预设

typescript

// First preset (runs first due to lower weight)
const basePreset: ManifestPropertyValuePreset = {
  type: 'propertyValuePreset',
  alias: 'My.PropertyValuePreset.Base',
  name: 'Base Preset',
  weight: 100,
  api: () => import('./base-preset.js'),
  forPropertyEditorUiAlias: 'Umb.PropertyEditorUi.TextBox',
};

// Second preset (runs after, can modify base value)
const enhancedPreset: ManifestPropertyValuePreset = {
  type: 'propertyValuePreset',
  alias: 'My.PropertyValuePreset.Enhanced',
  name: 'Enhanced Preset',
  weight: 200,
  api: () => import('./enhanced-preset.js'),
  forPropertyEditorUiAlias: 'Umb.PropertyEditorUi.TextBox',
};

typescript

// 第一个预设（权重较低，先执行）
const basePreset: ManifestPropertyValuePreset = {
  type: 'propertyValuePreset',
  alias: 'My.PropertyValuePreset.Base',
  name: 'Base Preset',
  weight: 100,
  api: () => import('./base-preset.js'),
  forPropertyEditorUiAlias: 'Umb.PropertyEditorUi.TextBox',
};

// 第二个预设（后执行，可修改基础值）
const enhancedPreset: ManifestPropertyValuePreset = {
  type: 'propertyValuePreset',
  alias: 'My.PropertyValuePreset.Enhanced',
  name: 'Enhanced Preset',
  weight: 200,
  api: () => import('./enhanced-preset.js'),
  forPropertyEditorUiAlias: 'Umb.PropertyEditorUi.TextBox',
};

Date Default Example

日期默认值示例

typescript

export class TodayDatePreset implements UmbPropertyValuePresetApi {
  async processValue(value: unknown, config: unknown): Promise<unknown> {
    if (value) return value;
    return new Date().toISOString().split('T')[0]; // Today's date
  }

  destroy() {}
}

export default TodayDatePreset;

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

typescript

export class TodayDatePreset implements UmbPropertyValuePresetApi {
  async processValue(value: unknown, config: unknown): Promise<unknown> {
    if (value) return value;
    return new Date().toISOString().split('T')[0]; // 今日日期
  }

  destroy() {}
}

export default TodayDatePreset;

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