内置扩展

@axewo/fin-editor 提供 6 组内置扩展，覆盖了富文本编辑器的常用功能。

扩展一览

扩展	名称	功能
`CoreExtension`	核心基础	Document/Paragraph/Text 节点 + History（撤销/重做）
`TextStyleExtension`	文本样式	加粗、斜体、下划线、删除线、字体颜色、高亮、字号、字体
`ParagraphExtension`	段落排版	H1-H6 标题、对齐方式、有序/无序/任务列表、引用、分割线
`LinkExtension`	链接	超链接标记，选中文本添加链接，链接文字自动变色
`ImageExtension`	图片	图片节点，支持拖拽上传、粘贴上传、调整大小、Alt 编辑
`CodeBlockExtension`	代码块	代码高亮（lowlight），支持多种编程语言

CoreExtension

提供编辑器运行所需的基础 ProseMirror 节点（Document、Paragraph、Text）以及 History 撤销/重做扩展。

必须最先注册。没有这些节点，Tiptap 无法渲染内容或接受输入。

import { CoreExtension } from '@axewo/fin-editor'

editor.use(CoreExtension) // 必须第一个注册！

工具栏项

ID	类型	命令	快捷键	说明
`undo`	button	`undo`	`Ctrl+Z`	撤销
`redo`	button	`redo`	`Ctrl+Shift+Z`	重做

撤销/重做按钮在没有可撤销/重做操作时自动禁用。

TextStyleExtension

提供完整的文本样式控制能力。

import { TextStyleExtension } from '@axewo/fin-editor'

editor.use(TextStyleExtension)

工具栏项

ID	类型	命令	快捷键
`bold`	button	`toggleBold`	`Ctrl+B`
`italic`	button	`toggleItalic`	`Ctrl+I`
`underline`	button	`toggleUnderline`	`Ctrl+U`
`strike`	button	`toggleStrike`	`Ctrl+Shift+X`
`text-color`	color-picker	`setColor`	—
`highlight`	color-picker	`toggleHighlight`	—

自定义字体/字号

该扩展还注册了两个自定义 ProseMirror Extension：

FontFamily — 通过 setMark('textStyle', { fontFamily }) 设置字体
FontSize — 通过 setMark('textStyle', { fontSize }) 设置字号

// 设置字体
editor.executeCommand('setFontFamily', 'Arial')
editor.executeCommand('unsetFontFamily')

// 设置字号
editor.executeCommand('setFontSize', '18px')
editor.executeCommand('unsetFontSize')

底层的 Tiptap Extensions

Bold → Italic → Underline → Strike → TextStyle → Color → Highlight
→ FontFamily (自定义) → FontSize (自定义)

ParagraphExtension

提供段落排版、列表、引用等结构化编辑能力。

import { ParagraphExtension } from '@axewo/fin-editor'

editor.use(ParagraphExtension)

ID	命令	参数
`heading-1`	`setHeading`	`{ level: 1 }`
`heading-2`	`setHeading`	`{ level: 2 }`
`heading-3`	`setHeading`	`{ level: 3 }`
`paragraph`	`setParagraph`	—

对齐按钮

ID	命令	快捷键
`text-align-left`	`setTextAlign` (`'left'`)	—
`text-align-center`	`setTextAlign` (`'center'`)	—
`text-align-right`	`setTextAlign` (`'right'`)	—

列表按钮

ID	命令	快捷键
`bullet-list`	`toggleBulletList`	`Ctrl+Shift+8`
`ordered-list`	`toggleOrderedList`	`Ctrl+Shift+7`
`task-list`	`toggleTaskList`	—

引用与分割线

ID	命令
`blockquote`	`toggleBlockquote`
`horizontal-rule`	`setHorizontalRule`

底层的 Tiptap Extensions

Heading (levels 1-6) → TextAlign → BulletList → OrderedList → ListItem
→ TaskList → TaskItem (nested) → Blockquote → HorizontalRule

LinkExtension

超链接标记扩展，选中文本后可添加跳转链接，链接文字自动变色为主题色并带下划线。

import { LinkExtension } from '@axewo/fin-editor'

editor.use(LinkExtension)

工具栏项

ID	类型	命令	快捷键	说明
`link`	button	`showLinkDialog`	`Ctrl+K`	插入/编辑链接

命令

命令	参数	说明
`setLink`	`{ href, target?, rel? }`	为选中文本设置链接
`unsetLink`	—	移除链接
`showLinkDialog`	—	触发自定义事件，弹出链接编辑对话框

链接样式

链接文字自动应用 .fin-editor__link CSS 类，样式由主题控制：

浅色主题：#409eff（蓝色）+ 下划线
深色主题：#409eff（蓝色）+ 下划线
Hover 状态：颜色变浅

ImageExtension

支持图片拖拽和粘贴的自定义 Image 节点。

import { createImageExtension } from '@axewo/fin-editor'

// createImageExtension 是工厂函数
editor.use(createImageExtension())

功能特性

拖拽上传：从文件管理器拖拽图片到编辑器
粘贴上传：Ctrl+V 粘贴剪贴板中的图片
调整大小：点击图片选中后，拖拽右下角圆点调整宽度（Vue NodeView）
编辑属性：选中图片后点击编辑按钮，可修改 Alt 文本、宽度和高度
插件驱动：通过 ProseMirror Plugin 拦截 drop 和 paste 事件

工具栏

ID	类型	命令	说明
`image`	button	`showImageDialog`	触发自定义事件，用于打开上传对话框

命令

命令	参数	说明
`setImage`	`{ src, alt?, width?, height? }`	插入新图片
`updateImage`	`{ src?, alt?, width?, height? }`	更新选中图片的属性
`showImageDialog`	—	触发自定义事件，弹出图片对话框（插入/编辑模式）

监听图片对话框事件：

window.addEventListener('fin-editor:show-image-dialog', (e) => {
  const { isEditing, src, alt, width, height } = e.detail
  if (isEditing) {
    // 编辑模式：更新已有图片属性
    editor.executeCommand('updateImage', { alt: '新描述', width: '50%' })
  } else {
    // 插入模式：插入新图片
    editor.executeCommand('setImage', { src: 'url', alt: '描述' })
  }
})

注意：createImageExtension() 使用工厂函数而非直接导出对象，因为扩展可能包含运行时状态的闭包。每次调用 createImageExtension() 都会创建一个新的扩展实例。
Vue NodeView：在 Vue 环境中，使用 createVueImageExtension() 替代 createImageExtension() 可获得图片调整大小和编辑属性功能。FinEditor 组件已内置使用。

CodeBlockExtension

基于 @tiptap/extension-code-block-lowlight 的低代码高亮扩展。

import { CodeBlockExtension } from '@axewo/fin-editor'

editor.use(CodeBlockExtension)

支持的语言

已预注册以下常用语言（可通过 lowlight.registerLanguage() 按需添加更多）：

javascript typescript css html xml json python rust bash sql yaml markdown java php go ruby cpp c shell dockerfile

工具栏

ID	类型	命令	说明
`code-block`	button	`toggleCodeBlock`	切换代码块

注册所有扩展

@axewo/fin-editor 提供了便捷函数一次性注册所有内置扩展：

import { registerAllExtensions } from '@axewo/fin-editor'
import type { EditorInstance } from '@axewo/fin-editor'

registerAllExtensions(editor)
// 等价于：
// editor.use(CoreExtension)          // Document/Paragraph/Text + History
//        .use(TextStyleExtension)    // Bold/Italic/Underline/Strike/Color/Highlight
//        .use(ParagraphExtension)    // Heading/Align/Lists/Blockquote/HR
//        .use(LinkExtension)         // Link mark
//        .use(createImageExtension()) // Image node
//        .use(CodeBlockExtension)    // Code block with highlighting
//        .use(CodeBlockExtension)

自定义扩展

你也可以创建自己的扩展。实现 EditorExtension 接口即可：

import type { EditorExtension, ToolbarItem } from '@axewo/fin-editor'
import { Mention } from '@tiptap/extension-mention'

const myMentionExtension: EditorExtension = {
  name: 'mention',

  tiptapExtensions: [
    Mention.configure({
      HTMLAttributes: { class: 'mention' },
    }),
  ],

  toolbarItems: [
    {
      type: 'button',
      id: 'mention',
      label: '提及',
      icon: 'at-sign',
      tooltip: '@提及用户',
      command: 'openMention',
      order: 50,
    },
  ],

  commands: {
    openMention: (editor) => {
      // 自定义命令逻辑
      console.log('打开提及面板')
      return true
    },
  },

  onMount: (editor, context) => {
    console.log('提及扩展已挂载')
  },

  onDestroy: (editor) => {
    console.log('提及扩展已销毁')
  },
}

// 注册到编辑器
editor.use(myMentionExtension)

扩展通过 ExtensionRegistry 注册后，其所有组成部分（Tiptap 扩展、工具栏项、命令、快捷键、生命周期钩子）都会被编辑器自动管理。

内置扩展 ​

扩展一览 ​

CoreExtension ​

工具栏项 ​

TextStyleExtension ​

工具栏项 ​

自定义字体/字号 ​

底层的 Tiptap Extensions ​

ParagraphExtension ​

标题下拉 (Heading Dropdown) ​

对齐按钮 ​

列表按钮 ​

引用与分割线 ​

底层的 Tiptap Extensions ​

LinkExtension ​

工具栏项 ​

命令 ​

链接样式 ​

ImageExtension ​

功能特性 ​

工具栏 ​

命令 ​

CodeBlockExtension ​

支持的语言 ​

工具栏 ​

注册所有扩展 ​

自定义扩展 ​

内置扩展

扩展一览

CoreExtension

工具栏项

TextStyleExtension

工具栏项

自定义字体/字号

底层的 Tiptap Extensions

ParagraphExtension

标题下拉 (Heading Dropdown)

对齐按钮

列表按钮

引用与分割线

底层的 Tiptap Extensions

LinkExtension

工具栏项

命令

链接样式

ImageExtension

功能特性

工具栏

命令

CodeBlockExtension

支持的语言

工具栏

注册所有扩展

自定义扩展