umbraco-ufm-component

Umbraco UFM 组件

这是什么？

UFM（Umbraco Flavored Markdown）组件可通过自定义语法扩展 Umbraco 的 Markdown 渲染功能。你可以创建自定义标记，在渲染时将其转换为 HTML。这适用于在 Markdown 文本中创建动态内容，例如本地化字符串、属性值或自定义 UI 元素。UFM 组件使用特殊语法标记（例如用于本地化的 # 或用于值的 =），并将其处理为 HTML。

文档

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

• 基础：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
• UFM：https://docs.umbraco.com/umbraco-cms/model-your-content/property-editors/umbraco-flavored-markdown

参考示例

Umbraco 源代码中包含一个可运行的示例：

位置：/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/ufm-custom-component/

此示例展示了带标记语法的自定义 UFM 组件。请参考其中适用于生产环境的模式。

相关基础技能

• 本地化：创建本地化 UFM 组件时

  • 参考技能：umbraco-localization

• 上下文 API：访问 UFM 渲染所需的数据时

  • 参考技能：umbraco-context-api

工作流

1. 获取文档 - 对上述 URL 使用 WebFetch
2. 提出问题 - 使用什么标记？输出什么内容？是否需要动态数据？
3. 生成文件 - 根据最新文档创建清单和组件
4. 说明 - 展示创建的内容以及测试方法

最简示例

清单（manifests.ts）

import type { ManifestUfmComponent } from '@umbraco-cms/backoffice/ufm';

export const manifests: Array<ManifestUfmComponent> = [
  {
    type: 'ufmComponent',
    alias: 'My.UfmComponent.Custom',
    name: 'Custom UFM Component',
    api: () => import('./my-ufm-component.js'),
    meta: {
      alias: 'myCustom',  // Usage: {myCustom:value}
      marker: '%',        // Optional: Short marker like {%value}
    },
  },
];

组件实现（my-ufm-component.ts）

import { UmbUfmComponentBase } from '@umbraco-cms/backoffice/ufm';
import type { UfmToken } from '@umbraco-cms/backoffice/ufm';

export class MyUfmComponent extends UmbUfmComponentBase {
  render(token: UfmToken): string | undefined {
    // token.text contains the text after the marker
    // e.g., {%hello} would have token.text = 'hello'

    return `<span class="my-custom">${token.text}</span>`;
  }
}

export { MyUfmComponent as api };

带自定义元素的组件（my-ufm-component.ts）

重要：UFM 的后处理清理器只允许标签名称以 umb-、ufm- 或 uui- 开头的自定义元素。其他前缀（例如 my-hidden-label）会从渲染输出中移除。 请参阅 UFM 清理文档。

import { html, customElement, property } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { UmbUfmComponentBase } from '@umbraco-cms/backoffice/ufm';
import type { UfmToken } from '@umbraco-cms/backoffice/ufm';

// The UFM component that renders to custom element
export class MyUfmComponent extends UmbUfmComponentBase {
  render(token: UfmToken): string | undefined {
    // Output a custom element with the token text as attribute.
    // Tag name MUST start with umb-, ufm-, or uui- to survive sanitization.
    return `<ufm-my-element text="${token.text}"></ufm-my-element>`;
  }
}

// The custom element that gets rendered
@customElement('ufm-my-element')
export class MyUfmElement extends UmbLitElement {
  @property()
  text?: string;

  override render() {
    return html`<strong>${this.text}</strong>`;
  }
}

export { MyUfmComponent as api };

高亮组件示例

import { UmbUfmComponentBase } from '@umbraco-cms/backoffice/ufm';
import type { UfmToken } from '@umbraco-cms/backoffice/ufm';

// Usage: {!important text here} or {highlight:important text here}
export class HighlightUfmComponent extends UmbUfmComponentBase {
  render(token: UfmToken): string | undefined {
    return `<mark style="background: yellow; padding: 2px 4px;">${token.text}</mark>`;
  }
}

export { HighlightUfmComponent as api };

图标组件示例

import { UmbUfmComponentBase } from '@umbraco-cms/backoffice/ufm';
import type { UfmToken } from '@umbraco-cms/backoffice/ufm';

// Usage: {@icon-document} renders an Umbraco icon
export class IconUfmComponent extends UmbUfmComponentBase {
  render(token: UfmToken): string | undefined {
    return `<uui-icon name="${token.text}"></uui-icon>`;
  }
}

export { IconUfmComponent as api };

接口参考

interface ManifestUfmComponent extends ManifestApi<UmbUfmComponentApi> {
  type: 'ufmComponent';
  meta: MetaUfmComponent;
}

interface MetaUfmComponent {
  alias: string;    // Long form: {alias:text}
  marker?: string;  // Short form: {marker text}
}

interface UmbUfmComponentApi extends UmbApi {
  render(token: UfmToken): string | undefined;
}

interface UfmToken {
  text: string;  // The text content after the marker
}

内置 UFM 组件

• {#key} 或 {umbLocalize:key} - 本地化
• {=property} 或 {umbValue:property} - 属性值
• {umbContentName:id} - 内容名称
• {umbLink:url} - 样式化链接

在 Markdown 中使用

UFM 组件用于标签说明和 Markdown 文本：

{
  "type": "propertyEditorUi",
  "meta": {
    "label": "{#myLabel}",
    "description": "Status: {%active} - {!Important note}"
  }
}

最佳实践

• 选择易记且简短的标记
• 返回安全的 HTML（转义用户输入）
• 保持渲染轻量
• 在输出中考虑无障碍性
• 渲染自定义元素时，使用允许的标签名称前缀：umb-、 ufm- 或 uui-。其他前缀会被 UFM 清理器移除。

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