eeed-editor

eeed-editor

eeed-editor 是一个面向业务文档编辑场景的 Vue 3 富文本编辑器，基于 Tiptap 构建，适合在后台系统、知识库、合同/报告编辑、审批表单、A4 文档和技术文档页面中使用。

它内置文档级编辑体验、A4 页面、大纲、代码块、数学公式、Mermaid、图片处理、表格、Markdown 粘贴、保存/上传回调，以及 Word 和 Markdown 导出能力。

特性

• Vue 3 组件化接入
• 只需 import eeedEditor from "eeed-editor"，样式会自动注入
• 支持可编辑与只读预览
• 支持普通文档、A4 文档、表单富文本、移动端精简工具栏等场景
• 支持标题大纲、当前章节高亮、点击大纲定位
• A4 / defaultA4 编辑模式内置字数统计
• 支持代码块高亮与一键复制
• 支持数学公式、Mermaid 图表、可增删行列与合并单元格的表格、图片、引用、分割线、任务列表
• 支持 Markdown 内容初始化与 Markdown 粘贴
• 支持保存、上传、内容变更三个业务回调
• 支持导出 Word 与 Markdown

安装

npm install eeed-editor

或者：

pnpm add eeed-editor

vue 和 element-plus 是 peer dependencies，请确保业务项目中已经安装：

npm install vue element-plus

快速开始

注意：eeedEditor 外层必须包一个稳定容器，并设置 position: relative 和明确的宽高。编辑器内部默认会根据父容器定位和计算高度，尤其是 A4 文档模式、工具栏固定布局、大纲滚动等场景。

<template>
  <div class="editor-wrapper">
    <eeedEditor
      title="产品方案"
      :content="content"
      :config="config"
      :onSave="handleSave"
      :onUploadFile="handleUploadFile"
      :onChange="handleChange"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
import eeedEditor from "eeed-editor";

const content = ref("<h1>产品方案</h1><p>这里是正文内容。</p>");

const latestHtml = ref("");
const latestText = ref("");
const latestMarkdown = ref("");

const config = {
  mode: "doc",
  editable: true,
  doc: {
    page: {
      mode: "default",
      style: {
        position: "absolute",
        backgroundColor: "#f3f6f9",
      },
    },
    headerBar: {
      visible: true,
      home: { visible: true, icon: "home", path: "/" },
      export: { visible: true },
      title: { visible: true },
    },
    toolBar: {
      visible: true,
      align: "start",
    },
  },
} as const;

const handleSave = async (title: string, html: string) => {
  // 这里接入你的保存接口
  await Promise.resolve({ title, html });
  return true;
};

const handleUploadFile = async (file: File) => {
  const formData = new FormData();
  formData.append("file", file);

  // 替换成你的上传接口
  // const res = await fetch("/api/upload", { method: "POST", body: formData });
  // const data = await res.json();
  // return data.url;

  return URL.createObjectURL(file);
};

const handleChange = (html: string, text: string, markdown: string) => {
  latestHtml.value = html;
  latestText.value = text;
  latestMarkdown.value = markdown;
};
</script>

<style scoped>
.editor-wrapper {
  position: relative;
  width: 100%;
  height: 720px;
}
</style>

Props

Config 类型

type ToolBarItem =
  | "history"
  | "formatBrush"
  | "clearFormatting"
  | "fontFamily"
  | "heading"
  | "fontSize"
  | "fontColor"
  | "highlightColor"
  | "bold"
  | "italic"
  | "underline"
  | "strike"
  | "blockquote"
  | "horizontalRule"
  | "inlineCode"
  | "table"
  | "list"
  | "textAlign"
  | "indent"
  | "lineHeight"
  | "insert";

type EditorConfig = {
  mode?: "doc";
  editable?: boolean;
  doc?: {
    page?: {
      mode?: "default" | "defaultA4" | "A4";
      style?: {
        position?: "absolute" | "relative";
        backgroundColor?: string;
      };
    };
    headerBar?: {
      visible?: boolean;
      home?: {
        visible?: boolean;
        icon?: "back" | "home";
        path?: string;
      };
      export?: {
        visible?: boolean;
      };
      title?: {
        visible?: boolean;
      };
    };
    toolBar?: {
      visible?: boolean;
      align?: "start" | "center";
      items?: ToolBarItem[];
    };
    readOnly?: {
      theme?: "article" | "ai" | "plain";
      backgroundColor?: string;
      contentBackgroundColor?: string;
      maxWidth?: string;
    };
    content?: {
      sanitize?: boolean;
      streamDebounce?: number;
      streaming?: boolean;
      preserveScroll?: boolean;
      autoScroll?: boolean;
      pauseWhileSelecting?: boolean;
    };
    placeholder?: string;
  };
};

常用配置说明

业务回调

onSave

点击保存或快捷键保存时触发。

const handleSave = async (title: string, html: string) => {
  await saveDocument({
    title,
    content: html,
  });

  return true;
};

说明：

• title 是当前文档标题
• html 是编辑器 HTML 内容
• 返回 true 会显示保存成功提示
• 返回 false 或抛出异常时不会显示成功提示

onUploadFile

插入图片、上传文件，以及从本地拖入或复制粘贴图片、视频、音频、附件时触发。支持多个文件按原顺序插入；拖入使用鼠标落点，粘贴使用当前光标或选区。文件是否可粘贴取决于浏览器能否从系统剪贴板读取文件。

const handleUploadFile = async (file: File) => {
  const formData = new FormData();
  formData.append("file", file);

  const res = await fetch("/api/upload", {
    method: "POST",
    body: formData,
  });
  const data = await res.json();

  return data.url;
};

说明：

• 必须返回一个可访问的 URL
• 如果没有传 onUploadFile，图片会尝试以 base64 方式插入
• 生产环境建议接入自己的文件服务或对象存储

onChange

编辑器内容变化时触发。

const handleChange = (html: string, text: string, markdown: string) => {
  form.content = html;
  form.text = text;
  form.markdown = markdown;
};

说明：

• html 是完整 HTML 内容
• text 是纯文本内容
• markdown 是 Markdown 格式内容（v0.1.13+ 新增）
• 如果业务侧需要自动保存，建议自行做 debounce

场景示例

A4 文档编辑

适合合同、报告、方案、正式文档编辑。

const config = {
  mode: "doc",
  editable: true,
  doc: {
    page: {
      mode: "A4",
      style: {
        position: "absolute",
        backgroundColor: "#eef2f7",
      },
    },
    headerBar: {
      visible: true,
      home: { visible: true, icon: "back", path: "/" },
      export: { visible: true },
      title: { visible: true },
    },
    toolBar: {
      visible: true,
      align: "center",
    },
  },
} as const;

表单富文本字段

适合嵌入业务表单、审批表单、弹窗表单。

const config = {
  mode: "doc",
  editable: true,
  doc: {
    page: {
      mode: "default",
      style: {
        position: "absolute",
        backgroundColor: "#ffffff",
      },
    },
    headerBar: {
      visible: false,
    },
    toolBar: {
      visible: true,
      align: "start",
      items: [
        "history",
        "heading",
        "bold",
        "italic",
        "underline",
        "fontColor",
        "list",
        "insert",
      ],
    },
  },
} as const;

移动端精简编辑

适合手机端内容维护，只保留必要工具。

const config = {
  mode: "doc",
  editable: true,
  doc: {
    page: {
      mode: "default",
      style: {
        position: "absolute",
        backgroundColor: "#ffffff",
      },
    },
    headerBar: {
      visible: false,
    },
    toolBar: {
      visible: true,
      align: "start",
      items: ["history", "bold", "italic", "underline", "list", "insert"],
    },
  },
} as const;

只读预览

适合详情页、审批查看、归档文档展示。

只读预览模式不会展示头部栏、工具栏、大纲和字数统计。默认使用 article 主题：浅灰页面背景、白色正文卡片和适合长文阅读的内容宽度。公式、图片和 Mermaid 不会进入编辑状态，图片仍可双击放大查看。

const config = {
  mode: "doc",
  editable: false,
  doc: {
    readOnly: {
      theme: "article",
    },
  },
} as const;

如果希望沿用旧版的透明、无间距嵌入效果，使用 plain 主题：

<template>
  <div class="preview-wrapper">
    <eeedEditor :content="content" :config="previewConfig" />
  </div>
</template>

<script setup lang="ts">
import eeedEditor from "eeed-editor";

const previewConfig = {
  mode: "doc",
  editable: false,
  doc: {
    readOnly: {
      theme: "plain",
    },
    page: {
      style: {
        position: "relative",
      },
    },
  },
} as const;
</script>

<style scoped>
.preview-wrapper {
  position: relative;
  width: 100%;
}
</style>

AI 问答渲染

content 可以直接传入 AI 返回的 Markdown，支持标题、列表、表格、代码块、KaTeX 公式和 Mermaid。流式回答过程中持续更新 content 即可，编辑器只会应用最后一次完成的异步解析结果。

import { computed, ref } from "vue";

const isStreaming = ref(true);

const aiPreviewConfig = computed(() => ({
  mode: "doc",
  editable: false,
  doc: {
    page: { style: { position: "relative" } },
    readOnly: {
      theme: "ai",
      maxWidth: "100%",
    },
    content: {
      sanitize: true,
      streamDebounce: 80,
      streaming: isStreaming.value,
      preserveScroll: true,
      autoScroll: true,
      pauseWhileSelecting: true,
    },
  },
} as const));

// aiMarkdown 可以是完整回答，也可以随着流式输出持续更新
const aiMarkdown = `## 分析结果

核心公式：$E = mc^2$

\`\`\`ts
const answer = "支持代码高亮";
\`\`\`

\`\`\`mermaid
graph LR
  Q[问题] --> A[AI 回答]
\`\`\``;

// 流式响应结束后触发公式和 Mermaid 的最终渲染
isStreaming.value = false;

外部内容默认会经过安全清洗。只有在内容已经由可信服务端完成严格清洗、并且确实需要保留自定义 HTML 时，才考虑设置 sanitize: false。流式输出无需每个 token 都立即重绘，80ms 通常能兼顾跟手感和渲染开销。用户停留在底部时会自动跟随生成内容；向上滚动阅读或选中文字后，编辑器会尊重当前阅读状态。

技术文档

适合代码块、公式、Mermaid 图表、知识库文章。

const content = `
<h1>接口说明</h1>
<p>这里是技术文档内容。</p>
<pre><code class="language-typescript">const message: string = "hello";</code></pre>
<p>行内公式：$a^2 + b^2 = c^2$</p>
<pre><code class="language-mermaid">graph TD
  A[开始] --> B[结束]</code></pre>
`;

内容格式

content 推荐传 HTML：

const content = "<h1>标题</h1><p>正文内容</p>";

也可以传 Markdown 文本，编辑器会自动转成 HTML：

const content = `
# 标题

这是一段 Markdown 内容。

\`\`\`ts
const value = "eeed-editor";
\`\`\`
`;

数学公式

支持行内公式和块级公式：

<p>行内公式：$a^2 + b^2 = c^2$</p>

<p>块级公式：</p>
<p>$$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-i\omega t} dt$$</p>

代码块

支持常见语言代码高亮，并提供复制按钮。

<pre><code class="language-typescript">import { ref } from "vue";

const title = ref("eeed-editor");</code></pre>

Mermaid

可以在技术文档场景中插入 Mermaid 图表内容：

<pre><code class="language-mermaid">graph TD
  A[需求] --> B[开发]
  B --> C[上线]</code></pre>

表格

点击工具栏中的表格按钮，可以用 8×10 快捷网格选择尺寸，也可以输入行数和列数（最多 50 行、20 列），并选择是否将首行设为表头。

光标位于表格内时，同一菜单提供在当前行或列前后插入、删除行列、切换表头行/列和删除整个表格。按住鼠标拖过单元格或先点击起点再按 Shift 点击终点，可跨行列选择区域；右键单元格可直接设置所选单元格内容的左对齐、居中、右对齐，并执行表格操作。选中多个单元格后可合并，光标位于合并单元格内时可拆分。表格列宽可拖动调整；Tab 和 Shift+Tab 可在单元格之间移动。在现有表格内点击新建表格时，新表格会插入到当前表格之后。

音视频与本地文件

通过“插入 → 音视频 / 本地文件”选择文件。音视频入口同时接受视频和音频文件，会根据文件类型自动插入对应的视频或音频节点；音视频在文档中使用原生播放器，附件展示文件名、大小和下载按钮；编辑时可删除文件节点，预览时保留播放和下载。

上传复用 onUploadFile(file)，回调需返回可持久访问的 HTTP(S) 地址或相对路径。未配置回调时使用 Base64 保存文件数据。默认单文件上限为 50 MB，可通过 config.doc.upload.maxFileSize（字节）调整；生产环境建议接上传服务，避免大文件直接写入文档。演示站的文件使用 Base64。

媒体与附件会随 HTML 内容保存，重新传入 content 即可恢复。Markdown 导出为文件链接；Word 导出保留名称，HTTP(S) 文件地址会转换为链接。音视频是否可播放取决于浏览器支持的格式。

上传回调可接收第二个参数 onProgress(percentage)，将实际上传进度（0–100）回传给组件。媒体上传提示会显示文件名、进度条和百分比；旧的单参数回调仍兼容，未回传进度时显示等待动画。传输到 100% 后仍会等待上传接口返回最终文件地址。

const onUploadFile = (file: File, onProgress?: (percentage: number) => void) =>
  new Promise<string>((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    xhr.open("POST", "/api/upload");
    xhr.upload.onprogress = (event) => {
      if (event.lengthComputable) onProgress?.(event.loaded / event.total * 100);
    };
    xhr.onload = () => {
      if (xhr.status < 200 || xhr.status >= 300) return reject(new Error("上传失败"));
      try { resolve(JSON.parse(xhr.responseText).url); }
      catch { reject(new Error("上传响应无效")); }
    };
    xhr.onerror = () => reject(new Error("上传失败"));
    const body = new FormData();
    body.append("file", file);
    xhr.send(body);
  });

链接

输入网址并按空格后自动识别链接；粘贴文字和初始内容中的网址、邮箱也会识别。链接显示为蓝色下划线，悬停可查看完整地址。编辑模式点击链接显示轻量地址栏，可修改地址后按 Enter 或保存，也可移除链接并保留文字。Ctrl / Command 点击打开，预览模式直接点击打开。选中文字后粘贴完整网址可直接为文字添加链接，无需弹窗。

选区浮动工具栏

选中文字后，会在选区附近显示快捷工具栏，支持加粗、斜体、下划线、删除线、文字颜色、高亮、对齐、设置链接和清除文字格式。点击工具栏会保留选区；取消选择、切换只读或将选区滚出可视区域后隐藏。

工具栏使用 doc.toolBar.items 的工具项白名单；可通过 doc.bubbleMenu.visible: false 关闭。图片、媒体节点、表格单元格区域选择以及代码块选区不会显示文字工具栏。

查找替换

点击工具栏的放大镜，或在编辑区按 Ctrl+F（macOS 为 Command+F）打开查找替换。输入文字后会高亮所有命中，使用上下按钮或 Enter / Shift+Enter 跳转；可切换区分大小写，替换当前命中或一次替换全部。替换全部作为一次编辑操作，可撤销。关闭面板会清除查找高亮。

导出

当 doc.headerBar.export.visible 为 true 时，顶部栏会展示导出入口。

当前支持：

• 导出 Word
• 导出 Markdown

const config = {
  mode: "doc",
  editable: true,
  doc: {
    headerBar: {
      visible: true,
      export: { visible: true },
      title: { visible: true },
    },
  },
} as const;

大纲

在 A4 / defaultA4 文档模式下，编辑器会根据标题自动生成大纲。

A4 / defaultA4 编辑模式下会在编辑器右下角展示实时字数统计，统计口径为去除空白字符后的正文字符数。

支持：

• 自动提取标题一到标题六
• 点击大纲滚动到对应标题
• 滚动时高亮当前章节
• 空标题显示为“未命名标题”
• 可收起/展开大纲

工具栏精简

通过 doc.toolBar.items 可以保留部分工具，适合移动端或表单场景。

const config = {
  mode: "doc",
  editable: true,
  doc: {
    toolBar: {
      visible: true,
      align: "start",
      items: ["history", "bold", "italic", "underline", "list", "insert"],
    },
  },
} as const;

可选工具项：

[
  "history",
  "formatBrush",
  "clearFormatting",
  "fontFamily",
  "heading",
  "fontSize",
  "fontColor",
  "highlightColor",
  "bold",
  "italic",
  "underline",
  "strike",
  "blockquote",
  "horizontalRule",
  "inlineCode",
  "table",
  "list",
  "textAlign",
  "indent",
  "lineHeight",
  "insert",
]

样式说明

从当前版本开始，只需要：

import eeedEditor from "eeed-editor";

组件样式会随 JS 自动注入页面，不需要再额外写：

import "eeed-editor/dist/index.css";

为了兼容旧项目，包内仍然保留 dist/index.css 文件。

容器要求

编辑器依赖父容器计算布局，请确保外层容器稳定：

.editor-wrapper {
  position: relative;
  width: 100%;
  height: 720px;
}

如果父容器没有明确高度，可能会出现：

• 编辑器不可见
• 工具栏和正文区域重叠
• A4 页面定位异常
• 大纲滚动区域异常

常见问题

为什么打开后高度不对？

请检查外层容器是否设置了 position: relative 和明确高度。

为什么保存成功没有提示？

onSave 需要返回 true：

const handleSave = async () => {
  await save();
  return true;
};

为什么上传图片没有变成线上地址？

请传入 onUploadFile，并返回上传后的 URL。

为什么样式没有生效？

新版会自动注入样式。如果你使用了非常特殊的构建工具或 SSR 环境，可以临时手动引入：

import "eeed-editor/dist/index.css";

浏览器支持

推荐在现代浏览器中使用：

• Chrome / Edge 最新版
• Firefox 最新版
• Safari 最新版

链接

• 官网：https://editor.eeed.cn
• GitHub：https://github.com/zhangmingxin0120/eeed-editor
• npm：https://www.npmjs.com/package/eeed-editor

License

MIT

文档批注

选中文字，点击浮动工具栏的「添加批注」即可填写。带批注的文字显示细下划线和批注数量；点击原文或数字，在原文旁边展开小卡片。支持同一段文字添加多条批注、修改和删除，点击外部或 Escape 关闭。只读模式也能查看。

批注随 HTML 的 data-annotation-* 属性和 JSON marks 保存，位置随编辑变化，支持撤销/重做。外部清洗 HTML 时请保留这些属性。纯文本、Markdown 不保存批注元数据。打印隐藏卡片、数量和批注下划线。

批注限 2000 字；删除全部原文后批注随之删除，可撤销恢复。已有批注的选区再次添加时，会追加到该段批注。此功能不包含多人身份、权限或实时协作。

字体颜色与字体背景色

主工具栏与选区浮动工具栏使用相同的颜色面板：常用色、当前颜色标记、最近使用的六种颜色、自定义颜色选择及 HEX 输入。支持 #RGB、#RRGGBB；点击「应用」确认，不会在输入时修改正文。多种颜色的选区会显示「多种颜色」。

「默认颜色」仅清除字体颜色，「无背景色」仅清除字体背景色；其他格式和批注保留。重复选择同一种背景色保持设置。最近使用颜色只保存在当前编辑器会话中，字体颜色和背景色分别记录。

列表编辑

选中一个或多个段落，点击有序、无序或任务列表按钮即可转换；再次点击相同类型恢复正文，三种类型可直接互转，保留文字格式和批注。

• Enter 拆分列表项并接续；空项 Enter 先退出一层，最外层恢复正文。Shift+Enter 在同一项内换行。
• Tab / Shift+Tab 调整层级，支持选中多项；父项和子项一起移动，最多六层。工具栏缩进按钮同样适用。
• 有序列表顶层自动编号，子层级显示无序标记，普通段落会分隔列表。编号按钮旁的小箭头可从 1 重新编号、恢复自动接续或设置起始编号（1–9999）。
• 输入 1. 、- 、[ ] 或 [x] 自动创建相应列表。Ctrl/Command+Shift+7、8、9 分别切换三种列表。
• 任务可以直接勾选；Ctrl/Command+Enter 切换选中任务的完成状态。新建任务默认未完成，只读模式禁止修改。
• 列表编辑和任务状态支持撤销/重做；导入 HTML/Markdown 时保留嵌套子项、起始编号和任务状态，兼容原有列表保存格式。

隐藏与加密内容

选中文字后点击主工具栏或浮动工具栏的锁图标，可将选区替换为隐藏标记。也可选中图片、附件等节点后使用主工具栏操作。

• 不设置密码：仅折叠显示，任何人都能点击查看，不提供保密保护。
• 设置密码：密码至少六位，确认后在浏览器本地使用 AES-256-GCM 加密；密钥通过 PBKDF2-SHA-256（310000 次迭代）派生，每段使用随机盐和 IV。需要 HTTPS 或 localhost，不保存密码，密码遗失无法恢复。
• 点击标记就地查看，收起后重新隐藏；密码内容每次打开均需解锁。只读模式也可查看，解锁预览不改变保存的密文。
• 展开时使用正文同一套节点的独立只读渲染，支持公式、Mermaid、代码高亮、表格、图片、媒体、批注及嵌套隐藏内容；收起时销毁预览，不修改原文档或重排列表编号。
• 编辑模式解锁后可「取消隐藏，恢复正文」，恢复原有段落和文字格式。跨单元格的部分选区需分段隐藏。
• HTML 和 JSON 保存隐藏载荷；纯文本、Markdown、Word 与打印只保留占位提示，不能用这些格式恢复隐藏内容。外部 HTML 清洗需保留 data-type、data-hidden-id、data-hidden-payload。
• 加密保护当前保存的内容；本次编辑会话的撤销历史、此前保存的文档版本及外部副本不会被清除。

工具栏配置项为 hideContent。

上传回调支持第三个可选参数 signal?: AbortSignal。接入 fetch 时传入 { signal }，接入 XMLHttpRequest 时监听 signal 的 abort 事件并调用 xhr.abort()，即可实际终止网络请求。旧回调仍兼容；未处理 signal 时，取消会停止等待并阻止插入，但后台请求可能继续。多文件逐项显示文件名、进度、状态，完成一项即插入一项。