umbraco-tiptap-extension

Umbraco Tiptap 扩展

这是什么？

Tiptap 扩展为 Umbraco 的富文本编辑器（基于 Tiptap 构建）添加功能。扩展可以添加新的节点类型（例如自定义区块）、标记（例如自定义格式），或其他编辑器功能。扩展 API 提供了底层 Tiptap 扩展，并将其注册到编辑器中。

文档

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

• 扩展类型：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types
• 富文本编辑器：https://docs.umbraco.com/umbraco-cms/model-your-content/property-editors/built-in-umbraco-property-editors/rich-text-editor
• Tiptap 文档：https://tiptap.dev/docs/editor/extensions/overview
• Foundation：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation

相关技能

• Tiptap 工具栏扩展：用于添加工具栏按钮

  • 参考技能：umbraco-tiptap-toolbar-extension

• Tiptap 状态栏扩展：用于添加状态栏元素

  • 参考技能：umbraco-tiptap-statusbar-extension

工作流

1. 获取文档 - 使用 WebFetch 访问上述 URL
2. 提问 - 需要什么功能？节点、标记还是扩展？是否需要自定义样式？
3. 生成文件 - 根据最新文档创建 manifest 和 API 类
4. 说明 - 展示创建的内容以及测试方法

最小示例

Manifest (manifests.ts)

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

const manifest: ManifestTiptapExtension = {
  type: 'tiptapExtension',
  alias: 'My.TiptapExtension.Highlight',
  name: 'Highlight Extension',
  api: () => import('./highlight.tiptap-api.js'),
  meta: {
    icon: 'icon-marker',
    label: 'Highlight',
    group: 'formatting',
  },
};

export const manifests = [manifest];

扩展 API (highlight.tiptap-api.ts)

import { UmbTiptapExtensionApiBase } from '@umbraco-cms/backoffice/tiptap';
import type { UmbTiptapExtensionArgs } from '@umbraco-cms/backoffice/tiptap';
import Highlight from '@tiptap/extension-highlight';

export default class HighlightTiptapExtensionApi extends UmbTiptapExtensionApiBase {
  getTiptapExtensions(args?: UmbTiptapExtensionArgs) {
    return [
      Highlight.configure({
        multicolor: true,
      }),
    ];
  }
}

自定义节点扩展

import { UmbTiptapExtensionApiBase } from '@umbraco-cms/backoffice/tiptap';
import { Node } from '@tiptap/core';

export default class CalloutTiptapExtensionApi extends UmbTiptapExtensionApiBase {
  getTiptapExtensions() {
    const CalloutNode = Node.create({
      name: 'callout',
      group: 'block',
      content: 'block+',

      addAttributes() {
        return {
          type: {
            default: 'info',
          },
        };
      },

      parseHTML() {
        return [{ tag: 'div[data-callout]' }];
      },

      renderHTML({ HTMLAttributes }) {
        return ['div', { 'data-callout': '', ...HTMLAttributes }, 0];
      },
    });

    return [CalloutNode];
  }
}

自定义标记扩展

import { UmbTiptapExtensionApiBase } from '@umbraco-cms/backoffice/tiptap';
import { Mark } from '@tiptap/core';

export default class CustomMarkTiptapExtensionApi extends UmbTiptapExtensionApiBase {
  getTiptapExtensions() {
    const CustomMark = Mark.create({
      name: 'customHighlight',

      addAttributes() {
        return {
          color: {
            default: 'yellow',
          },
        };
      },

      parseHTML() {
        return [{ tag: 'mark' }];
      },

      renderHTML({ HTMLAttributes }) {
        return ['mark', { style: `background-color: ${HTMLAttributes.color}` }, 0];
      },
    });

    return [CustomMark];
  }
}

带自定义样式的扩展

import { UmbTiptapExtensionApiBase } from '@umbraco-cms/backoffice/tiptap';
import { css } from '@umbraco-cms/backoffice/external/lit';
import Highlight from '@tiptap/extension-highlight';

export default class StyledHighlightApi extends UmbTiptapExtensionApiBase {
  getTiptapExtensions() {
    return [Highlight];
  }

  // Custom styles for the editor
  getStyles() {
    return css`
      mark {
        background-color: yellow;
        padding: 0.1em 0.2em;
        border-radius: 2px;
      }
    `;
  }
}

使用属性编辑器中的配置

import { UmbTiptapExtensionApiBase } from '@umbraco-cms/backoffice/tiptap';
import type { UmbTiptapExtensionArgs } from '@umbraco-cms/backoffice/tiptap';
import Highlight from '@tiptap/extension-highlight';

export default class ConfigurableHighlightApi extends UmbTiptapExtensionApiBase {
  getTiptapExtensions(args?: UmbTiptapExtensionArgs) {
    // Access data type configuration
    const multicolor = args?.configuration?.getValueByAlias('multicolor') ?? false;

    return [
      Highlight.configure({
        multicolor,
      }),
    ];
  }
}

元属性

属性	描述
icon	配置 UI 中显示的图标
label	显示名称
group	用于组织扩展的分组
description	可选描述

常见扩展分组

• formatting - 文本格式（粗体、斜体等）
• structure - 结构元素（标题、列表等）
• media - 媒体元素（图片、嵌入内容等）
• misc - 其他功能

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