umbraco-tiptap-extension

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Umbraco Tiptap Extension

Umbraco Tiptap 扩展

What is it?

什么是Tiptap扩展？

A Tiptap Extension adds functionality to Umbraco's Rich Text Editor (which is built on Tiptap). Extensions can add new node types (like custom blocks), marks (like custom formatting), or other editor capabilities. The extension API provides the underlying Tiptap extensions that get registered with the editor.

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

Documentation

文档

Always fetch the latest docs before implementing:

Extension Types: https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-types
Rich Text Editor: https://docs.umbraco.com/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor
Tiptap Docs: https://tiptap.dev/docs/editor/extensions/overview
Foundation: https://docs.umbraco.com/umbraco-cms/customizing/foundation

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

扩展类型：https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-types
富文本编辑器：https://docs.umbraco.com/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor
Tiptap文档：https://tiptap.dev/docs/editor/extensions/overview
基础指南：https://docs.umbraco.com/umbraco-cms/customizing/foundation

Related Skills

Workflow

工作流程

Fetch docs - Use WebFetch on the URLs above
Ask questions - What functionality? Node, Mark, or Extension? Custom styles needed?
Generate files - Create manifest + API class based on latest docs
Explain - Show what was created and how to test

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

Minimal Examples

最简示例

Manifest (manifests.ts)

清单 (manifests.ts)

typescript

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

typescript

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

Extension API (highlight.tiptap-api.ts)

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

typescript

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

typescript

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

Custom Node Extension

自定义节点扩展

typescript

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

typescript

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

Custom Mark Extension

自定义标记扩展

typescript

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

typescript

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

Extension with Custom Styles

带自定义样式的扩展

typescript

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

typescript

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

  // 编辑器的自定义样式
  getStyles() {
    return css`
      mark {
        background-color: yellow;
        padding: 0.1em 0.2em;
        border-radius: 2px;
      }
    `;
  }
}

Using Configuration from Property Editor

使用属性编辑器的配置

typescript

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

typescript

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) {
    // 访问数据类型配置
    const multicolor = args?.configuration?.getValueByAlias('multicolor') ?? false;

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

Meta Properties

元属性

Property	Description
`icon`	Icon shown in configuration UI
`label`	Display name
`group`	Group for organizing extensions
`description`	Optional description

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

Common Extension Groups

常见扩展分组

```
formatting
```
- Text formatting (bold, italic, etc.)
```
structure
```
- Structural elements (headings, lists, etc.)
```
media
```
- Media elements (images, embeds, etc.)
```
misc
```
- Other functionality

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

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

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

umbraco-tiptap-extension

Original

Translation

Umbraco Tiptap Extension

Umbraco Tiptap 扩展

What is it?

什么是Tiptap扩展？

Documentation

文档

Related Skills

相关技能

Workflow

工作流程

Minimal Examples

最简示例

Manifest (manifests.ts)

清单 (manifests.ts)

Extension API (highlight.tiptap-api.ts)

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

Custom Node Extension

自定义节点扩展

Custom Mark Extension

自定义标记扩展

Extension with Custom Styles

带自定义样式的扩展

Using Configuration from Property Editor

使用属性编辑器的配置

Meta Properties

元属性

Common Extension Groups

常见扩展分组