@vg-print/plugin-api-word 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## 0.1.0 — 2026-11-06
 
+- 默认用背景同色细实线遮盖布局表格及无边框单元格的编辑网格线，保留模板真实边框和可编辑内容；补充显示效果限制。
+- 核对 Vue 2 / Vue 3 的注册接口与打印核心，确认同一插件通过宿主注入即可共用；补充 `vg-print-vue2` 注册示例与工具链支持范围。
+- 核对布局表格的无边框设置，补充 Word/WPS 编辑网格线和实际打印边框的区别及隐藏方法。
 - 新增 `hiprint.register({ plugins: [pluginApiWord()] })` 注入与 `template.toWord()` 方法。
 - 新增独立 `exportWord()` API，支持下载和返回 DOCX Blob。
 - 基于引擎渲染 DOM 转换原生段落、表格、横纵合并及并排布局；图表/条码等局部图片化。

package/README.md

@@ -37,6 +37,27 @@ const blob = await template.toWord(printData, {
 
 必须传入模板实例，原始模板 JSON 请先使用 `createTemplate()` 构造。插件注册前后创建的实例共享同一原型；重复注册只更新默认配置。
 
+## Vue 2 / Vue 3 兼容
+
+同一个插件包可用于 Vue 3 的 `vg-print` 和 Vue 2 的 `vg-print-vue2`。插件只使用注册入口传入的 `hiprint.PrintTemplate.prototype` 和模板的 `getHtml()`，没有 Vue 依赖，也不会自行导入任一版本的打印引擎。两个项目当前的打印核心源码一致，注册接口、纸页 DOM 和图片预处理接口也一致。
+
+Vue 3 使用上面的示例。Vue 2 使用其对应的打印包注册，插件用法相同：
+
+```js
+import { hiprint, createTemplate } from 'vg-print-vue2'
+import 'vg-print-vue2/style.css'
+import pluginApiWord from '@vg-print/plugin-api-word'
+
+// 可放在异步初始化函数中，无需使用 Vue.use()。
+async function exportReport(templateJson, printData) {
+  await hiprint.register({ plugins: [pluginApiWord()] })
+  const template = createTemplate(templateJson)
+  return template.toWord(printData, { name: '报告.docx' })
+}
+```
+
+独立 `exportWord()` API 同样适用于两种模板实例，不依赖设计器是否提供 Word 按钮。当前 Vue 2 项目的 Vite 4 工具链支持本包的 ESM 入口；其他旧工具链需要自行配置依赖转译。Vue 2 兼容不代表支持 CommonJS `require` 或 IE 浏览器。
+
 也可以不注册，直接使用独立 API：
 
 ```js
@@ -100,11 +121,21 @@ const blob = await wordTemplate.toWord(printData, { isDownload: false })
 - 读取 `getHtml()` 渲染后的页面，复用字段绑定、格式化、内容隐藏和引擎分页结果。
 - 普通文本、长文本保留可编辑内容、基本字体样式、显式换行和对齐。
 - 动态/静态表格、e2table、w2html 中的 HTML 表格转换为原生 Word 表格，支持列宽、横纵合并、边框、背景和表头。
-- 并排组件用无边框表格布局；矩形容器按实际包围范围分组，内容编辑后自然撑高。装饰矩形包围其他内容时也会按容器处理。
+- 并排组件用视觉无边框的表格布局；矩形容器按实际包围范围分组，内容编辑后自然撑高。装饰矩形包围其他内容时也会按容器处理。
 - 长文本标题与正文的横向布局转换为双列表格。
 - 图片、条码、二维码、图表、竖线、椭圆作为图片；内部文字和图表数据不可原生编辑。
 - 渲染 DOM 已包含的水印保留为背景图片；编辑型 Word 不是防篡改文件。
 
+### Word/WPS 中的灰色虚线
+
+并排布局、组件定位和标题/正文对齐使用原生 Word 表格。仅设置“无边框”时，Word/WPS 开启“查看网格线”仍会显示灰色虚线。
+
+插件默认在没有模板边框的位置写入与背景同色的 0.5pt 实线，以遮住灰色网格线。白色纸面使用白色实线，有纯色背景的单元格使用其背景色，文字和表格仍可编辑。这是视觉遮盖，不是修改接收方的网格线设置；更改文档背景、使用非纯色背景或编辑器特殊显示模式时可能看到这些同色边框，具体效果仍需在 Word/WPS 中验证。
+
+模板本身的横线、矩形边框和表格单元格边框仍会保留。选中表格时的移动柄、插入行列的“＋”按钮属于编辑器交互控件，退出表格编辑状态后隐藏，插件不能移除。
+
+若特定编辑器仍显示辅助线，可在 Word 的“表格布局（或表格工具 → 布局）”中关闭“查看网格线”；WPS 可在“表格工具”中查找对应选项。
+
 不保证任意模板与预览逐像素一致。Word/WPS 的字体度量、行距、自动换行和分页与浏览器不同；自由重叠、旋转文字、复杂 CSS、混合定位和复杂列表不保证还原。未知组件使用图片回退，重叠组件按阅读顺序输出并报告警告。
 
 常规报告/规整表单更适合导出；不使用固定行高截断长文本。页眉页脚和页码来自引擎每页的渲染内容，作为每节正文输出，不转换为自动更新的 Word 页码域或原生重复页眉页脚。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vg-print/plugin-api-word",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Editable DOCX export plugin for vg-print, installed through hiprint.register.",
   "type": "module",
   "license": "MIT",

package/src/convert.js

@@ -9,7 +9,6 @@ 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 单元格和文档结尾需要段落，嵌套表格后补一个极小空段落。
@@ -41,6 +40,33 @@ function borders(style) {
   }))
 }
 
+/**
+ * 网格线属于编辑器本机设置，DOCX 不能强制关闭。
+ * 用与纸面/单元格背景同色的 0.5pt 实线覆盖无边框处的灰色网格线。
+ * 保留模板明确设置的边框；不将文字截图，也不改变组件列宽。
+ */
+function concealedBorders(background = 'FFFFFF') {
+  const edge = { style: BorderStyle.SINGLE, size: 4, color: background }
+  return { top: edge, bottom: edge, left: edge, right: edge, insideHorizontal: edge, insideVertical: edge }
+}
+
+function backgroundOf(element) {
+  for (let node = element; node; node = node.parentElement) {
+    const background = color(styleOf(node).backgroundColor)
+    if (background) return background
+    // 纸页外的应用主题不是 Word 纸面颜色，透明纸面按白色处理。
+    if (node.classList.contains('hiprint-printPaper')) break
+  }
+  return 'FFFFFF'
+}
+
+function cellBorders(element) {
+  const fallback = concealedBorders(backgroundOf(element))
+  return Object.fromEntries(Object.entries(borders(styleOf(element))).map(([side, border]) =>
+    [side, border.style === BorderStyle.NONE ? fallback[side] : border]
+  ))
+}
+
 function visible(element) {
   const style = styleOf(element)
   return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0'
@@ -121,7 +147,7 @@ async function htmlBlocks(root, context, maxWidth) {
     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)
+    if (horizontal) return layout(items, Math.min(origin.width || maxWidth, maxWidth), context, backgroundOf(root))
     context.warn('html-layout', '富文本复杂定位已按阅读顺序转换', root, context.pageIndex)
   }
   const output = []
@@ -180,8 +206,8 @@ async function htmlBlocks(root, context, maxWidth) {
 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
+    rows: [new TableRow({ children: [new TableCell({ children: [empty()], borders: concealedBorders(backgroundOf(table)) })] })],
+    borders: concealedBorders(backgroundOf(table))
   })
   const occupied = []
   const placements = rows.map((row, rowIndex) => {
@@ -234,7 +260,7 @@ async function htmlTable(table, context, maxWidth) {
         columnSpan: colSpan,
         rowSpan,
         width: { size: cellWidth, type: WidthType.DXA },
-        borders: borders(style),
+        borders: cellBorders(cell),
         margins: {
           top: twip(number(style.paddingTop)), bottom: twip(number(style.paddingBottom)),
           left: twip(number(style.paddingLeft)), right: twip(number(style.paddingRight))
@@ -249,7 +275,7 @@ async function htmlTable(table, context, maxWidth) {
       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 })
+  return new Table({ rows: result, width: { size: twip(width), type: WidthType.DXA }, columnWidths: widths, layout: TableLayoutType.FIXED, borders: concealedBorders(backgroundOf(table)) })
 }
 
 function elementType(element) {
@@ -304,7 +330,7 @@ async function content(item, context) {
     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)
+    if (item.children?.length) return layout(item.children, item.width, context, backgroundOf(element))
     return [empty()]
   }
   if (type !== 'content') throw new Error(`不支持的 Word 组件类型：${type}`)
@@ -314,8 +340,9 @@ async function content(item, context) {
   return htmlBlocks(contentRoot, context, item.width)
 }
 
-async function layout(items, width, context) {
+async function layout(items, width, context, background = 'FFFFFF') {
   const result = []
+  const layoutBorders = concealedBorders(background)
   let previousBottom = 0
   for (const row of groupRows(items, context)) {
     if (row.top > previousBottom + 1) result.push(spacer(row.top - previousBottom))
@@ -328,7 +355,7 @@ async function layout(items, width, context) {
       }
       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 } }))
+        cells.push(new TableCell({ children: [empty()], borders: layoutBorders, width: { size: gap, type: WidthType.DXA } }))
         widths.push(gap)
       }
       const available = Math.max(1, Math.min(item.width, width - Math.max(0, item.left)))
@@ -339,7 +366,7 @@ async function layout(items, width, context) {
       cells.push(new TableCell({
         children: finish(children),
         width: { size: cellWidth, type: WidthType.DXA },
-        borders: borders(style),
+        borders: cellBorders(item.element),
         margins: { top: 0, right: 0, bottom: 0, left: 0 },
         shading: color(style.backgroundColor) ? { fill: color(style.backgroundColor) } : undefined,
         verticalAlign: 'top'
@@ -349,7 +376,7 @@ async function layout(items, width, context) {
     }
     if (cursor < width - 1) {
       const gap = twip(width - cursor)
-      cells.push(new TableCell({ children: [empty()], borders: NO_BORDERS, width: { size: gap, type: WidthType.DXA } }))
+      cells.push(new TableCell({ children: [empty()], borders: layoutBorders, width: { size: gap, type: WidthType.DXA } }))
       widths.push(gap)
     }
     result.push(new Table({
@@ -357,7 +384,7 @@ async function layout(items, width, context) {
       columnWidths: widths,
       width: { size: twip(width), type: WidthType.DXA },
       layout: TableLayoutType.FIXED,
-      borders: NO_BORDERS,
+      borders: layoutBorders,
       margins: { top: 0, bottom: 0, left: 0, right: 0 }
     }))
     // 不强制写入设计高度；后续行由 Word 按实际内容高度推动。
@@ -400,7 +427,7 @@ export async function convertPage(page, context) {
   }
   const roots = items.filter(item => !parentOf.has(item))
   roots.forEach(relative)
-  const children = await layout(roots, page.width, context)
+  const children = await layout(roots, page.width, context, backgroundOf(page.element))
   // 引擎生成的水印保留为背景图片，正文文字和表格仍然可以编辑。
   const watermark = Array.from(page.element.querySelectorAll('[class]')).find(el =>
     Array.from(el.classList).some(name => name.startsWith('__vm__'))