FDocxEditor

FDocxEditor 是一个基于 Vue 3 的 Word 报告组件，支持 docx 模板渲染、页面预览、定点富文本编辑和导出最新 docx。

安装

npm install f-docx-editor

项目结构

f-docx-editor/ ├── src/ │ ├── FDocxEditor.vue # 核心组件 │ ├── FDocxTemplateEditor.vue # 全文模板编辑组件 │ ├── index.js # 组件导出入口 │ ├── App.vue # 开发测试用 App │ └── main.js # 开发入口 ├── example/ # 示例代码 ├── scripts/ │ └── prepare-package.mjs # 打包脚本 ├── public/ │ └── index.html ├── package.json ├── vue.config.js └── README.md

使用方式

开发测试

cd /Users/fang/Documents/f-docx-editor npm install npm run serve

构建库

npm run build:lib

发布到 npm

npm run build:lib npm run publish

import FDocxEditor from 'f-docx-editor'
import 'f-docx-editor/FDocxEditor.css'

基础使用

<template>
  <FDocxEditor
    ref="editorRef"
    render-type="edit"
    :render-data="reportData"
    template-url="/运营报告.docx"
    @save-payload-change="handleSavePayloadChange"
  />
</template>

模板配置

发布到 npm 的包不会内置 运营报告.docx，避免把业务模板、真实字段和示例数据一起发布出去。

你需要在业务系统中提供模板文件，有两种方式：

1. 放到业务项目的 public/运营报告.docx，组件使用 template-url="/运营报告.docx"。
2. 由后端或文件服务返回模板地址，组件使用 template-url="https://your-domain/path/运营报告.docx"。

模板中的可编辑变量需要使用：

[EDITOR_START] {字段名} [EDITOR_END]

例如：

[EDITOR_START] {OverallSituation} [EDITOR_END]

后端保存时建议保存 save-payload-change 事件抛出的结构，其中富文本内容在 renderData.__editableRichTextMap 中。下次渲染时，把后端保存后的完整 renderData 重新传给组件即可。

Props

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | renderData | Object | {} | docxtemplater 渲染数据，包含普通变量、循环数据、图表数据和富文本数据 | | renderType | 'view' \| 'edit' \| 'templateEdit' | 'view' | view 为只预览，edit 为定点可编辑，templateEdit 为全文模板编辑 | | templateUrl | String | '' | 推荐使用，指定 docx 模板文件地址 | | templateFileName | String | '运营报告.docx' | 未传 templateUrl 时，从站点根路径加载该文件 | | exportFileName | String | '' | 自定义导出文件名 |

模板编辑

renderType="templateEdit" 会进入全文 Word 模板编辑模式。该模式直接加载原始 docx 模板，不执行变量渲染，也不会隐藏 [EDITOR_START] / [EDITOR_END] 等显性标签。

保存模板时通过组件 ref 调用 saveTemplate()，组件会抛出 template-save 事件，由外层把修改后的 docx 文件提交给后端。

<template>
  <FDocxEditor
    ref="editorRef"
    render-type="templateEdit"
    template-url="/api/report-template.docx"
    @template-save="handleTemplateSave"
  />
</template>

暴露方法

通过 ref 可以调用：

| 方法 | 说明 | | --- | --- | | exportDocx() | 导出最新 docx | | getRenderData() | 获取当前组件内最新 renderData | | getSavePayload() | 获取建议提交给后端的保存结构 | | getEditorHtml() | 获取当前弹窗编辑器 HTML | | getEditorJson() | 获取当前弹窗编辑器 JSON | | saveTemplate() | 保存全文模板编辑后的 docx，并触发 template-save | | reloadTemplate() | 重新加载当前模板文件 |

数据安全建议

不要把真实业务模板、真实接口数据、内部地址、账号信息、密钥或生产 mock 数据发布进 npm 包。模板文件建议由业务系统自行托管，并通过 templateUrl 注入。