# JSON DOCX

> 将 JSON 数据转换为 Word 文档(.docx)的技能。支持标题、段落、列表、表格、图片、分页符等多种内容类型，适用于生成报告、合同、发票、简历等文档。触发时机：用户请求将 JSON 转换为 Word 文档时。

- Skill: `dxy-hub/json-docx` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add dxy-hub/json-docx`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dxy-hub/json-docx/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: dxy-hub (https://skillmd.com/u/dxy-hub)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dxy-hub/json-docx

---


# JSON to DOCX 转换技能

## Overview

本技能用于将结构化的 JSON 数据转换为 Word 文档(.docx)格式，支持丰富的文档元素和格式选项。

---

## 触发条件

当用户输入中包含以下任一表达时触发本技能：

- `把 json 转换为 docx`
- `json 转换为 word`
- `生成 word 文档`（且提供 JSON 数据）
- `创建 docx 文件`（且提供 JSON 数据）
- `json to docx`
- 提供需要转换为 Word 文档的 JSON 数据

---

## 工作流程

### 第一步：检查 JSON 数据格式

确认用户提供的 JSON 数据是否符合本技能支持的格式。如果格式不符，提示用户提供正确格式的 JSON。

#### 基本结构

```json
{
  "title": "文档标题",
  "author": "作者名称",
  "subject": "文档主题",
  "description": "文档描述",
  "content": [
    // 内容元素数组
  ]
}
```

### 第二步：选择转换方式

本技能提供两种实现方式：

- **Python 版本**：使用 `python-docx` 库，更稳定，依赖更少
- **Node.js 版本**：使用 `docx` 库，功能更丰富

根据用户环境和偏好选择合适的方式。

### 第三步：执行转换

使用对应的脚本执行转换：

**Python 版本**：
```bash
python json_to_docx.py input.json output.docx
```

**Node.js 版本**：
```bash
node json-to-docx.js input.json output.docx
# 或使用
npm run convert input.json output.docx
```

### 第四步：验证输出

确认 `.docx` 文件已成功生成，检查文件内容是否符合预期。

---

## 支持的内容类型

### 1. 标题 (heading)

```json
{
  "type": "heading",
  "level": 1,
  "text": "一级标题"
}
```

- `level`: 1-6，表示标题级别

### 2. 段落 (paragraph)

```json
{
  "type": "paragraph",
  "text": "段落文本内容",
  "align": "left"
}
```

- `align`: left, center, right, justify（对齐方式）

### 3. 文本 (text)

```json
{
  "type": "text",
  "text": "文本内容",
  "bold": true,
  "italics": true,
  "underline": true,
  "color": "FF0000",
  "size": 14,
  "font": "Arial"
}
```

- `bold`: 粗体
- `italics`: 斜体
- `underline`: 下划线
- `color`: 十六进制颜色值（如 "FF0000" 红色）
- `size`: 字体大小（磅）
- `font`: 字体名称
- `highlight`: 高亮颜色（如 "yellow"）

### 4. 项目符号列表 (bullet)

```json
{
  "type": "bullet",
  "items": ["项目1", "项目2", "项目3"]
}
```

### 5. 编号列表 (numbered)

```json
{
  "type": "numbered",
  "items": ["项目1", "项目2", "项目3"]
}
```

### 6. 表格 (table)

```json
{
  "type": "table",
  "headers": ["列1", "列2", "列3"],
  "rows": [
    ["数据1", "数据2", "数据3"],
    ["数据4", "数据5", "数据6"]
  ]
}
```

### 7. 图片 (image)

```json
{
  "type": "image",
  "path": "image.png",
  "width": 300,
  "height": 200,
  "align": "center"
}
```

- `path`: 图片文件路径（支持相对路径）
- `width`: 宽度（像素）
- `height`: 高度（像素）
- `align`: left, center, right

### 8. 分页符 (pagebreak)

```json
{
  "type": "pagebreak"
}
```

### 9. 空白分隔符 (spacer)

```json
{
  "type": "spacer",
  "size": 400
}
```

- `size`: 空白大小（单位取决于实现）

### 10. 水平线 (line)

```json
{
  "type": "line"
}
```

---

## 安装依赖

### Python 版本

```bash
pip install python-docx
```

### Node.js 版本

```bash
npm install
```

---

## 常见应用场景

### 1. 生成报告模板

```json
{
  "title": "月度报告",
  "content": [
    {"type": "heading", "level": 1, "text": "执行摘要"},
    {"type": "paragraph", "text": "本报告总结了本月的主要成就..."},
    {"type": "heading", "level": 2, "text": "关键指标"},
    {"type": "table", "headers": ["指标", "本月", "上月", "变化"],
      "rows": [
        ["收入", "100万", "90万", "+11%"],
        ["用户数", "1000", "900", "+11%"]
      ]}
  ]
}
```

### 2. 生成合同文档

```json
{
  "title": "服务合同",
  "content": [
    {"type": "heading", "level": 1, "text": "服务协议"},
    {"type": "paragraph", "text": "甲方：[公司名称]"},
    {"type": "paragraph", "text": "乙方：[服务提供商]"},
    {"type": "heading", "level": 2, "text": "第一条 服务内容"},
    {"type": "numbered", "items": [
      "提供技术咨询服务",
      "提供系统维护服务",
      "提供培训服务"
    ]}
  ]
}
```

### 3. 生成发票

```json
{
  "title": "发票",
  "content": [
    {"type": "paragraph", "text": "发票号码：INV-2024-001", "align": "right"},
    {"type": "paragraph", "text": "日期：2024-03-18", "align": "right"},
    {"type": "spacer", "size": 400},
    {"type": "paragraph", "text": "收件人：", "bold": true},
    {"type": "paragraph", "text": "客户公司名称"},
    {"type": "heading", "level": 2, "text": "项目明细"},
    {"type": "table", "headers": ["项目", "数量", "单价", "金额"],
      "rows": [
        ["服务费", "1", "1000", "1000"],
        ["税费", "1", "100", "100"]
      ]}
  ]
}
```

### 4. 生成简历

```json
{
  "title": "个人简历",
  "content": [
    {"type": "heading", "level": 1, "text": "张三"},
    {"type": "paragraph", "text": "邮箱：example@email.com | 电话：138-0000-0000"},
    {"type": "heading", "level": 2, "text": "工作经历"},
    {"type": "heading", "level": 3, "text": "ABC 公司 - 软件工程师"},
    {"type": "paragraph", "text": "2020年1月 - 至今"},
    {"type": "bullet", "items": [
      "负责系统架构设计",
      "参与核心功能开发",
      "指导初级工程师"
    ]}
  ]
}
```

---

## 版本选择建议

- **Python 版本**: 更稳定，依赖更少，适合服务器环境
- **Node.js 版本**: 功能更丰富，支持更多格式选项，适合前端/Node.js 项目

---

## 常见问题

### 1. 中文显示问题

如果中文显示不正常，请确保 JSON 文件使用 UTF-8 编码保存。

### 2. 图片路径问题

- 使用相对路径时，图片路径应相对于 JSON 文件所在目录
- 建议使用绝对路径或将图片与 JSON 文件放在同一目录

### 3. 表格格式

表格的 headers 和 rows 数组长度必须一致，否则可能导致格式错误。

---

## File Structure

```
~/.openclaw/skills/json-docx/
├── SKILL.md              # 本文件
├── README.md             # 使用说明
├── ADVANCED.md           # 高级功能指南
├── json_to_docx.py       # Python 版本转换脚本
├── json-to-docx.js       # Node.js 版本转换脚本
├── example.json          # 示例 JSON 数据
└── package.json          # Node.js 依赖配置
```

---

## Maintenance

- 技能版本：v1.0
- 创建日期：2026-03-18
- 许可证：MIT License