Visual HTML Editor Vibe 项目

项目简介

Visual HTML Editor 是一款「源码优先」的可嵌入可视化 HTML 编辑器，专为编辑 AI 生成或已有的 HTML 内容而设计。传统上，可视化编辑器（WYSIWYG）会把 HTML 解析成自己的一套组件模型，编辑后再重新生成 HTML，这个过程往往会破坏原始代码的结构、属性和格式。Visual HTML Editor 采取了截然不同的思路：它直接在你现有的 HTML 源码上进行编辑，只修改用户实际改动的那一小部分，未被触及的源码区域会被完整保留。开发者可以精确控制用户能改什么、不能改什么，最终导出的 HTML 是干净的、不依赖编辑器运行时的可移植 HTML，可以直接接回现有的邮件、幻灯片或网页发布流程。项目目前在预发布 Alpha 阶段，核心编辑工作流已可试用。

核心功能

• 基于现有 HTML 直接编辑：加载完整的 HTML 文档或片段，无需把内容重建为编辑器专属的组件结构，可直接编辑产品已有的 HTML。
• 小改动保持小改动：文本、样式、属性的修改直接作用于源码，保留未被编辑的区域，而不是在浏览器 DOM 中重写整个文档。
• 可配置的编辑规则：开发者可以配置允许的标签、属性、CSS 属性、URL 和操作类型，核心命令与 UI 都会强制执行这些规则。
• 导出的内容可移植：导出的 HTML 不含编辑器运行时标记，也不依赖编辑器才能显示，可直接用于既有工作流。
• 灵活的集成深度：既可以嵌入 React 工作区，也可以使用框架无关的核心包，自行处理命令、校验、历史记录与导出。
• 多场景适配：内置邮件模板、演示幻灯片、网页内容三种编辑场景配置，并可通过格式适配器扩展。
• 命令行即开即用：通过 npx 命令可在不克隆仓库、不添加项目依赖的情况下，直接在本地打开一个 HTML 文件进行编辑。

技术实现

Visual HTML Editor 的核心技术难点在于「源码保真」（Source Fidelity）。大多数可视化编辑器采用「解析 → 编辑 → 重新序列化」的流程，这在处理结构复杂或带有特殊格式的 HTML 时极易产生意外改动——比如自动补全标签、重排属性顺序、丢失注释或改动实体编码。Visual HTML Editor 通过把编辑操作直接映射到源码区间的方案，让「把 beautiful 改成 wonderful」这类操作只改动文本内容，而保留周围原有的标签、属性语法（例如单引号 <em class="accent">）和缩进结构。项目为此专门维护了源码保真测试（source-fidelity tests）和兼容性测试夹具（compatibility fixtures），用来验证「无改动往返」「最小文本编辑」「精确撤销」等行为。保真范围限定在受支持的操作内：当改动涉及内联结构的替换时，被编辑区域可能会被整体替换。技术栈上，项目要求 Node.js 24.11.1（在 .nvmrc 中锁定）与 pnpm 12.4.1，核心包 @visual-html/core 负责解析、校验、历史记录与源码变换，React 包 @visual-html/react 提供可嵌入的工作区 UI。

快速上手

1. 不安装直接试用：在终端运行 npx @visual-html/editor@next ./document.html，会启动一个临时的本地编辑器，自动解析文档目录中的相对资源，只有在你选择「保存文件」时才写回，不会安装示例或修改项目清单。
2. 从源码运行完整展示：克隆仓库后，依次执行 npm install --global pnpm@12.4.1、pnpm install --frozen-lockfile、pnpm dev，然后在浏览器打开 http://127.0.0.1:4173/#/editor。
3. 选择场景开始编辑：在编辑器中选择 Email（邮件）、Slides（幻灯片）或 Web（网页）加载示例，点击文字直接修改，选中元素调整可用样式，用 Undo 撤销或用 Source 查看 HTML 源码，最后选择 Export HTML 下载结果。
4. 导入自己的 HTML：选择 Email 或 Web 场景后点击 Import HTML，检视报告的问题并确认替换；幻灯片导入使用格式适配器处理。
5. 在 React 中集成：安装带 next 标签的预发布包，用 @visual-html/core 的 webProfile（或 emailProfile / slidesProfile）传入 HtmlEditor 组件，通过 onChange 拿到每次提交编辑后的新源码；在保存或关闭边界上，持有 HtmlEditorHandle 引用并调用 await editorRef.current.flush() 以提交正在进行的输入。

适用人群

• 需要在自家产品中嵌入 HTML 编辑能力，但又不想让编辑器改写原有内容的 SaaS 与工具开发者。
• 正在使用 AI 生成 HTML（邮件模板、落地页、幻灯片），并希望让用户做小幅可视化修改的产品团队。
• 在 CMS、内部工具中需要提供「受控编辑」能力，限制用户可修改范围的工程团队。
• 关注源码保真、希望替代传统重型富文本编辑器的前端开发者。

官方链接

GitHub 仓库：https://github.com/kong75/visual-html-editor 在线 Demo：https://kong75.github.io/visual-html-editor/ NPM 包（预发布）：npx @visual-html/editor@next