Core API

@axewo/fin-editor 是框架无关的编辑器引擎，提供 EditorInstance、ExtensionRegistry 和三个可替换的服务（上传、国际化、主题）。

EditorInstance

核心类，封装 Tiptap Editor 的完整生命周期。

创建编辑器

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

const editor = new EditorInstance({
  content: '<p>Hello World</p>',
  mode: 'edit',
  theme: 'light',
  locale: 'zh-CN',
  placeholder: '请输入内容...',
  spellcheck: false,
  autoSaveInterval: 30000, // 每 30 秒自动保存
})

// 绑定到 DOM 元素
editor.createEditor(document.getElementById('editor')!)

EditorConfig

属性	类型	默认值	说明
content	string | object	''	初始内容（HTML 或 JSON）
mode	'edit' | 'view' | 'comment'	'edit'	编辑模式
theme	'light' | 'dark' | 'auto'	'light'	主题
locale	'zh-CN' | 'en-US'	'zh-CN'	语言
placeholder	string	''	占位文本
spellcheck	boolean	false	拼写检查
autoSaveInterval	number	0	自动保存间隔（ms），0 表示不自动保存
collaboration	CollaborationConfig	—	协同编辑配置
upload	UploadConfig	—	上传配置
toolbar	ToolbarConfig	—	工具栏配置
shortcuts	ShortcutBinding[]	—	自定义快捷键

内容操作

// 获取内容
editor.getHTML()       // → '<p>Hello <strong>World</strong></p>'
editor.getContent()    // 同 getHTML 的别名
editor.getText()       // → 'Hello World'
editor.getJSON()       // → { type: 'doc', content: [...] }

// 设置内容
editor.setContent('<p>新内容</p>')           // HTML
editor.setContent({ type: 'doc', ... })     // JSON（ProseMirror Document）
editor.setContent('<p>...</p>', true)       // 第二个参数为 true 时触发 update 事件

命令系统

// 执行命令
editor.executeCommand('toggleBold')
editor.executeCommand('setHeading', { level: 2 })
editor.executeCommand('setTextAlign', 'center')

// 检查命令状态（用于高亮工具栏按钮）
editor.isCommandActive('bold')    // → true | false
editor.isCommandActive('heading') // → true | false

事件系统

// 监听事件，返回取消监听的函数
const unsubscribe = editor.on('change', (html, tiptapEditor) => {
  console.log('内容变化:', html)
})

// 可用事件
editor.on('selection-change', (tiptapEditor) => { ... })
editor.on('focus', (tiptapEditor) => { ... })
editor.on('blur', (tiptapEditor) => { ... })
editor.on('save', (html, tiptapEditor) => { ... })
editor.on('upload-start', (file) => { ... })
editor.on('upload-success', (result, file) => { ... })
editor.on('upload-error', (error, file) => { ... })
editor.on('mode-change', (mode) => { ... })
editor.on('theme-change', (theme) => { ... })

// 取消监听
unsubscribe()

模式 / 主题 / 语言

editor.setMode('view')    // 切换为只读模式
editor.setTheme('dark')   // 切换为暗色主题
editor.setLocale('en-US') // 切换为英文

工具栏

// 获取所有已注册扩展的工具栏项（已按 order 排序）
const items = editor.getToolbarItems()
// → [{ type: 'button', id: 'bold', command: 'toggleBold', ... }, ...]

扩展管理

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

// 注册扩展（必须在 createEditor() 之前调用）
editor.use(TextStyleExtension)
// 支持链式调用
editor.use(ParagraphExtension).use(ImageExtension)

// createEditor 会自动将所有已注册扩展的 tiptapExtensions 注入编辑器实例
editor.createEditor(element)

手动保存

editor.save() // 触发 'save' 事件

销毁

editor.destroy()
// 清理 Tiptap 实例、自动保存定时器、事件监听器、扩展 onDestroy 钩子

ExtensionRegistry

EditorInstance 内部使用 ExtensionRegistry 管理所有已注册的扩展。

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

const registry = new ExtensionRegistry()

// 注册
registry.register(myExtension)

// 获取所有 Tiptap extensions（用于创建编辑器）
const extensions = registry.getTiptapExtensions()

// 获取工具栏项（已按 order 排序，order 相同时按注册顺序）
const toolbarItems = registry.getToolbarItems()

// 获取所有快捷键
const shortcuts = registry.getShortcuts()

// 查询单个扩展
registry.get('text-style')     // → EditorExtension | undefined
registry.has('text-style')     // → boolean

// 列出所有已注册扩展名称
registry.list()                // → ['text-style', 'paragraph', ...]

// 移除扩展
registry.unregister('text-style')

一般不需要直接操作 ExtensionRegistry，通过 EditorInstance.use() 注册即可。

服务层

UploadService

提供文件上传能力，支持自定义上传逻辑。

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

const upload = new HttpUploadService({
  endpoint: '/api/upload',
  method: 'POST',
  headers: { Authorization: 'Bearer xxx' },
  maxSize: 10 * 1024 * 1024,  // 10MB
  accept: ['image/png', 'image/jpeg', 'image/webp'],
})

// 上传单个文件
const result = await upload.upload(file)
// → { url: 'https://...', name: 'photo.png', size: 204800, mimeType: 'image/png' }

// 批量上传
const results = await upload.uploadAll(files)

// 自定义上传逻辑
const customService = new HttpUploadService({
  endpoint: '',
  customUpload: async (file) => {
    // 自定义上传逻辑（如上传到 OSS）
    return { url: 'https://oss.example.com/xxx.png' }
  },
})

也可以通过 UploadConfig 中的 customUpload 字段直接覆盖上传逻辑。

I18nService

管理编辑器 UI 文本的国际化。

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

const i18n = new I18nService()

i18n.setLocale('zh-CN')
i18n.t('bold')   // → '加粗'
i18n.t('italic') // → '斜体'

i18n.setLocale('en-US')
i18n.t('bold')   // → 'Bold'

// 获取所有翻译
i18n.getAll()    // → { bold: '加粗', italic: '斜体', ... }

ThemeService

管理编辑器主题。

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

const theme = new ThemeService()

theme.set('light')  // 浅色
theme.set('dark')   // 深色
theme.set('auto')   // 跟随系统（prefers-color-scheme）

theme.get()         // → 'light' | 'dark'（auto 会解析为实际值）

类型导出

import type {
  EditorMode,          // 'edit' | 'view' | 'comment'
  EditorTheme,         // 'light' | 'dark' | 'auto'
  EditorLocale,        // 'zh-CN' | 'en-US'
  EditorConfig,        // 编辑器配置
  ToolbarItem,         // 工具栏项
  ToolbarItemType,     // 'button' | 'dropdown' | 'color-picker' | 'divider' | 'group' | 'custom'
  ToolbarConfig,       // 工具栏配置
  ToolbarGroup,        // 工具栏分组
  UploadConfig,        // 上传配置
  UploadResult,        // 上传结果
  ShortcutBinding,     // 快捷键绑定
  EditorEventMap,      // 事件类型映射
  EditorExtension,     // 扩展接口
  ExtensionContext,    // 扩展上下文
  CollaborationConfig, // 协同编辑配置
} from '@axewo/fin-editor'