---
name: docx
description: "Criação, edição e análise de documentos Word (.docx). Versão light para heartbeats."
---

# DOCX — Referência Rápida

## Referência rápida

| Tarefa | Abordagem |
|--------|-----------|
| Ler conteúdo | `pandoc` ou descompactar XML |
| Criar novo | `docx-js` (npm install -g docx) |
| Editar existente | Descompactar → editar XML → recompactar |
| Converter .doc | `python scripts/office/soffice.py --headless --convert-to docx doc.doc` |

## Criar novos documentos (docx-js)

### Setup básico

```javascript
const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, ImageRun,
        Header, Footer, AlignmentType, PageOrientation, LevelFormat, HeadingLevel,
        BorderStyle, WidthType, ShadingType, PageNumber, PageBreak } = require('docx');

const doc = new Document({ sections: [{ children: [/* conteúdo */] }] });
Packer.toBuffer(doc).then(buffer => fs.writeFileSync("doc.docx", buffer));
```

### Tamanho de página (A4)

```javascript
sections: [{
  properties: {
    page: {
      size: { width: 11906, height: 16838 },  // A4 em DXA
      margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 }
    }
  },
  children: [/* conteúdo */]
}]
```

Largura de conteúdo A4 com margens 1": `11906 - 2880 = 9026 DXA`

**Paisagem:** Passar dimensões retrato + `orientation: PageOrientation.LANDSCAPE` (docx-js troca internamente).

### Listas

```javascript
numbering: { config: [
  { reference: "bullets", levels: [{ level: 0, format: LevelFormat.BULLET, text: "\u2022",
    alignment: AlignmentType.LEFT, style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] }
] }
// Usar: new Paragraph({ numbering: { reference: "bullets", level: 0 }, children: [...] })
```

### Tabelas

```javascript
// Largura tabela = soma columnWidths. Usar SEMPRE WidthType.DXA (nunca PERCENTAGE).
new Table({
  width: { size: 9026, type: WidthType.DXA },
  columnWidths: [4513, 4513],
  rows: [new TableRow({ children: [
    new TableCell({
      borders: { top: b, bottom: b, left: b, right: b },
      width: { size: 4513, type: WidthType.DXA },
      shading: { fill: "D5E8F0", type: ShadingType.CLEAR },  // CLEAR, nunca SOLID
      margins: { top: 80, bottom: 80, left: 120, right: 120 },
      children: [new Paragraph({ children: [new TextRun("Célula")] })]
    })
  ] })]
})
```

### Imagens

```javascript
new ImageRun({
  type: "png",  // Obrigatório
  data: fs.readFileSync("image.png"),
  transformation: { width: 200, height: 150 },
  altText: { title: "T", description: "D", name: "N" }  // Três obrigatórios
})
```

### Cabeçalhos/rodapés

```javascript
headers: { default: new Header({ children: [new Paragraph({ children: [new TextRun("Cabeçalho")] })] }) },
footers: { default: new Footer({ children: [new Paragraph({
  children: [new TextRun("Página "), new TextRun({ children: [PageNumber.CURRENT] })]
})] }) }
```

### Regras críticas docx-js

- Nunca usar `\n` — usar Paragraphs separados
- Nunca usar bullets unicode — usar `LevelFormat.BULLET`
- PageBreak dentro de Paragraph: `new Paragraph({ children: [new PageBreak()] })`
- ImageRun requer `type`
- Tabelas: `columnWidths` E `width` na célula, ambos devem corresponder
- Usar `ShadingType.CLEAR`, nunca SOLID
- TOC requer `HeadingLevel` apenas, sem estilos custom
- Override estilos: IDs exactos "Heading1", "Heading2" + `outlineLevel`

## Editar documentos existentes

### Passo 1: Descompactar

```bash
python scripts/office/unpack.py document.docx unpacked/
```

### Passo 2: Editar XML

Editar ficheiros em `unpacked/word/`. Usar ferramenta Edit directamente (não scripts Python).

**Tracked changes:**
```xml
<!-- Inserção -->
<w:ins w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
  <w:r><w:t>texto inserido</w:t></w:r>
</w:ins>

<!-- Eliminação -->
<w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
  <w:r><w:delText>texto eliminado</w:delText></w:r>
</w:del>
```

**Comentários:**
```bash
python scripts/comment.py unpacked/ 0 "Texto do comentário"
python scripts/comment.py unpacked/ 1 "Resposta" --parent 0
```

**Smart quotes:** `&#x2018;` `&#x2019;` `&#x201C;` `&#x201D;`

### Passo 3: Recompactar

```bash
python scripts/office/pack.py unpacked/ output.docx --original document.docx
```

Validação: `python scripts/office/validate.py doc.docx`

## Convenções Descomplicar

- Data: DD-MM-YYYY
- Monetário: 1.234,56 EUR
- Fonte: Arial 12pt
- Página: A4 (11906 x 16838 DXA)
- Autor tracked changes: "Claude"
- Idioma: PT-PT

---
**Versão**: 1.0.0-light | **Base**: 1.0.0