HTML 可视化编辑器

浏览器端 HTML 可视化编辑器 SDK。以 TypeScript 库的形式集成到任意 Web 应用，提供元素选择、拖拽移动、缩放、富文本编辑、工具栏、右键菜单、撤销重做、序列化等完整的可视化编辑能力。通过扩展机制按需加载功能，借鉴 VS Code 扩展模型实现声明式注册和条件激活。

功能特性

• 扩展机制 — Provider 声明 + 条件触发，支持即时激活、命令触发懒加载、DOM 元素触发懒加载
• 命令系统 — 扩展间通信统一走 commands.execute()，可观测、可拦截、可覆盖
• Shadow DOM 隔离 — 编辑器 UI 渲染在 Shadow DOM 内，被编辑内容留在 Light DOM 通过 <slot> 投射
• Result 模式 — 所有可能失败的操作返回 Result<T, E> 判别联合，不抛异常
• 16 个内置扩展 — 选择、拖拽、缩放、富文本、工具栏、右键菜单、历史记录、序列化、表格编辑、图片处理、插入面板、页面排序、矢量画板、PDF 分页、图表排版

环境要求

工具	版本
Node.js	>= 22
npm	>= 10

浏览器兼容：Chrome / Edge / Firefox / Safari 最近两个大版本。

快速开始

# 安装依赖
npm install

# 启动 Playground 开发服务器（端口 3000）
npm run dev

# 构建所有包
npm run build

# 运行全部测试
npm run test

全量引入

import { createEditor } from '@doonce/html-editor'
import { DEFAULT_EXTENSION_PROVIDERS } from '@doonce/html-editor-extensions'

const result = createEditor({
  container: document.getElementById('editor'),
  providers: DEFAULT_EXTENSION_PROVIDERS,
})

if (result.ok) {
  await result.editor.ready
  await result.editor.enable()
}

按需引入

import { createEditor } from '@doonce/html-editor'
import {
  selectorProvider,
  historyProvider,
  toolbarProvider,
} from '@doonce/html-editor-extensions'

createEditor({
  container,
  providers: [selectorProvider, historyProvider, toolbarProvider],
})

Tip

编辑器实例暴露 serialize() 方法导出干净的 HTML（剥离所有编辑器标记），loadContent({ html }) 加载 HTML 内容。

多编辑器管理

import { createEditorManager } from '@doonce/html-editor'

const { manager } = createEditorManager()
manager.register({ editor: editor1, id: 'main' })
manager.register({ editor: editor2, id: 'sidebar' })
await manager.enableAll()

技术栈

技术	用途
TypeScript 6.0	开发语言（ES Module）
Vite 8	SDK lib mode 打包 + Playground 开发服务器
Vitest	单元测试 + 集成测试
Playwright	E2E 端到端测试
Tailwind CSS 4.2	编辑器 UI 样式（编译后注入 Shadow DOM）
npm workspaces	Monorepo 管理

产物格式：ESM + UMD + .d.ts

架构

graph TB
  App[宿主应用] --> Core["@doonce/html-editor"]
  App --> Ext["@doonce/html-editor-extensions"]
  Core --> Types["@doonce/html-editor-types"]
  Ext --> Types

Loading

宿主应用传入一个 DOM 容器作为编辑区域。@doonce/html-editor 提供运行时框架（生命周期管理、扩展注册、命令分发、事件总线），不包含任何编辑功能。所有用户可见的功能由 @doonce/html-editor-extensions 中的独立扩展实现，通过命令系统交互，彼此无直接依赖。@doonce/html-editor-types 是纯类型包，定义所有跨包公共接口。

目录结构

目录	说明
packages/core	编辑器核心运行时
packages/extensions	16 个内置功能扩展
packages/types	共享 TypeScript 类型定义（纯类型，零运行时）
playground	开发调试用的示例应用
tests/integration	跨包集成测试（Vitest + happy-dom）
tests/e2e	端到端测试（Playwright）
run-control	共享构建配置（tsconfig / Vite / Vitest）
docs	设计文档和架构规范