DOCX

DOCX - Word 文档处理 (重构版)

路径参数说明

重要：所有工具的 path 参数遵循以下规则（与 FS 技能一致）：

• 相对路径直接使用，依赖 VM 设置的工作目录
• 绝对路径不被允许

示例：

// 相对路径（推荐）
read({ path: 'input/document.docx', scope: 'text' })
read({ path: 'data/output.docx', scope: 'text' })

工具列表

read - 读取文档

scope 参数

示例

// 读取文档信息
read({ path: 'document.docx', scope: 'info' })
// 返回: { metadata, paragraphCount, characterCount, wordCount, hasHeader, hasFooter }

// 提取文本
read({ path: 'document.docx', scope: 'text' })
read({ path: 'document.docx', scope: 'text', includeFormatting: true })  // 返回 HTML

// 提取段落/表格/批注
read({ path: 'document.docx', scope: 'paragraphs' })
read({ path: 'document.docx', scope: 'tables' })
read({ path: 'document.docx', scope: 'comments' })

// 提取图片信息
read({ path: 'document.docx', scope: 'images' })
// 返回: { imageCount, images: [{ path, fileName, extension, size }] }

// 提取页眉页脚
read({ path: 'document.docx', scope: 'headers' })
read({ path: 'document.docx', scope: 'footers' })

write - 写入文档

参数

页眉配置

header: {
  text: 'Document Header',
  alignment: 'CENTER'  // LEFT, CENTER, RIGHT
}

页脚配置

footer: {
  text: 'Company Name',
  pageNumber: true,
  pagePrefix: 'Page ',
  pageSuffix: '',
  pageAlignment: 'CENTER'
}

示例

// 从数据创建（带页眉页脚）
write({
  path: 'output.docx',
  source: 'data',
  title: 'Report Title',
  header: { text: 'Company Report', alignment: 'CENTER' },
  footer: { pageNumber: true, pagePrefix: 'Page ' },
  content: [
    { type: 'heading', text: 'Introduction', level: 1 },
    { type: 'paragraph', text: 'This is the content.' },
    { type: 'paragraph', text: 'Bold text', runs: [{ text: 'Bold', bold: true }] },
    { type: 'list', items: ['Item 1', 'Item 2'] },
    { type: 'table', headers: ['Name', 'Value'], rows: [['A', '1']] }
  ]
})

// 从 Markdown 创建
write({
  path: 'output.docx',
  source: 'markdown',
  markdown: '# Title\n\nParagraph with **bold** text.\n\n- Item 1\n- Item 2',
  header: { text: 'Header' },
  footer: { pageNumber: true }
})

// 多节文档
write({
  path: 'output.docx',
  sections: [
    { 
      content: [{ type: 'heading', text: 'Section 1', level: 1 }],
      header: { text: 'Section 1 Header' }
    },
    { 
      content: [{ type: 'heading', text: 'Section 2', level: 1 }],
      header: { text: 'Section 2 Header' }
    }
  ]
})

patch - 模板填充（核心功能）

重要：使用 Patcher API，保留原文档样式！

参数

模板文档准备

在 Word 文档中使用 {{placeholder}} 格式的占位符：

姓名：{{name}}
日期：{{date}}
金额：{{amount}}

示例

// 简单文本替换
patch({
  path: 'template.docx',
  patches: {
    name: '张三',
    date: '2024-01-15',
    amount: '¥1,000.00'
  },
  output: 'output.docx'
})

// 复杂替换（段落样式）
patch({
  path: 'template.docx',
  patches: {
    title: {
      type: 'paragraph',
      children: [{ text: '新标题', bold: true, size: 28 }]
    }
  }
})

// 自定义分隔符
patch({
  path: 'template.docx',
  patches: { name: 'John' },
  delimiters: { start: '[[', end: ']]' }
})

edit - 编辑文档

推荐使用 patch 工具进行编辑，可保留原文档样式

action 参数

示例

// 替换占位符（保留格式）
edit({
  path: 'document.docx',
  action: 'replace',
  replacements: {
    title: '新标题',
    author: '张三'
  }
})

// 在占位符处插入内容
edit({
  path: 'document.docx',
  action: 'insert',
  placeholder: 'content_here',
  text: '这是新插入的内容'
})

// 添加段落到末尾
edit({
  path: 'document.docx',
  action: 'append',
  text: '新段落'
})

// 删除占位符内容
edit({
  path: 'document.docx',
  action: 'delete',
  placeholder: 'remove_this'
})

convert - 格式转换

示例

// 转 Markdown
convert({ path: 'document.docx', format: 'markdown' })
convert({ path: 'document.docx', format: 'markdown', output: 'document.md' })

// 转 HTML
convert({ path: 'document.docx', format: 'html' })
convert({ path: 'document.docx', format: 'html', output: 'document.html', includeStyles: true })

image - 图片操作

action 参数

示例

// 列出图片
image({ path: 'document.docx', action: 'list' })

// 提取图片
image({ path: 'document.docx', action: 'extract', outputDir: './images' })

// 在占位符处插入图片（保留格式）
image({
  path: 'document.docx',
  action: 'insert',
  placeholder: 'image_here',
  imagePath: 'chart.png',
  width: 500,
  height: 300
})

// 插入图片到末尾（可能丢失格式）
image({
  path: 'document.docx',
  action: 'insert',
  imagePath: 'chart.png',
  width: 500,
  height: 300
})

link - 超链接操作

action 参数

示例

// 列出超链接
link({ path: 'document.docx', action: 'list' })

// 在占位符处添加超链接
link({
  path: 'document.docx',
  action: 'add',
  placeholder: 'link_here',
  url: 'https://example.com',
  text: '点击访问'
})

toc - 目录操作

action 参数

示例

// 在占位符处插入目录
toc({
  path: 'document.docx',
  action: 'insert',
  placeholder: 'toc_here'
})

// 更新目录提示
toc({ path: 'document.docx', action: 'update' })
// 返回提示：需要在 Word 中手动更新目录（F9）

最佳实践

1. 模板填充优先

使用 patch 工具进行模板填充，可保留原文档的所有样式：

// 推荐：使用模板填充
patch({ path: 'template.docx', patches: { name: '张三' } })

// 不推荐：直接编辑（可能丢失格式）
edit({ path: 'document.docx', action: 'append', text: '新内容' })

2. 占位符命名规范

• 使用清晰的命名：{{customer_name}}、{{invoice_date}}
• 避免特殊字符：仅使用字母、数字、下划线
• 模板中占位符前后留空格：姓名：{{ name }}

3. 页眉页脚设置

创建专业文档时添加页眉页脚：

write({
  path: 'report.docx',
  header: { text: '公司报告', alignment: 'CENTER' },
  footer: { pageNumber: true, pagePrefix: '第 ', pageSuffix: ' 页' },
  content: [...]
})

注意事项

• 模板填充：使用 patch 工具可保留原文档样式
• 占位符格式：默认 {{placeholder}}，可自定义分隔符
• 目录更新：插入目录后需在 Word 中手动更新（F9）
• 图片插入：推荐使用占位符方式，可保留格式