docx-skill（DOCX 技能）

DOCX Skill v2.0

Overview

Complete Microsoft Word document processing using docx-js library for creation and XML manipulation for editing. A .docx file is a ZIP archive containing XML files.

Installation & Dependencies

Required

# For creating documents
npm install -g docx

# For text extraction
brew install pandoc

# For validation (optional)
pip install python-docx

Optional

# For PDF conversion
brew install --cask libreoffice

# For image processing
brew install imagemagick

Quick Start

Create Your First Document

const { Document, Packer, Paragraph, TextRun } = require('docx');

const doc = new Document({
  sections: [{
    children: [
      new Paragraph({
        children: [
          new TextRun({ text: "Hello World!", bold: true, size: 32 })
        ]
      })
    ]
  }]
});

await Packer.toBuffer(doc).then(buffer => {
  require('fs').writeFileSync("hello.docx", buffer);
});
console.log("✓ Document created!");

Read Document Content

# Extract text with pandoc
pandoc document.docx -o output.md

# Or with Python
python -c "from docx import Document; doc = Document('file.docx'); print('\
'.join([p.text for p in doc.paragraphs]))"

Complete API Reference

Document Structure

const { Document, Packer, Section } = require('docx');

const doc = new Document({
  sections: [{
    properties: {
      page: {
        size: { width: 12240, height: 15840 }, // US Letter (DXA units)
        margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } // 1 inch
      }
    },
    children: [/* paragraphs, tables, etc */]
  }]
});

Paragraphs

const { Paragraph, TextRun, PageBreak } = require('docx');

// Basic paragraph
new Paragraph({
  children: [new TextRun("Simple text")]
})

// Formatted paragraph
new Paragraph({
  children: [
    new TextRun({
      text: "Bold and ",
      bold: true,
      size: 28,  // 14pt (size is half-points)
      font: "Arial"
    }),
    new TextRun({
      text: "italic",
      italics: true,
      color: "FF0000"  // Red in hex
    })
  ],
  spacing: {
    before: 200,   // Space before paragraph
    after: 200,    // Space after paragraph
    line: 360      // Line height (1.5 = 360)
  },
  alignment: "center"  // left, center, right, justified
})

// Heading
new Paragraph({
  heading: "Heading1",
  children: [new TextRun("Chapter Title")]
})

// Page break
new Paragraph({
  children: [new PageBreak()]
})

Lists

const { LevelFormat } = require('docx');

// Configure numbering in document
const doc = new Document({
  numbering: {
    config: [
      {
        reference: "bullet-list",
        levels: [{
          level: 0,
          format: LevelFormat.BULLET,
          text: "•",
          alignment: "left",
          style: {
            paragraph: { indent: { left: 720, hanging: 360 } }
          }
        }]
      },
      {
        reference: "number-list",
        levels: [{
          level: 0,
          format: LevelFormat.DECIMAL,
          text: "%1.",
          alignment: "left",
          style: {
            paragraph: { indent: { left: 720, hanging: 360 } }
          }
        }]
      }
    ]
  },
  sections: [{
    children: [
      // Bullet list item
      new Paragraph({
        numbering: { reference: "bullet-list", level: 0 },
        children: [new TextRun("Bullet point")]
      }),
      // Numbered list item
      new Paragraph({
        numbering: { reference: "number-list", level: 0 },
        children: [new TextRun("Numbered item")]
      })
    ]
  }]
});

Tables

const { Table, TableRow, TableCell, WidthType, BorderStyle, ShadingType } = require('docx');

// Create table
new Table({
  width: { size: 9360, type: WidthType.DXA },  // Full content width
  columnWidths: [4680, 4680],  // Two equal columns
  
  rows: [
    // Header row
    new TableRow({
      children: [
        new TableCell({
          children: [new Paragraph({ children: [new TextRun("Header 1")] })],
          shading: { fill: "4472C4", type: ShadingType.SOLID },
          borders: {
            top: { style: BorderStyle.SINGLE, size: 1 },
            bottom: { style: BorderStyle.SINGLE, size: 1 },
            left: { style: BorderStyle.SINGLE, size: 1 },
            right: { style: BorderStyle.SINGLE, size: 1 }
          }
        }),
        new TableCell({
          children: [new Paragraph({ children: [new TextRun("Header 2")] })],
          shading: { fill: "4472C4", type: ShadingType.SOLID },
          borders: {
            top: { style: BorderStyle.SINGLE, size: 1 },
            bottom: { style: BorderStyle.SINGLE, size: 1 },
            left: { style: BorderStyle.SINGLE, size: 1 },
            right: { style: BorderStyle.SINGLE, size: 1 }
          }
        })
      ]
    }),
    // Data row
    new TableRow({
      children: [
        new TableCell({
          children: [new Paragraph({ children: [new TextRun("Data 1")] })],
          borders: {
            top: { style: BorderStyle.SINGLE, size: 1 },
            bottom: { style: BorderStyle.SINGLE, size: 1 },
            left: { style: BorderStyle.SINGLE, size: 1 },
            right: { style: BorderStyle.SINGLE, size: 1 }
          }
        }),
        new TableCell({
          children: [new Paragraph({ children: [new TextRun("Data 2")] })],
          borders: {
            top: { style: BorderStyle.SINGLE, size: 1 },
            bottom: { style: BorderStyle.SINGLE, size: 1 },
            left: { style: BorderStyle.SINGLE, size: 1 },
            right: { style: BorderStyle.SINGLE, size: 1 }
          }
        })
      ]
    })
  ]
})

Images

const { ImageRun } = require('docx');
const fs = require('fs');

new Paragraph({
  children: [
    new ImageRun({
      type: "png",  // Required: png, jpg, jpeg, gif, bmp, svg
      data: fs.readFileSync("image.png"),
      transformation: {
        width: 400,
        height: 300
      },
      altText: {
        title: "Image Title",
        description: "Image Description",
        name: "image-name"
      }
    })
  ]
})

Headers and Footers

const { Header, Footer, PageNumber } = require('docx');

const doc = new Document({
  sections: [{
    properties: {
      page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } }
    },
    headers: {
      default: new Header({
        children: [
          new Paragraph({
            children: [
              new TextRun({ text: "Document Header", bold: true })
            ],
            alignment: "center"
          })
        ]
      })
    },
    footers: {
      default: new Footer({
        children: [
          new Paragraph({
            children: [
              new TextRun("Page "),
              new TextRun({ children: [PageNumber.CURRENT] }),
              new TextRun(" of "),
              new TextRun({ children: [PageNumber.TOTAL_PAGES] })
            ],
            alignment: "center"
          })
        ]
      })
    },
    children: [/* content */]
  }]
});

Table of Contents

const { TableOfContents, HeadingLevel } = require('docx');

const doc = new Document({
  sections: [{
    children: [
      // TOC must come before headings
      new TableOfContents("Table of Contents", {
        hyperlink: true,
        headingStyleRange: "1-3"  // Include H1, H2, H3
      }),
      
      new Paragraph({ children: [new PageBreak()] }),
      
      // Headings for TOC
      new Paragraph({
        heading: HeadingLevel.HEADING_1,
        children: [new TextRun("Chapter 1")]
      }),
      new Paragraph({
        heading: HeadingLevel.HEADING_2,
        children: [new TextRun("Section 1.1")]
      })
    ]
  }]
});

Complete Examples

Example 1: Business Report

const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, HeadingLevel, TableOfContents, PageBreak, WidthType } = require('docx');
const fs = require('fs');

const doc = new Document({
  sections: [{
    properties: {
      page: {
        size: { width: 12240, height: 15840 },
        margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 }
      }
    },
    children: [
      // Title Page
      new Paragraph({
        children: [
          new TextRun({ text: "Annual Report 2024", bold: true, size: 48, font: "Arial" })
        ],
        spacing: { after: 400 },
        alignment: "center"
      }),
      new Paragraph({
        children: [new TextRun({ text: "Company Name", size: 24 })],
        alignment: "center"
      }),
      new Paragraph({ children: [new PageBreak()] }),
      
      // Table of Contents
      new TableOfContents("Contents", { headingStyleRange: "1-2" }),
      new Paragraph({ children: [new PageBreak()] }),
      
      // Executive Summary
      new Paragraph({
        heading: HeadingLevel.HEADING_1,
        children: [new TextRun("Executive Summary")]
      }),
      new Paragraph({
        children: [new TextRun("This report provides an overview of...")]
      }),
      
      // Financial Table
      new Paragraph({
        heading: HeadingLevel.HEADING_1,
        children: [new TextRun("Financial Summary")]
      }),
      new Table({
        width: { size: 9360, type: WidthType.DXA },
        columnWidths: [3120, 3120, 3120],
        rows: [
          new TableRow({
            children: [
              new TableCell({ children: [new Paragraph({ children: [new TextRun("Metric")] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("2023")] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("2024")] })] })
            ]
          }),
          new TableRow({
            children: [
              new TableCell({ children: [new Paragraph({ children: [new TextRun("Revenue")] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("$10M")] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("$12M")] })] })
            ]
          })
        ]
      })
    ]
  }]
});

Packer.toBuffer(doc).then(buffer => {
  fs.writeFileSync("annual-report.docx", buffer);
  console.log("✓ Report created!");
});

Example 2: Invoice Template

const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, WidthType, BorderStyle } = require('docx');
const fs = require('fs');

const doc = new Document({
  sections: [{
    children: [
      // Header
      new Paragraph({
        children: [new TextRun({ text: "INVOICE", bold: true, size: 36 })],
        alignment: "center",
        spacing: { after: 400 }
      }),
      
      // Invoice Details
      new Table({
        width: { size: 9360, type: WidthType.DXA },
        columnWidths: [4680, 4680],
        rows: [
          new TableRow({
            children: [
              new TableCell({
                children: [
                  new Paragraph({ children: [new TextRun({ text: "From:", bold: true })] }),
                  new Paragraph({ children: [new TextRun("Company Name")] }),
                  new Paragraph({ children: [new TextRun("123 Business St")] }),
                  new Paragraph({ children: [new TextRun("city@example.com")] })
                ]
              }),
              new TableCell({
                children: [
                  new Paragraph({ children: [new TextRun({ text: "To:", bold: true })] }),
                  new Paragraph({ children: [new TextRun("Client Name")] }),
                  new Paragraph({ children: [new TextRun("456 Client Ave")] }),
                  new Paragraph({ children: [new TextRun("client@example.com")] })
                ]
              })
            ]
          })
        ]
      }),
      
      new Paragraph({ children: [new TextRun("") ], spacing: { before: 200 } }),
      
      // Invoice Info
      new Table({
        width: { size: 9360, type: WidthType.DXA },
        columnWidths: [2340, 2340, 2340, 2340],
        rows: [
          new TableRow({
            children: [
              new TableCell({ children: [new Paragraph({ children: [new TextRun({ text: "Invoice #", bold: true })] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("INV-2024-001")] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun({ text: "Date", bold: true })] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("2024-01-15")] })] })
            ]
          })
        ]
      }),
      
      new Paragraph({ children: [new TextRun("") ], spacing: { before: 400 } }),
      
      // Items Table
      new Table({
        width: { size: 9360, type: WidthType.DXA },
        columnWidths: [4680, 2340, 2340],
        rows: [
          new TableRow({
            children: [
              new TableCell({ children: [new Paragraph({ children: [new TextRun({ text: "Description", bold: true })] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun({ text: "Qty", bold: true })] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun({ text: "Amount", bold: true })] })] })
            ]
          }),
          new TableRow({
            children: [
              new TableCell({ children: [new Paragraph({ children: [new TextRun("Web Development")] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("40")] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("$4,000")] })] })
            ]
          }),
          new TableRow({
            children: [
              new TableCell({ children: [new Paragraph({ children: [new TextRun("Design")] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("20")] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("$2,000")] })] })
            ]
          }),
          new TableRow({
            children: [
              new TableCell({ children: [] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun({ text: "Total:", bold: true })] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun({ text: "$6,000", bold: true })] })] })
            ]
          })
        ]
      })
    ]
  }]
});

Packer.toBuffer(doc).then(buffer => {
  fs.writeFileSync("invoice.docx", buffer);
  console.log("✓ Invoice created!");
});

Example 3: Resume/CV

const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, WidthType, HeadingLevel } = require('docx');
const fs = require('fs');

const doc = new Document({
  sections: [{
    properties: {
      page: {
        size: { width: 12240, height: 15840 },
        margin: { top: 1000, right: 1000, bottom: 1000, left: 1000 }
      }
    },
    children: [
      // Name and Contact
      new Paragraph({
        children: [new TextRun({ text: "JOHN DOE", bold: true, size: 36, font: "Arial" })],
        alignment: "center"
      }),
      new Paragraph({
        children: [new TextRun("john.doe@email.com | (555) 123-4567 | LinkedIn")],
        alignment: "center",
        spacing: { after: 300 }
      }),
      
      // Experience Section
      new Paragraph({
        heading: HeadingLevel.HEADING_1,
        children: [new TextRun("EXPERIENCE")]
      }),
      
      new Table({
        width: { size: 9360, type: WidthType.DXA },
        columnWidths: [2340, 7020],
        rows: [
          new TableRow({
            children: [
              new TableCell({
                children: [new Paragraph({ children: [new TextRun({ text: "2020 - Present", bold: true })] })]
              }),
              new TableCell({
                children: [
                  new Paragraph({ children: [new TextRun({ text: "Senior Developer", bold: true })] }),
                  new Paragraph({ children: [new TextRun("Company Name")] }),
                  new Paragraph({ children: [new TextRun("• Led development of...")] }),
                  new Paragraph({ children: [new TextRun("• Managed team of...")] })
                ]
              })
            ]
          })
        ]
      }),
      
      // Education Section
      new Paragraph({
        heading: HeadingLevel.HEADING_1,
        children: [new TextRun("EDUCATION")]
      }),
      new Paragraph({
        children: [
          new TextRun({ text: "Bachelor of Science in Computer Science", bold: true }),
          new TextRun(" | University Name | 2016-2020")
        ]
      }),
      
      // Skills Section
      new Paragraph({
        heading: HeadingLevel.HEADING_1,
        children: [new TextRun("SKILLS")]
      }),
      new Paragraph({
        children: [new TextRun("JavaScript, Python, React, Node.js, SQL, AWS, Docker, Git")]
      })
    ]
  }]
});

Packer.toBuffer(doc).then(buffer => {
  fs.writeFileSync("resume.docx", buffer);
  console.log("✓ Resume created!");
});

Editing Existing Documents

Method 1: Unpack → Edit → Repack

# Step 1: Unpack the document
python scripts/office/unpack.py document.docx unpacked/

# Step 2: Edit XML files in unpacked/word/
# Edit document.xml, styles.xml, etc.

# Step 3: Repack
python scripts/office/pack.py unpacked/ output.docx --original document.docx

Method 2: Using python-docx

from docx import Document

# Load existing document
doc = Document('existing.docx')

# Read paragraphs
for para in doc.paragraphs:
    print(para.text)

# Edit content
doc.paragraphs[0].text = "New first paragraph"

# Add new paragraph
doc.add_paragraph("New paragraph at end")

# Save
doc.save('edited.docx')

Method 3: Find and Replace

from docx import Document

def find_and_replace(doc_path, find_text, replace_text, output_path):
    doc = Document(doc_path)
    
    for para in doc.paragraphs:
        if find_text in para.text:
            para.text = para.text.replace(find_text, replace_text)
    
    for table in doc.tables:
        for row in table.rows:
            for cell in row.cells:
                if find_text in cell.text:
                    cell.text = cell.text.replace(find_text, replace_text)
    
    doc.save(output_path)

# Usage
find_and_replace('template.docx', '{{NAME}}', 'John Doe', 'output.docx')

Page Sizes Reference

All sizes in DXA units (1440 DXA = 1 inch):

Smart Quotes & Special Characters

Use XML entities for professional typography:

Error Handling

Common Errors

Error: "Font not found"

// Solution: Use web-safe fonts
new TextRun({ text: "Content", font: "Arial" })  // ✅ Safe
new TextRun({ text: "Content", font: "CustomFont" })  // ❌ May fail

Error: "Image not loading"

// Solution: Check file path and type
new ImageRun({
  type: "png",  // Must match actual file type
  data: fs.readFileSync("./images/logo.png"),  // Correct path
  transformation: { width: 200, height: 150 }
})

Error: "Table rendering incorrectly"

// Solution: Set both table width AND cell widths
new Table({
  width: { size: 9360, type: WidthType.DXA },  // Required
  columnWidths: [4680, 4680],  // Required, must sum to table width
  rows: [...]
})

Best Practices

1. Always Set Page Size Explicitly

// docx-js defaults to A4
properties: {
  page: {
    size: { width: 12240, height: 15840 }  // US Letter
  }
}

2. Use Styles Consistently

const doc = new Document({
  styles: {
    default: {
      document: {
        run: { font: "Arial", size: 24 }  // 12pt default
      }
    }
  }
});

3. Never Use Unicode Bullets

// ❌ WRONG
new Paragraph({ children: [new TextRun("• Item")] })

// ✅ CORRECT
new Paragraph({
  numbering: { reference: "bullets", level: 0 },
  children: [new TextRun("Item")]
})

4. Validate Before Distribution

# Check document integrity
python scripts/office/validate.py document.docx

# Or with pandoc
pandoc document.docx -o /dev/null && echo "✓ Valid"

Testing Your Setup

// test-docx.js
const { Document, Packer, Paragraph, TextRun } = require('docx');
const fs = require('fs');

async function test() {
  console.log("Testing docx setup...");
  
  const doc = new Document({
    sections: [{
      children: [
        new Paragraph({
          children: [new TextRun("Test document created successfully!")]
        })
      ]
    }]
  });
  
  await Packer.toBuffer(doc).then(buffer => {
    fs.writeFileSync("test-output.docx", buffer);
  });
  
  console.log("✓ Test passed! Check test-output.docx");
}

test().catch(console.error);

Run test:

node test-docx.js

License

MIT License - See LICENSE file for details.