ai-word-editor（Vue3 富文本编辑器组件包）

基于 Vue3 + Vite 的编辑器组件包，提供：

• 编辑器组件：在业务项目中直接使用
• Word 导出：将 HTML 导出为 .docx（可选批注数据）

环境要求

• Node.js：建议 18+
• Vue：3.x

安装

npm install ai-word-editor
# 或 pnpm add ai-word-editor
# 或 yarn add ai-word-editor

快速开始（推荐：插件方式）

1）在 main.ts 注册

import { createApp } from 'vue'
import App from './App.vue'
import { UmoEditorAppPlugin } from 'ai-word-editor'
import 'ai-word-editor/style.css'

createApp(App).use(UmoEditorAppPlugin, {}).mount('#app')

2）在页面中使用

<template>
  <UmoEditorApp cdn-url="/umo-editor-external" />
</template>

重要：cdn-url 静态资源（必须配置）

@umoteam/editor 运行时需要加载 @umoteam/editor-external 的静态资源。 线上环境不要依赖 '/node_modules/@umoteam/editor-external' 这类路径（通常不可用）。

推荐做法：

• 将 node_modules/@umoteam/editor-external 复制/同步到宿主项目 public/umo-editor-external/
• 然后组件传入：cdn-url="/umo-editor-external"

按需使用（只导入组件）

import { UmoEditorApp } from 'ai-word-editor'

Word 导出（仅使用导出能力）

exportToDocx（带批注）

import { exportToDocx } from 'ai-word-editor/word-docx-export'

await exportToDocx(html, comments, '文件名')

• html：编辑器生成的 HTML 字符串（例如 Tiptap 的 editor.getHTML()）
• comments：批注数组，形如 [{ id, note, author, createdAt, resolved }]
• '文件名'：导出的文件名（不含 .docx），默认为 '文档'

exportHtmlToDocx（纯 HTML，无批注）

import { exportHtmlToDocx } from 'ai-word-editor/word-docx-export'

await exportHtmlToDocx(html, '文件名')

• html：编辑器生成的 HTML 字符串
• '文件名'：导出的文件名（不含 .docx），默认为 '文档'

依赖说明：

• 宿主项目需安装 file-saver、jszip

Word 导入（仅使用导入能力）

parseDocxToStyledHtml / parseDocxToStyledJSON

import {
  parseDocxToStyledHtml,
  parseDocxToStyledJSON,
} from 'ai-word-editor/word-docx-import'

const html = await parseDocxToStyledHtml(file)
const json = await parseDocxToStyledJSON(file)

• file：用户上传的 .docx 文件（File 对象）
• html：保留字体、字号、颜色、加粗、斜体、下划线、删除线、对齐方式等样式的 HTML 字符串
• json：与编辑器 getJSON() 兼容的 ProseMirror 文档 JSON，用于直接导入编辑器

parseDocxComments（解析 Word 批注）

import { parseDocxComments } from 'ai-word-editor/word-docx-import'

const comments = await parseDocxComments(file)

• 返回值形如：[{ wordId, author, date, note, selectedText, containsDelText }]
• 可结合编辑器的 CommentMark / 批注侧边栏，在导入文档时按 selectedText 恢复批注

宿主注入批注：UmoEditorApp 实例方法 setComments

用于在已有正文的前提下，按 selectedText 在文档中定位并插入批注 Mark（策略与 Word 导入后恢复批注相同）。适合智能审查、外部 CommentPanel 与编辑器解耦的场景。

类型（从包内导出）

import type {
  SetCommentItem,
  SetCommentsOptions,
  SetCommentsResult,
} from 'ai-word-editor'

调用示例

<script setup lang="ts">
import { ref } from 'vue'
import { UmoEditorApp, type UmoEditorInstance } from 'ai-word-editor'

const editorRef = ref<UmoEditorInstance | null>(null)

async function applyAuditComments() {
  const items = [
    {
      id: 'stable-id-1', // 可选；不传则内部生成
      selectedText: '乙方应向甲方提供未经使用的全新原装产品。',
      note: '【审核要点】……\n\n审核结论：……',
      author: '智能审核',
      colorIndex: 17, // 可选；不传则按顺序轮换颜色
    },
  ]
  // replace: true 会先移除当前文档内全部批注 Mark 并清空组件内批注列表与 pending 队列，再写入本次数据
  const res = await editorRef.value?.setComments(items, { replace: true })
  console.log(res) // { ok, applied, skipped, skippedItems? }
}
</script>

<template>
  <UmoEditorApp ref="editorRef" cdn-url="/umo-editor-external" />
</template>

行为说明

• selectedText 必须在正文里能唯一匹配才会打上 Mark；无法匹配的条目计入 skipped，并在 skippedItems 中标注 no_match（空字符串为 empty_text）。
• 若需 Word 导入后再叠加宿主批注，不要使用 replace: true，以免清空 Word 已恢复的批注；若要以智能审查结果覆盖文档内全部批注，可在导入完成后调用 setComments(..., { replace: true })（会一并清掉 Word 原生恢复的 Mark）。

批注双向联动（正文 <-> 面板）

UmoEditorApp 内置了批注双向定位：

• 点击右侧批注面板项，会定位并高亮正文中的对应批注文本。
• 点击正文中的批注文本（comment-mark），会反向激活面板中的对应批注项，并自动滚动到可视区域。

事件：activeCommentChange

组件会在“当前激活批注 ID”变化时触发：

<UmoEditorApp
  @activeCommentChange="onActiveCommentChange"
/>

const onActiveCommentChange = (commentId: string | null) => {
  // 可用于外部联动（例如业务侧详情面板、审查列表等）
}

自定义 comment-panel 插槽约定

如果使用自定义面板（而非默认 CommentPanel），建议：

• 以插槽提供的 activeCommentId 作为激活态唯一来源；
• 面板内部监听 activeCommentId，并在变化后将目标项 scrollIntoView；
• 每条面板项增加稳定标识（如 data-comment-id），便于精准定位。

FAQ

• 页面空白/资源 404：优先检查 cdn-url 是否指向已同步到 public 的资源目录。
• 导出失败：确认宿主项目已安装 file-saver、jszip，并检查运行环境是否允许下载文件。

联系方式

• 微信：扫码添加（备注：ai-word-editor）

本仓库打包与发布（维护者）

在本仓库执行：

npm run build:lib

产物输出到 dist/，类型声明输出到 dist/types/。