umbraco-ufm-component

Umbraco UFM コンポーネント

これは何ですか？

UFM（Umbraco Flavored Markdown）コンポーネントは、Umbraco のマークダウンレンダリングをカスタム構文で拡張します。これにより、レンダリング時に HTML に変換されるカスタムマーカーを作成できます。これは、マークダウンテキスト内にローカライズされた文字列、プロパティ値、カスタム UI 要素などの動的コンテンツを作成するのに便利です。UFM コンポーネントは、HTML に処理される特別な構文マーカー（ローカライズ用の # や値用の = など）を使用します。

ドキュメント

実装する前に、常に最新のドキュメントを取得してください:

• Foundation: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation
• Extension Registry: 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 コンポーネントを実演しています。本番環境のパターンとしてこれを研究してください。

関連する Foundation スキル

• Localization: ローカライズされた UFM コンポーネントを作成する場合

  • 参照スキル: umbraco-localization

• Context 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} - スタイル付きリンク

マークダウンでの使用

UFM コンポーネントは、ラベルの説明やマークダウンテキストで使用されます:

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

ベストプラクティス

• 覚えやすく短いマーカーを選択する
• 安全な HTML を返す（ユーザー入力をエスケープする）
• レンダリングを軽量に保つ
• 出力におけるアクセシビリティを考慮する
• カスタム要素をレンダリングする場合は、許可されたタグ名プレフィックス（umb-、 ufm-、または uui-）を使用してください。その他のプレフィックスは UFM のサニタイザーによって削除されます。

以上です！常に最新のドキュメントを取得し、例を最小限に保ち、完全に動作するコードを生成してください。