docx

name	docx
description	Word 文档处理。用于读取、写入、编辑、模板填充 .docx 文件。支持页眉页脚、超链接、目录、图片操作。使用 Patcher API 保留原文档样式。当用户需要操作 Word 文档时触发。

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

路径参数说明

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

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

示例：

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

工具列表

工具	说明	关键参数
read	读取文档	scope: info/text/paragraphs/tables/comments/images/headers/footers
write	写入文档	source: data/markdown，支持 header/footer
patch	模板填充	patches: { placeholder: value }，保留原文档样式
edit	编辑文档	action: replace/append/insert/delete
convert	格式转换	format: markdown/html
image	图片操作	action: extract/insert/list
link	超链接操作	action: add/list
toc	目录操作	action: insert/update

---

read - 读取文档

scope 参数

scope	说明	返回内容
info	文档信息	元数据、段落数、字数、是否有页眉页脚
text	提取文本	纯文本或 HTML（includeFormatting: true）
paragraphs	提取段落	段落列表（可选样式）
tables	提取表格	表格数据数组
comments	提取批注	批注列表
images	提取图片信息	图片列表（路径、大小）
headers	提取页眉	页眉内容
footers	提取页脚	页脚内容

示例

// 读取文档信息
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 - 写入文档

参数

参数	类型	说明
path	string	输出文件路径
source	string	数据来源：data 或 markdown
content	array	内容数据（source 为 data）
markdown	string	Markdown 内容（source 为 markdown）
title	string	文档标题
properties	object	文档属性（author, subject, keywords）
header	object	页眉配置
footer	object	页脚配置
sections	array	多节配置

页眉配置

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，保留原文档样式！

参数

参数	类型	说明
path	string	模板文件路径
patches	object	替换数据 { placeholder: value }
output	string	输出文件路径（可选，默认覆盖原文件）
keepOriginalStyles	boolean	保留原文档样式（默认 true）
delimiters	object	占位符分隔符（默认 { start: '{{', end: '}}' }）

模板文档准备

在 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 参数

action	说明	关键参数
replace	替换占位符	replacements: { placeholder: value }
append	添加段落	text: 内容
insert	插入段落	text: 内容，placeholder: 占位符
delete	删除内容	placeholder: 占位符

示例

// 替换占位符（保留格式）
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 参数

action	说明	关键参数
list	列出图片	无额外参数
extract	提取图片	outputDir: 输出目录
insert	插入图片	imagePath: 图片路径，placeholder: 占位符

示例

// 列出图片
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 参数

action	说明	关键参数
list	列出超链接	无额外参数
add	添加超链接	placeholder: 占位符，url: 链接，text: 显示文本

示例

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

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

---

toc - 目录操作

action 参数

action	说明	关键参数
insert	插入目录	placeholder: 占位符
update	更新目录提示	无额外参数

示例

// 在占位符处插入目录
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）
• 图片插入：推荐使用占位符方式，可保留格式