@vg-print/plugin-api-word 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# 变更日志
+
+## 0.1.0 — 2026-11-06
+
+- 新增 `hiprint.register({ plugins: [pluginApiWord()] })` 注入与 `template.toWord()` 方法。
+- 新增独立 `exportWord()` API，支持下载和返回 DOCX Blob。
+- 基于引擎渲染 DOM 转换原生段落、表格、横纵合并及并排布局；图表/条码等局部图片化。
+- 新增进度、转换警告、类型解析和异步写入前回调。
+- 提供 ESM 包入口、TypeScript 声明和中文使用说明。
+- 静态核对阶段，尚未在 Word/WPS 中验证排版精度。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vg-print contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,143 @@
-# Temporary Holding Version
+# @vg-print/plugin-api-word
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+为 `vg-print` 打印模板添加可编辑 `.docx` 导出。由宿主通过 `hiprint.register` 注入，不依赖 Vue、不创建额外打印引擎，也不需要打印客户端、本机 Office 或云端转换服务。
+
+文字与表格生成 Word 原生内容；图片、条码、二维码、图表生成局部图片。不会把整页截图伪装成“可编辑 Word”。
+
+## 安装与注册
+
+```bash
+npm install vg-print @vg-print/plugin-api-word
+```
+
+```js
+import { hiprint, createTemplate } from 'vg-print'
+import 'vg-print/style.css'
+import pluginApiWord from '@vg-print/plugin-api-word'
+
+// 请等待 register 完成，尤其是同时传入签名授权时。
+await hiprint.register({
+  plugins: [
+    pluginApiWord({
+      fontName: 'Microsoft YaHei',
+      onWarning: warning => console.warn(warning.message)
+    })
+  ]
+})
+
+const template = createTemplate(templateJson)
+await template.toWord(printData, { name: '报告.docx' })
+
+// 不下载，获取 Blob，可自行上传或保存。
+const blob = await template.toWord(printData, {
+  isDownload: false,
+  name: '报告.docx'
+})
+```
+
+必须传入模板实例，原始模板 JSON 请先使用 `createTemplate()` 构造。插件注册前后创建的实例共享同一原型；重复注册只更新默认配置。
+
+也可以不注册，直接使用独立 API：
+
+```js
+import { exportWord } from '@vg-print/plugin-api-word'
+const blob = await exportWord(template, printData, { isDownload: false })
+```
+
+## API
+
+`template.toWord(printData, options?): Promise<Blob>`
+
+| 配置 | 默认值 | 说明 |
+| --- | --- | --- |
+| `isDownload` | `true` | 下载文件；无论是否下载都返回 Blob |
+| `name` | `vg-print-{timestamp}.docx` | 文件名，自动补 `.docx` |
+| `title` | `vg-print Word export` | 文档元数据标题 |
+| `fontName` | `Microsoft YaHei` | 默认字体，组件已有字体优先 |
+| `fontSize` | `10` | 默认字号，单位 pt，组件已有字号优先 |
+| `pixelRatio` | `2` | 图片组件截图倍率，不影响可编辑文字 |
+| `pageBreaks` | `true` | 按打印引擎输出的页分节；`false` 使用连续分节 |
+| `renderOptions` | — | 传给 `getHtml`，支持 `beforeGetHtml`；小标签拼版固定关闭 |
+| `customTypeResolver` | — | `(element, defaultType) => type \| undefined` |
+| `onProgress` | — | `(current, total)`，当前页完成转换时回调 |
+| `onWarning` | — | 接收布局降级说明 |
+| `onBeforeWrite` | — | 转换每页后、写入文档前修改原生内容，支持异步 |
+
+`onProgress` 最后一次回调表示页面转换完成，文件压缩和下载仍在进行；请用 `await toWord()` 控制 loading。
+
+`pageBreaks: false` 仍保留各节纸张尺寸，Word 会根据内容自然分页；不同纸张尺寸可能强制换页。默认分节也不能阻止编辑后的内容增加页数。
+
+```js
+await template.toWord(printData, {
+  onProgress: (current, total) => console.log(current, total),
+  onWarning: ({ code, message, pageIndex }) => {
+    console.warn(`第 ${pageIndex + 1} 页 [${code}] ${message}`)
+  },
+  customTypeResolver: (element, defaultType) => {
+    if (element.classList.contains('my-chart')) return 'image'
+    return undefined
+  },
+  onBeforeWrite: async ({ children, pageIndex }) => {
+    // children 为 docx 的 Paragraph/Table 数组。
+    // 可原地修改；返回新数组则替换这一页的内容。
+    return children
+  }
+})
+```
+
+支持的转换类型：`content`（原生文字/表格）、`container`（布局容器）、`hline`（原生段落边框）、`image`（局部图片）、`other`（图片回退并警告）。
+
+TypeScript 使用方可以显式补充模板方法类型：
+
+```ts
+import type { WordPrintTemplate } from '@vg-print/plugin-api-word'
+const wordTemplate = template as WordPrintTemplate
+const blob = await wordTemplate.toWord(printData, { isDownload: false })
+```
+
+## 转换范围与精度
+
+- 读取 `getHtml()` 渲染后的页面，复用字段绑定、格式化、内容隐藏和引擎分页结果。
+- 普通文本、长文本保留可编辑内容、基本字体样式、显式换行和对齐。
+- 动态/静态表格、e2table、w2html 中的 HTML 表格转换为原生 Word 表格，支持列宽、横纵合并、边框、背景和表头。
+- 并排组件用无边框表格布局；矩形容器按实际包围范围分组，内容编辑后自然撑高。装饰矩形包围其他内容时也会按容器处理。
+- 长文本标题与正文的横向布局转换为双列表格。
+- 图片、条码、二维码、图表、竖线、椭圆作为图片；内部文字和图表数据不可原生编辑。
+- 渲染 DOM 已包含的水印保留为背景图片；编辑型 Word 不是防篡改文件。
+
+不保证任意模板与预览逐像素一致。Word/WPS 的字体度量、行距、自动换行和分页与浏览器不同；自由重叠、旋转文字、复杂 CSS、混合定位和复杂列表不保证还原。未知组件使用图片回退，重叠组件按阅读顺序输出并报告警告。
+
+常规报告/规整表单更适合导出；不使用固定行高截断长文本。页眉页脚和页码来自引擎每页的渲染内容，作为每节正文输出，不转换为自动更新的 Word 页码域或原生重复页眉页脚。
+
+图片截图使用 `@zumer/snapdom`；跨域图片需允许 CORS，图片缺失或截图失败可能导致导出失败。`fontName` 不会自动安装或嵌入接收方字体。
+
+只支持浏览器导出。调用时需有 DOM、已加载设计器样式和可用字体。相同模板的 Word 导出会串行执行；建议不要同时对同一模板进行其他预览/导出操作。
+
+## 本地配套开发与发布
+
+插件项目与设计器项目为兄弟目录：
+
+```text
+cusom+vgPrint/
+├── api-word/
+└── vue-plugin-hiprint-demo/
+```
+
+设计器将此包作为 `file:../api-word` 开发依赖，通过 `src/main.js` 注册。开发 Vite 别名直接读取本项目源码，`dedupe` 从设计器解析插件依赖。
+
+```bash
+# 在设计器目录执行；将本地包安装为副本，依赖放在设计器 node_modules。
+npm install --install-links --ignore-scripts
+```
+
+设计器库入口不 import 插件，库打包将插件列为 external，并声明为可选 peer dependency。外部项目按需安装注册后，FullDesigner/Preview 自动显示 Word 按钮。
+
+此包直接发布 ESM 源码和类型声明，无需构建步骤，不提供 CommonJS `require` 入口。
+
+```bash
+# 在 api-word 目录执行；先检查发布内容，再发布。
+npm pack --dry-run
+npm publish --access public
+```
+
+当前实现仅做静态核对。正式发布前请用代表性模板检查 Word/WPS 中的文件可打开性、文字编辑、跨页表格、合并单元格、并排内容、图片和字体替换结果。

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@vg-print/plugin-api-word",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Editable DOCX export plugin for vg-print, installed through hiprint.register.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["src", "README.md", "CHANGELOG.md", "LICENSE"],
+  "dependencies": {
+    "docx": "9.5.1",
+    "@zumer/snapdom": "^2.0.2"
+  },
+  "publishConfig": { "access": "public" },
+  "engines": { "node": ">=18.18.0" }
+}

package/src/convert.js

@@ -0,0 +1,420 @@
+import {
+  Paragraph, TextRun, ImageRun, Table, TableRow, TableCell,
+  BorderStyle, WidthType, TableLayoutType, HeightRule, AlignmentType
+} from 'docx'
+import { snapdom } from '@zumer/snapdom'
+
+// CSS px -> twip（1/20pt）；字号使用半 pt，与布局尺寸不能混用。
+const twip = px => Math.round(Math.max(0, Number(px) || 0) * 15)
+const number = value => Number.parseFloat(value) || 0
+const styleOf = element => getComputedStyle(element)
+const NONE = { style: BorderStyle.NONE, size: 0, color: 'FFFFFF' }
+const NO_BORDERS = { top: NONE, bottom: NONE, left: NONE, right: NONE, insideHorizontal: NONE, insideVertical: NONE }
+const empty = () => new Paragraph({ spacing: { before: 0, after: 0, line: 1 }, children: [new TextRun({ text: '', size: 1 })] })
+const finish = children => {
+  // Word 单元格和文档结尾需要段落，嵌套表格后补一个极小空段落。
+  if (!children.length || children[children.length - 1] instanceof Table) children.push(empty())
+  return children
+}
+
+function color(value) {
+  if (!value || value === 'transparent') return undefined
+  const hex = value.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i)
+  if (hex) return hex[1].length === 3 ? hex[1].split('').map(c => c + c).join('') : hex[1]
+  const rgb = value.match(/^rgba?\(\s*(\d+)[,\s]+(\d+)[,\s]+(\d+)(?:\s*[,/]\s*([\d.]+))?\s*\)$/i)
+  if (!rgb || (rgb[4] !== undefined && Number(rgb[4]) === 0)) return undefined
+  return rgb.slice(1, 4).map(c => Math.min(255, Number(c)).toString(16).padStart(2, '0')).join('')
+}
+
+function borders(style) {
+  return Object.fromEntries(['top', 'right', 'bottom', 'left'].map(side => {
+    const prefix = 'border' + side[0].toUpperCase() + side.slice(1)
+    const width = number(style[prefix + 'Width'])
+    const kind = style[prefix + 'Style']
+    const border = width && kind !== 'none' && kind !== 'hidden' ? {
+      style: kind === 'dashed' ? BorderStyle.DASHED : kind === 'dotted' ? BorderStyle.DOTTED :
+        kind === 'double' ? BorderStyle.DOUBLE : BorderStyle.SINGLE,
+      size: Math.max(1, Math.round(width * 6)),
+      color: color(style[prefix + 'Color']) || '000000'
+    } : NONE
+    return [side, border]
+  }))
+}
+
+function visible(element) {
+  const style = styleOf(element)
+  return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0'
+}
+
+function runStyle(element, context) {
+  const style = styleOf(element)
+  const decoration = style.textDecorationLine || ''
+  return {
+    font: style.fontFamily?.split(',')[0].trim().replace(/["']/g, '') || context.options.fontName,
+    size: Math.max(1, Math.round((number(style.fontSize) || context.options.fontSize * 4 / 3) * 1.5)),
+    bold: Number(style.fontWeight) >= 600 || style.fontWeight === 'bold',
+    italics: style.fontStyle === 'italic',
+    color: color(style.color),
+    underline: decoration.includes('underline') ? {} : undefined,
+    strike: decoration.includes('line-through'),
+    subScript: element.tagName === 'SUB',
+    superScript: element.tagName === 'SUP',
+    characterSpacing: twip(number(style.letterSpacing)),
+    shading: color(style.backgroundColor) ? { fill: color(style.backgroundColor) } : undefined
+  }
+}
+
+function paragraph(runs, element) {
+  const style = styleOf(element)
+  const alignments = { center: AlignmentType.CENTER, right: AlignmentType.RIGHT, end: AlignmentType.RIGHT, justify: AlignmentType.JUSTIFIED }
+  const line = number(style.lineHeight)
+  const isCell = ['TD', 'TH'].includes(element.tagName)
+  return new Paragraph({
+    children: runs,
+    alignment: alignments[style.textAlign] || AlignmentType.LEFT,
+    // 不固定段落高度，编辑后仍允许内容自然撑开。
+    spacing: { before: twip(number(style.marginTop)), after: twip(number(style.marginBottom)), ...(line ? { line: twip(line), lineRule: 'atLeast' } : {}) },
+    indent: {
+      left: isCell ? 0 : twip(number(style.paddingLeft)),
+      right: isCell ? 0 : twip(number(style.paddingRight)),
+      firstLine: twip(number(style.textIndent))
+    }
+  })
+}
+
+/**
+ * 图片组件、SVG 条码、Canvas 图表使用局部截图，不栅格化文字/表格。
+ * 图片加载/跨域失败应使导出失败，避免生成缺图却提示成功的文件。
+ */
+async function imageRun(element, context, maxWidth, floating) {
+  const rect = element.getBoundingClientRect()
+  const width = Math.max(1, Math.min(rect.width, maxWidth || rect.width))
+  const height = Math.max(1, rect.height * width / Math.max(1, rect.width))
+  const canvas = await snapdom.toCanvas(element, { scale: Number(context.options.pixelRatio), backgroundColor: 'transparent' })
+  const blob = await new Promise((resolve, reject) => {
+    canvas.toBlob(result => result ? resolve(result) : reject(new Error('图片组件转换失败')), 'image/png')
+  })
+  return new ImageRun({
+    type: 'png',
+    data: new Uint8Array(await blob.arrayBuffer()),
+    transformation: { width, height },
+    floating
+  })
+}
+
+/**
+ * 富文本递归转换：保留显式换行、内联样式、图片和原生表格。
+ * 块级元素按段落拆分；不把 textContent 当作完整富文本使用。
+ */
+async function htmlBlocks(root, context, maxWidth) {
+  // longText 的 flex 标题/正文，以及 html 内容缩进的绝对定位标题，
+  // 转换成原生双列表格，避免标题另起一行或用空格模拟对齐。
+  const direct = Array.from(root.children).filter(el => visible(el) && !['STYLE', 'SCRIPT'].includes(el.tagName))
+  const rootStyle = styleOf(root)
+  const hasText = Array.from(root.childNodes).some(node => node.nodeType === 3 && node.textContent.trim())
+  if (!hasText && direct.length > 1 && (
+    (rootStyle.display === 'flex' && rootStyle.flexDirection === 'row') ||
+    direct.some(el => styleOf(el).position === 'absolute')
+  )) {
+    const origin = root.getBoundingClientRect()
+    const items = direct.map(el => ({ ...rectangle(el, origin), type: 'content' }))
+    const horizontal = items.every((item, index) => items.slice(index + 1).every(other =>
+      Math.min(item.right, other.right) - Math.max(item.left, other.left) <= 1
+    ))
+    if (horizontal) return layout(items, Math.min(origin.width || maxWidth, maxWidth), context)
+    context.warn('html-layout', '富文本复杂定位已按阅读顺序转换', root, context.pageIndex)
+  }
+  const output = []
+  let runs = []
+  const flush = element => {
+    if (runs.length) {
+      output.push(paragraph(runs, element || root))
+      runs = []
+    }
+  }
+  const walk = async node => {
+    if (node.nodeType === 3) {
+      const parent = node.parentElement || root
+      const whiteSpace = styleOf(parent).whiteSpace
+      const text = /pre|break-spaces/.test(whiteSpace) ? node.textContent : node.textContent.replace(/\s+/g, ' ')
+      if (text.trim() || runs.length || /pre/.test(whiteSpace)) {
+        const lines = text.split(/\r\n|\r|\n/)
+        lines.forEach((line, index) => {
+          if (index) runs.push(new TextRun({ break: 1 }))
+          if (line) runs.push(new TextRun({ text: line, ...runStyle(parent, context) }))
+        })
+      }
+      return
+    }
+    if (node.nodeType !== 1 || !visible(node)) return
+    const tag = node.tagName
+    if (['STYLE', 'SCRIPT', 'NOSCRIPT'].includes(tag)) return
+    if (tag === 'BR') { runs.push(new TextRun({ break: 1 })); return }
+    if (tag === 'TABLE') {
+      flush(root)
+      output.push(await htmlTable(node, context, maxWidth))
+      return
+    }
+    if (['IMG', 'SVG', 'CANVAS'].includes(tag)) {
+      runs.push(await imageRun(node, context, maxWidth))
+      return
+    }
+    const nodeStyle = styleOf(node)
+    const block = /^(block|flex|grid|list-item|table-caption)$/.test(nodeStyle.display)
+    if (block) {
+      flush(root)
+      // 每个块递归进入 htmlBlocks，嵌套的标题/正文布局也会被识别。
+      const children = await htmlBlocks(node, context, Math.min(node.getBoundingClientRect().width || maxWidth, maxWidth))
+      output.push(...children)
+      return
+    }
+    for (const child of node.childNodes) await walk(child)
+  }
+  if (root.tagName === 'LI') runs.push(new TextRun({ text: '• ', ...runStyle(root, context) }))
+  for (const node of root.childNodes) await walk(node)
+  flush(root)
+  return finish(output)
+}
+
+/** 合并单元格通过显式网格保留 colspan/rowspan，避免仅按 DOM 下标错位。 */
+async function htmlTable(table, context, maxWidth) {
+  const rows = Array.from(table.rows).filter(visible)
+  if (!rows.length) return new Table({
+    rows: [new TableRow({ children: [new TableCell({ children: [empty()] })] })],
+    borders: NO_BORDERS
+  })
+  const occupied = []
+  const placements = rows.map((row, rowIndex) => {
+    occupied[rowIndex] ||= []
+    let column = 0
+    return Array.from(row.cells).filter(visible).map(cell => {
+      while (occupied[rowIndex][column]) column++
+      const colSpan = Math.max(1, cell.colSpan)
+      // HTML rowspan=0 表示延续到当前行组末尾。
+      const groupRows = Array.from(row.parentElement.children).filter(el => el.tagName === 'TR')
+      const remaining = groupRows.length - groupRows.indexOf(row)
+      const rowSpan = Math.min(cell.rowSpan === 0 ? remaining : Math.max(1, cell.rowSpan), rows.length - rowIndex)
+      const position = { cell, column, colSpan, rowSpan }
+      for (let y = rowIndex; y < rowIndex + rowSpan; y++) {
+        occupied[y] ||= []
+        for (let x = column; x < column + colSpan; x++) occupied[y][x] = true
+      }
+      column += colSpan
+      return position
+    })
+  })
+  const count = Math.max(...occupied.map(row => row.length), 1)
+  const tableRect = table.getBoundingClientRect()
+  const width = Math.max(1, Math.min(tableRect.width || maxWidth, maxWidth))
+  const edges = new Array(count + 1).fill(undefined)
+  edges[0] = 0
+  edges[count] = tableRect.width
+  placements.flat().forEach(({ cell, column, colSpan }) => {
+    const rect = cell.getBoundingClientRect()
+    edges[column] ??= rect.left - tableRect.left
+    edges[column + colSpan] ??= rect.right - tableRect.left
+  })
+  // 完全合并的列可能没有独立边界，按相邻已知边界均分。
+  for (let start = 0; start < count;) {
+    let end = start + 1
+    while (end < count && edges[end] === undefined) end++
+    for (let x = start + 1; x < end; x++) edges[x] = edges[start] + (edges[end] - edges[start]) * (x - start) / (end - start)
+    start = end
+  }
+  const ratio = width / Math.max(1, tableRect.width)
+  const widths = Array.from({ length: count }, (_, column) => Math.max(1, twip((edges[column + 1] - edges[column]) * ratio)))
+  const result = []
+  for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
+    const cells = []
+    for (const { cell, column, colSpan, rowSpan } of placements[rowIndex]) {
+      const style = styleOf(cell)
+      const cellWidth = widths.slice(column, column + colSpan).reduce((sum, value) => sum + value, 0)
+      cells.push(new TableCell({
+        children: await htmlBlocks(cell, context, Math.max(1, cellWidth / 15 - number(style.paddingLeft) - number(style.paddingRight))),
+        columnSpan: colSpan,
+        rowSpan,
+        width: { size: cellWidth, type: WidthType.DXA },
+        borders: borders(style),
+        margins: {
+          top: twip(number(style.paddingTop)), bottom: twip(number(style.paddingBottom)),
+          left: twip(number(style.paddingLeft)), right: twip(number(style.paddingRight))
+        },
+        shading: color(style.backgroundColor) ? { fill: color(style.backgroundColor) } : undefined,
+        verticalAlign: style.verticalAlign === 'middle' ? 'center' : style.verticalAlign === 'bottom' ? 'bottom' : 'top'
+      }))
+    }
+    result.push(new TableRow({
+      children: cells,
+      tableHeader: rows[rowIndex].parentElement.tagName === 'THEAD',
+      height: { value: twip(rows[rowIndex].getBoundingClientRect().height), rule: HeightRule.ATLEAST }
+    }))
+  }
+  return new Table({ rows: result, width: { size: twip(width), type: WidthType.DXA }, columnWidths: widths, layout: TableLayoutType.FIXED, borders: NO_BORDERS })
+}
+
+function elementType(element) {
+  const classes = element.classList
+  if (classes.contains('hiprint-printElement-rect')) return 'container'
+  if (classes.contains('hiprint-printElement-hline')) return 'hline'
+  if (['image', 'barcode', 'qrcode', 'echarts', 'oval', 'vline'].some(type => classes.contains('hiprint-printElement-' + type))) return 'image'
+  if (['text', 'longText', 'html', 'w2html', 'e2table', 'table', 'staticGridTable'].some(type => classes.contains('hiprint-printElement-' + type))) return 'content'
+  if (classes.contains('hiprint-paperNumber')) return 'content'
+  return 'other'
+}
+
+function rectangle(element, origin) {
+  const box = element.getBoundingClientRect()
+  return { element, left: box.left - origin.left, top: box.top - origin.top, width: box.width, height: box.height, right: box.right - origin.left, bottom: box.bottom - origin.top }
+}
+
+/** 根据实际 DOM 高度分行，允许同行文字高度不同；重叠不丢弃，顺序输出并警告。 */
+function groupRows(items, context) {
+  const rows = []
+  for (const item of items.sort((a, b) => a.top - b.top || a.left - b.left)) {
+    const row = rows[rows.length - 1]
+    const isSameBand = row && item.top < row.bottom - 1
+    const overlap = isSameBand && row.items.some(other => Math.min(other.right, item.right) - Math.max(other.left, item.left) > 1)
+    if (isSameBand && !overlap) {
+      row.items.push(item)
+      row.bottom = Math.max(row.bottom, item.bottom)
+    } else {
+      if (overlap) context.warn('overlap', '重叠组件已按阅读顺序排列，Word 不保留叠放关系', item.element, context.pageIndex)
+      rows.push({ top: item.top, bottom: item.bottom, items: [item] })
+    }
+  }
+  return rows
+}
+
+function spacer(px) {
+  return new Paragraph({ spacing: { before: 0, after: 0, line: Math.max(1, twip(px)), lineRule: 'exact' }, children: [new TextRun({ text: '', size: 1 })] })
+}
+
+async function content(item, context) {
+  const { element } = item
+  let type = item.type || elementType(element)
+  type = context.options.customTypeResolver?.(element, type) ?? type
+  const transform = styleOf(element).transform
+  if (transform && transform !== 'none') context.warn('transform', '组件变换不能完整映射到可编辑 Word 布局', element, context.pageIndex)
+  if (type === 'image' || type === 'other') {
+    if (type === 'other') context.warn('image-fallback', '未知组件以图片导出', element, context.pageIndex)
+    return [new Paragraph({ children: [await imageRun(element, context, item.width)], spacing: { before: 0, after: 0 } })]
+  }
+  if (type === 'hline') {
+    const border = borders(styleOf(element)).top
+    return [new Paragraph({ border: { bottom: border }, spacing: { before: 0, after: 0, line: 1 }, children: [new TextRun({ text: '', size: 1 })] })]
+  }
+  if (type === 'container') {
+    if (item.children?.length) return layout(item.children, item.width, context)
+    return [empty()]
+  }
+  if (type !== 'content') throw new Error(`不支持的 Word 组件类型：${type}`)
+  const contentRoot = item.type ? element : element.querySelector(
+    '.hiprint-printElement-longText-content,.hiprint-printElement-text-content,.hiprint-printElement-table-content,.hiprint-printElement-w2html-content,.hiprint-printElement-e2table-content'
+  ) || element
+  return htmlBlocks(contentRoot, context, item.width)
+}
+
+async function layout(items, width, context) {
+  const result = []
+  let previousBottom = 0
+  for (const row of groupRows(items, context)) {
+    if (row.top > previousBottom + 1) result.push(spacer(row.top - previousBottom))
+    const cells = []
+    const widths = []
+    let cursor = 0
+    for (const item of row.items.sort((a, b) => a.left - b.left)) {
+      if (item.left < -1 || item.right > width + 1) {
+        context.warn('out-of-bounds', '超出可用宽度的组件已限制到 Word 列宽', item.element, context.pageIndex)
+      }
+      if (item.left > cursor + 1) {
+        const gap = twip(item.left - cursor)
+        cells.push(new TableCell({ children: [empty()], borders: NO_BORDERS, width: { size: gap, type: WidthType.DXA } }))
+        widths.push(gap)
+      }
+      const available = Math.max(1, Math.min(item.width, width - Math.max(0, item.left)))
+      const cellWidth = twip(available)
+      const style = styleOf(item.element)
+      const children = await content({ ...item, width: available }, context)
+      if (item.top > row.top + 1) children.unshift(spacer(item.top - row.top))
+      cells.push(new TableCell({
+        children: finish(children),
+        width: { size: cellWidth, type: WidthType.DXA },
+        borders: borders(style),
+        margins: { top: 0, right: 0, bottom: 0, left: 0 },
+        shading: color(style.backgroundColor) ? { fill: color(style.backgroundColor) } : undefined,
+        verticalAlign: 'top'
+      }))
+      widths.push(cellWidth)
+      cursor = item.left + available
+    }
+    if (cursor < width - 1) {
+      const gap = twip(width - cursor)
+      cells.push(new TableCell({ children: [empty()], borders: NO_BORDERS, width: { size: gap, type: WidthType.DXA } }))
+      widths.push(gap)
+    }
+    result.push(new Table({
+      rows: [new TableRow({ children: cells })],
+      columnWidths: widths,
+      width: { size: twip(width), type: WidthType.DXA },
+      layout: TableLayoutType.FIXED,
+      borders: NO_BORDERS,
+      margins: { top: 0, bottom: 0, left: 0, right: 0 }
+    }))
+    // 不强制写入设计高度；后续行由 Word 按实际内容高度推动。
+    result.push(empty())
+    previousBottom = Math.max(previousBottom, row.bottom)
+  }
+  return finish(result)
+}
+
+export async function convertPage(page, context) {
+  const origin = page.element.getBoundingClientRect()
+  const elements = Array.from(page.element.querySelectorAll('.hiprint-printElement,.hiprint-paperNumber'))
+    .filter(element => !element.parentElement.closest('.hiprint-printElement') && visible(element))
+  const items = elements.map(element => rectangle(element, origin))
+    .filter(item => item.width > 0 && (item.height > 0 || elementType(item.element) === 'hline'))
+  // 当前 vgContainer 以矩形根组件和兄弟子组件输出，按实际包围范围重建布局。
+  const containers = items.filter(item => elementType(item.element) === 'container')
+  const parentOf = new Map()
+  for (const item of items) {
+    const parent = containers.filter(candidate => candidate !== item &&
+      candidate.width * candidate.height > item.width * item.height &&
+      item.left >= candidate.left - 1 && item.right <= candidate.right + 1 &&
+      item.top >= candidate.top - 1 && item.bottom <= candidate.bottom + 1)
+      .sort((a, b) => a.width * a.height - b.width * b.height)[0]
+    if (parent) parentOf.set(item, parent)
+  }
+  for (const [item, parent] of parentOf) {
+    parent.children ||= []
+    // 延后转换相对坐标，保证嵌套容器使用原始纸页坐标找父级。
+    parent.children.push(item)
+  }
+  const relative = parent => {
+    for (const child of parent.children || []) {
+      relative(child)
+      child.left -= parent.left
+      child.right -= parent.left
+      child.top -= parent.top
+      child.bottom -= parent.top
+    }
+  }
+  const roots = items.filter(item => !parentOf.has(item))
+  roots.forEach(relative)
+  const children = await layout(roots, page.width, context)
+  // 引擎生成的水印保留为背景图片，正文文字和表格仍然可以编辑。
+  const watermark = Array.from(page.element.querySelectorAll('[class]')).find(el =>
+    Array.from(el.classList).some(name => name.startsWith('__vm__'))
+  )
+  if (watermark && visible(watermark)) {
+    children.unshift(new Paragraph({
+      children: [await imageRun(watermark, context, page.width, {
+        horizontalPosition: { relative: 'page', offset: 0 },
+        verticalPosition: { relative: 'page', offset: 0 },
+        behindDocument: true,
+        allowOverlap: true
+      })],
+      spacing: { before: 0, after: 0, line: 1 }
+    }))
+  }
+  return children
+}

package/src/index.d.ts

@@ -0,0 +1,54 @@
+import type { Paragraph, Table } from 'docx'
+
+export type WordElementType = 'content' | 'container' | 'hline' | 'image' | 'other'
+export interface WordWarning {
+  code: 'overlap' | 'transform' | 'image-fallback' | 'html-layout' | 'out-of-bounds'
+  message: string
+  element: HTMLElement
+  /** 从 0 开始。 */
+  pageIndex: number
+}
+export interface PrintTemplateLike {
+  getHtml(printData: unknown, options?: Record<string, unknown>): unknown
+  ensureImages?(root: HTMLElement): unknown
+}
+export interface WordWriteContext {
+  template: PrintTemplateLike
+  printData: unknown
+  page: HTMLElement
+  pageIndex: number
+  paperCount: number
+  children: Array<Paragraph | Table>
+  options: WordOptions
+  warn(code: WordWarning['code'], message: string, element: HTMLElement, pageIndex: number): void
+}
+export interface WordOptions {
+  /** 默认 true；无论是否下载，都返回 DOCX Blob。 */
+  isDownload?: boolean
+  name?: string
+  title?: string
+  /** 默认 Microsoft YaHei；组件自身字体优先。 */
+  fontName?: string
+  /** pt，默认 10；组件自身字号优先。 */
+  fontSize?: number
+  /** 图片组件截图倍率，默认 2，不影响原生文字/表格。 */
+  pixelRatio?: number
+  /** 默认 true，按引擎页分节；false 用连续分节，由 Word 自动分页。 */
+  pageBreaks?: boolean
+  /** 传给 getHtml；applyPanelLayoutHtml 固定为 false。 */
+  renderOptions?: Record<string, unknown>
+  customTypeResolver?(element: HTMLElement, defaultType: WordElementType): WordElementType | undefined
+  /** 页内容转换完成的进度；文件压缩/下载发生在最后一次回调之后。 */
+  onProgress?(current: number, total: number): void
+  onWarning?(warning: WordWarning): void
+  onBeforeWrite?(context: WordWriteContext): Array<Paragraph | Table> | void | Promise<Array<Paragraph | Table> | void>
+}
+export interface WordPrintTemplate extends PrintTemplateLike {
+  toWord(printData: unknown, options?: WordOptions): Promise<Blob>
+}
+export interface WordPlugin {
+  name: string
+  install(hiprint: { PrintTemplate: { prototype: object } }): void
+}
+export default function pluginApiWord(defaultOptions?: WordOptions): WordPlugin
+export function exportWord(template: PrintTemplateLike, printData: unknown, options?: WordOptions): Promise<Blob>

package/src/index.js

@@ -0,0 +1,126 @@
+import { Document, Packer } from 'docx'
+import { renderPages } from './render.js'
+import { convertPage } from './convert.js'
+
+const INSTALLED = Symbol.for('@vg-print/plugin-api-word')
+const MIME = 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+
+/**
+ * 插件仅依赖 register 传入的 hiprint，不 import vg-print 或 Vue，
+ * 因而不会创建第二套打印引擎，也可供 Vue 2/3 使用方共享。
+ * 重复注册更新默认配置，不重复包装模板方法。
+ */
+export default function pluginApiWord(defaultOptions = {}) {
+  return {
+    name: '@vg-print/plugin-api-word',
+    install(hiprint) {
+      const prototype = hiprint?.PrintTemplate?.prototype
+      if (!prototype) throw new TypeError('Word 插件需要 hiprint.PrintTemplate')
+      if (prototype[INSTALLED]) {
+        prototype[INSTALLED].defaults = { ...defaultOptions }
+        return
+      }
+      if (prototype.toWord) throw new Error('PrintTemplate.toWord 已被其他插件占用')
+      const state = { defaults: { ...defaultOptions } }
+      Object.defineProperty(prototype, INSTALLED, { value: state })
+      Object.defineProperty(prototype, 'toWord', {
+        configurable: true,
+        writable: true,
+        value(printData, options = {}) {
+          return exportWord(this, printData, { ...state.defaults, ...options })
+        }
+      })
+    }
+  }
+}
+
+/**
+ * 独立 API 与模板方法使用相同链路；始终返回 Blob，下载只是额外副作用。
+ * 按模板串行执行，避免同一模板的 getHtml 临时状态在并发导出时相互覆盖。
+ */
+const queues = new WeakMap()
+export function exportWord(template, printData, options = {}) {
+  if (!template || typeof template.getHtml !== 'function') {
+    return Promise.reject(new TypeError('请传入具有 getHtml() 的打印模板实例'))
+  }
+  const previous = queues.get(template) || Promise.resolve()
+  const task = previous.catch(() => {}).then(() => writeWord(template, printData, options))
+  queues.set(template, task)
+  const cleanup = () => { if (queues.get(template) === task) queues.delete(template) }
+  task.then(cleanup, cleanup)
+  return task
+}
+
+async function writeWord(template, printData, options) {
+  const settings = {
+    fontName: 'Microsoft YaHei',
+    fontSize: 10,
+    isDownload: true,
+    pixelRatio: 2,
+    pageBreaks: true,
+    ...options
+  }
+  if (!(Number(settings.fontSize) > 0) || !(Number(settings.pixelRatio) > 0)) {
+    throw new RangeError('fontSize 和 pixelRatio 必须大于 0')
+  }
+  const warn = (code, message, element, pageIndex) => {
+    settings.onWarning?.({ code, message, element, pageIndex })
+  }
+  const { pages, dispose } = await renderPages(template, printData, settings)
+  try {
+    const sections = []
+    for (let pageIndex = 0; pageIndex < pages.length; pageIndex++) {
+      const page = pages[pageIndex]
+      const context = { options: settings, warn, pageIndex, template, printData }
+      let children = await convertPage(page, context)
+      const replacement = await settings.onBeforeWrite?.({
+        ...context, page: page.element, children, paperCount: pages.length
+      })
+      if (replacement !== undefined) {
+        if (!Array.isArray(replacement)) throw new TypeError('onBeforeWrite 应返回数组或 undefined')
+        children = replacement
+      }
+      sections.push({
+        properties: {
+          type: settings.pageBreaks ? 'nextPage' : 'continuous',
+          page: {
+            size: { width: Math.round(page.width * 15), height: Math.round(page.height * 15) },
+            margin: { top: 0, right: 0, bottom: 0, left: 0, header: 0, footer: 0 }
+          }
+        },
+        children
+      })
+      settings.onProgress?.(pageIndex + 1, pages.length)
+    }
+    const document = new Document({
+      creator: 'vg-print',
+      title: settings.title || 'vg-print Word export',
+      styles: {
+        default: {
+          document: {
+            run: { font: settings.fontName, size: Number(settings.fontSize) * 2 },
+            paragraph: { spacing: { before: 0, after: 0 } }
+          }
+        }
+      },
+      sections
+    })
+    const blob = new Blob([await Packer.toArrayBuffer(document)], { type: MIME })
+    if (settings.isDownload !== false) {
+      const name = String(settings.name || `vg-print-${Date.now()}.docx`).replace(/\.docx$/i, '') + '.docx'
+      const url = URL.createObjectURL(blob)
+      const anchor = window.document.createElement('a')
+      anchor.href = url
+      anchor.download = name
+      window.document.body.appendChild(anchor)
+      try { anchor.click() } finally {
+        anchor.remove()
+        // 下载启动后再回收 URL，避免浏览器尚未读取文件便被撤销。
+        setTimeout(() => URL.revokeObjectURL(url), 1000)
+      }
+    }
+    return blob
+  } finally {
+    dispose()
+  }
+}

package/src/render.js

@@ -0,0 +1,70 @@
+/**
+ * 使用引擎生成的 DOM，而不是重新执行模板 formatter/styler。
+ * 每次导出拥有自己的离屏容器，不使用引擎全局 removeTempContainer，
+ * 避免清除正在进行的 PDF/图片导出容器。
+ */
+export async function renderPages(template, printData, options) {
+  if (typeof document === 'undefined' || !document.body) {
+    throw new Error('Word 导出需要浏览器 DOM，请在页面挂载后调用')
+  }
+  const host = document.createElement('div')
+  host.setAttribute('aria-hidden', 'true')
+  host.style.cssText = 'position:fixed;left:-100000px;top:0;pointer-events:none;width:max-content;z-index:-1;'
+  document.body.appendChild(host)
+  const dispose = () => host.remove()
+  try {
+    const html = await template.getHtml(printData, {
+      ...(options.renderOptions || {}),
+      // 小标签拼版不会成为 Word 表格布局；按引擎原始纸页导出。
+      applyPanelLayoutHtml: false
+    })
+    if (typeof html === 'string') host.innerHTML = html
+    else if (html?.nodeType) host.appendChild(html)
+    else if (html && typeof html.length === 'number') {
+      Array.from(html).forEach(node => { if (node?.nodeType) host.appendChild(node) })
+    } else throw new Error('getHtml() 未返回可解析的 HTML')
+
+    // 取消预览缩放，保留组件内部缩放，以实际纸张尺寸测量。
+    host.querySelectorAll('.hiprint-printTemplate,.hiprint-printPanel,.hiprint-printPaper').forEach(el => {
+      el.style.transform = 'none'
+      el.style.zoom = '1'
+    })
+    if (document.fonts?.ready) await document.fonts.ready
+    if (typeof template.ensureImages === 'function') await template.ensureImages(host)
+    await Promise.all(Array.from(host.querySelectorAll('img')).map(image => {
+      if (image.complete) return Promise.resolve()
+      return new Promise(resolve => {
+        const done = () => {
+          clearTimeout(timer)
+          image.removeEventListener('load', done)
+          image.removeEventListener('error', done)
+          resolve()
+        }
+        const timer = setTimeout(done, 15000)
+        image.addEventListener('load', done, { once: true })
+        image.addEventListener('error', done, { once: true })
+      })
+    }))
+    // 给图表/图片组件一次提交 DOM 的机会，不启动应用或持续轮询。
+    await new Promise(resolve => requestAnimationFrame(() => resolve()))
+    const elements = Array.from(host.querySelectorAll('.hiprint-printPaper'))
+    if (!elements.length) throw new Error('没有可导出的打印纸页')
+    const pages = elements.map(element => {
+      const rect = element.getBoundingClientRect()
+      const originalHeight = Number(element.getAttribute('original-height'))
+      return {
+        element,
+        width: rect.width,
+        // 引擎纸页通常裁掉 1mm，Word 纸张使用原始高度。
+        height: originalHeight > 0 ? originalHeight * 96 / 25.4 : rect.height
+      }
+    })
+    if (pages.some(page => !(page.width > 0 && page.height > 0))) {
+      throw new Error('纸页尺寸无效，请确认已加载 vg-print/style.css')
+    }
+    return { pages, dispose }
+  } catch (error) {
+    dispose()
+    throw error
+  }
+}