O que Criação, edição e análise de DOCX faz?
Visão geral
Um arquivo .docx é um arquivo ZIP contendo arquivos XML.
Referência rápida
| Tarefa | Abordagem |
|---|---|
| Ler/analisar conteúdo | markitdown ou descompactar para XML bruto |
| Criar novo documento | Use docx-js - veja Criando Novos Documentos abaixo |
| Editar documento existente | Descompactar → editar XML → recompactar - veja Editando Documentos Existentes abaixo |
Leitura de conteúdo
# Extração de texto
markitdown documento.docx > output.md
# Acesso XML bruto
python scripts/office/unpack.py documento.docx descompactado/
Aceitando alterações controladas
Para produzir um documento limpo com todas as alterações controladas aceitas:
python scripts/accept_changes.py entrada.docx saida.docx
Criando Novos Documentos
Gere arquivos .docx com JavaScript, depois valide. Instale: npm install -g docx
Configuração
const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, ImageRun,
Header, Footer, AlignmentType, PageOrientation, LevelFormat, ExternalHyperlink,
InternalHyperlink, Bookmark, FootnoteReferenceRun, PositionalTab,
PositionalTabAlignment, PositionalTabRelativeTo, PositionalTabLeader,
TabStopType, TabStopPosition, Column, SectionType,
TableOfContents, HeadingLevel, BorderStyle, WidthType, ShadingType,
VerticalAlign, PageNumber, PageBreak } = require('docx');
const doc = new Document({ sections: [{ children: [/* conteúdo */] }] });
Packer.toBuffer(doc).then(buffer => fs.writeFileSync("doc.docx", buffer));
Validação
Após criar o arquivo, valide-o. Se a validação falhar, descompacte, corrija o XML e recompacte.
python scripts/office/validate.py doc.docx
Tamanho da página
// CRÍTICO: docx-js usa A4 como padrão, não US Letter
// Sempre defina o tamanho da página explicitamente para resultados consistentes
sections: [{
properties: {
page: {
size: {
width: 12240, // 8,5 polegadas em DXA
height: 15840 // 11 polegadas em DXA
},
margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } // margens de 1 polegada
}
},
children: [/* conteúdo */]
}]
Tamanhos de página comuns (unidades DXA, 1440 DXA = 1 polegada):
| Papel | Largura | Altura | Largura do conteúdo (margens de 1") |
|---|---|---|---|
| US Letter | 12.240 | 15.840 | 9.360 |
| A4 (padrão) | 11.906 | 16.838 | 9.026 |
Orientação paisagem: docx-js troca largura/altura internamente, então passe as dimensões de retrato e deixe-o lidar com a troca:
size: {
width: 12240, // Passe o lado CURTO como largura
height: 15840, // Passe o lado LONGO como altura
orientation: PageOrientation.LANDSCAPE // docx-js os troca no XML
},
// Largura do conteúdo = 15840 - margem esquerda - margem direita (usa o lado longo)
Estilos (Substituir cabeçalhos internos)
Use Arial como fonte padrão (suportada universalmente). Mantenha títulos em preto para legibilidade.
const doc = new Document({
styles: {
default: { document: { run: { font: "Arial", size: 24 } } }, // 12pt padrão
paragraphStyles: [
// IMPORTANTE: Use IDs exatos para substituir estilos internos
{ id: "Heading1", name: "Heading 1", basedOn: "Normal", next: "Normal", quickFormat: true,
run: { size: 32, bold: true, font: "Arial" },
paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 } }, // outlineLevel obrigatório para TOC
{ id: "Heading2", name: "Heading 2", basedOn: "Normal", next: "Normal", quickFormat: true,
run: { size: 28, bold: true, font: "Arial" },
paragraph: { spacing: { before: 180, after: 180 }, outlineLevel: 1 } },
]
},
sections: [{
children: [
new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun("Título")] }),
]
}]
});
Listas (NUNCA use marcadores Unicode)
// ❌ ERRADO - nunca insira manualmente caracteres de marcador
new Paragraph({ children: [new TextRun("• Item")] }) // RUIM
new Paragraph({ children: [new TextRun("\u2022 Item")] }) // RUIM
// ✅ CORRETO - use configuração de numeração com LevelFormat.BULLET
const doc = new Document({
numbering: {
config: [
{ reference: "bullets",
levels: [{ level: 0, format: LevelFormat.BULLET, text: "•", alignment: AlignmentType.LEFT,
style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
{ reference: "numbers",
levels: [{ level: 0, format: LevelFormat.DECIMAL, text: "%1.", alignment: AlignmentType.LEFT,
style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
]
},
sections: [{
children: [
new Paragraph({ numbering: { reference: "bullets", level: 0 },
children: [new TextRun("Item com marcador")] }),
new Paragraph({ numbering: { reference: "numbers", level: 0 },
children: [new TextRun("Item numerado")] }),
]
}]
});
// ⚠️ Cada referência cria numeração INDEPENDENTE
// Mesma referência = continua (1,2,3 então 4,5,6)
// Referência diferente = reinicia (1,2,3 então 1,2,3)
Tabelas
CRÍTICO: Tabelas precisam de larguras duplas - defina tanto columnWidths na tabela quanto width em cada célula. Sem ambos, as tabelas renderizam incorretamente em algumas plataformas.
// CRÍTICO: Sempre defina a largura da tabela para renderização consistente
// CRÍTICO: Use ShadingType.CLEAR (não SOLID) para evitar fundos pretos
const border = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" };
const borders = { top: border, bottom: border, left: border, right: border };
new Table({
width: { size: 9360, type: WidthType.DXA }, // Sempre use DXA (porcentagens quebram no Google Docs)
columnWidths: [4680, 4680], // Devem somar à largura da tabela (DXA: 1440 = 1 polegada)
rows: [
new TableRow({
children: [
new TableCell({
borders,
width: { size: 4680, type: WidthType.DXA }, // Também defina em cada célula
shading: { fill: "D5E8F0", type: ShadingType.CLEAR }, // CLEAR não SOLID
margins: { top: 80, bottom: 80, left: 120, right: 120 }, // Preenchimento da célula (interno, não adiciona à largura)
children: [new Paragraph({ children: [new TextRun("Célula")] })]
})
]
})
]
})
Cálculo da largura da tabela:
Sempre use WidthType.DXA — WidthType.PERCENTAGE quebra no Google Docs.
// Largura da tabela = soma de columnWidths = largura do conteúdo
// US Letter com margens de 1": 12240 - 2880 = 9360 DXA
width: { size: 9360, type: WidthType.DXA },
columnWidths: [7000, 2360] // Devem somar à largura da tabela
Regras de largura:
- Sempre use
WidthType.DXA— nuncaWidthType.PERCENTAGE(incompatível com Google Docs) - A largura da tabela deve ser igual à soma de
columnWidths - A
widthda célula deve corresponder àcolumnWidthrespectiva - As
marginsda célula são preenchimento interno; elas reduzem a área de conteúdo e não se somam à largura da célula - Para tabelas de largura total: use a largura do conteúdo (largura da página menos as margens esquerda e direita)
Imagens
// CRÍTICO: o parâmetro type é OBRIGATÓRIO
new Paragraph({
children: [new ImageRun({
type: "png", // Obrigatório: png, jpg, jpeg, gif, bmp, svg
data: fs.readFileSync("imagem.png"),
transformation: { width: 200, height: 150 },
altText: { title: "Título", description: "Desc", name: "Nome" } // Todos os três obrigatórios
})]
})
Quebras de página
// CRÍTICO: PageBreak deve estar dentro de um Paragraph
new Paragraph({ children: [new PageBreak()] })
// Ou use pageBreakBefore
new Paragraph({ pageBreakBefore: true, children: [new TextRun("Nova página")] })
Hiperlinks
// Link externo
new Paragraph({
children: [new ExternalHyperlink({
children: [new TextRun({ text: "Clique aqui", style: "Hyperlink" })],
link: "https://exemplo.com",
})]
})
// Link interno (marcador + referência)
// 1. Crie marcador no destino
new Paragraph({ heading: HeadingLevel.HEADING_1, children: [
new Bookmark({ id: "capitulo1", children: [new TextRun("Capítulo 1")] }),
]})
// 2. Link para ele
new Paragraph({ children: [new InternalHyperlink({
children: [new TextRun({ text: "Veja Capítulo 1", style: "Hyperlink" })],
anchor: "capitulo1",
})]})
Notas de rodapé
const doc = new Document({
footnotes: {
1: { children: [new Paragraph("Fonte: Relatório Anual 2024")] },
2: { children: [new Paragraph("Consulte o apêndice para metodologia")] },
},
sections: [{
children: [new Paragraph({
children: [
new TextRun("A receita cresceu 15%"),
new FootnoteReferenceRun(1),
new TextRun(" usando métricas ajustadas"),
new FootnoteReferenceRun(2),
],
})]
}]
});
Paradas de tabulação
// Alinhar texto à direita na mesma linha (ex.: data oposta a um título)
new Paragraph({
children: [
new TextRun("Nome da Empresa"),
new TextRun("\tJaneiro 2025"),
],
tabStops: [{ type: TabStopType.RIGHT, position: TabStopPosition.MAX }],
})
// Líder de ponto (estilo TOC)
new Paragraph({
children: [
new TextRun("Introdução"),
new TextRun({ children: [
new PositionalTab({
alignment: PositionalTabAlignment.RIGHT,
relativeTo: PositionalTabRelativeTo.MARGIN,
leader: PositionalTabLeader.DOT,
}),
"3",
]}),
],
})
Layouts de múltiplas colunas
// Colunas de largura igual
sections: [{
properties: {
column: {
count: 2, // número de colunas
space: 720, // espaço entre colunas em DXA (720 = 0,5 polegada)
equalWidth: true,
separate: true, // linha vertical entre colunas
},
},
children: [/* conteúdo flui naturalmente entre colunas */]
}]
// Colunas de largura personalizada (equalWidth deve ser false)
sections: [{
properties: {
column: {
equalWidth: false,
children: [
new Column({ width: 5400, space: 720 }),
new Column({ width: 3240 }),
],
},
},
children: [/* conteúdo */]
}]
Force uma quebra de coluna com uma nova seção usando type: SectionType.NEXT_COLUMN.
Sumário
// CRÍTICO: Cabeçalhos devem usar HeadingLevel APENAS - sem estilos personalizados
new TableOfContents("Sumário", { hyperlink: true, headingStyleRange: "1-3" })
Cabeçalhos/Rodapés
sections: [{
properties: {
page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } // 1440 = 1 polegada
},
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] })]
})] })
},
children: [/* conteúdo */]
}]
Regras críticas para docx-js
- Defina o tamanho da página explicitamente - docx-js usa A4 como padrão; use US Letter (12240 x 15840 DXA) para documentos dos EUA
- Paisagem: passe dimensões de retrato - docx-js troca largura/altura internamente; passe o lado curto como
width, o lado longo comoheight, e definaorientation: PageOrientation.LANDSCAPE - Nunca use
\n- use elementos Paragraph separados - Nunca use marcadores Unicode - use
LevelFormat.BULLETcom configuração de numeração - PageBreak deve estar em Paragraph - autônomo cria XML inválido
- ImageRun requer
type- sempre especifique png/jpg/etc - Sempre defina
widthda tabela com DXA - nunca useWidthType.PERCENTAGE(quebra no Google Docs) - Tabelas precisam de larguras duplas - array
columnWidthsEwidthda célula, ambos devem corresponder - Largura da tabela = soma de columnWidths - para DXA, garanta que somem exatamente
- Sempre adicione margens de célula - use
margins: { top: 80, bottom: 80, left: 120, right: 120 }para preenchimento legível - Use
ShadingType.CLEAR- nunca SOLID para sombreamento de tabela - Nunca use tabelas como divisores/linhas - células têm altura mínima e renderizam como caixas vazias (incluindo em cabeçalhos/rodapés); use
border: { bottom: { style: BorderStyle.SINGLE, size: 6, color: "2E75B6", space: 1 } }em um Paragraph. Para rodapés de duas colunas, use paradas de tabulação (veja seção Paradas de Tabulação), não tabelas - TOC requer HeadingLevel apenas - sem estilos personalizados em parágrafos de cabeçalho
- Substitua estilos internos - use IDs exatos: "Heading1", "Heading2", etc.
- Inclua
outlineLevel- obrigatório para TOC (0 para H1, 1 para H2, etc.)
Editando Documentos Existentes
Siga todas as 3 etapas em ordem.
Etapa 1: Descompactar
python scripts/office/unpack.py documento.docx descompactado/
Extrai XML, formata-o, mescla execuções adjacentes e converte aspas curvas em entidades XML (“ etc.) para que sobrevivam à edição. Use --merge-runs false para pular a mesclagem de execuções.
Etapa 2: Editar XML
Edite arquivos em descompactado/word/. Veja a Referência XML abaixo para padrões.
Use "Claude" como autor para alterações controladas e comentários, a menos que o usuário solicite explicitamente o uso de um nome diferente.
Use a ferramenta Editar diretamente para substituição de strings. Não escreva scripts Python. Scripts introduzem complexidade desnecessária. A ferramenta Editar mostra exatamente o que está sendo substituído.
CRÍTICO: Use aspas curvas para novo conteúdo. Ao adicionar texto com apóstrofos ou aspas, use entidades XML para produzir aspas curvas:
<!-- Use estas entidades para tipografia profissional -->
<w:t>Aqui’s a quote: “Olá”</w:t>
| Entidade | Caractere |
|---|---|
‘ | ' (aspa simples esquerda) |
’ | ' (aspa simples direita / apóstrofo) |
“ | " (aspa dupla esquerda) |
” | " (aspa dupla direita) |
Adicionando comentários: Use comment.py para lidar com código padrão em múltiplos arquivos XML (o texto deve ser pré-escapado em XML):
python scripts/comment.py descompactado/ 0 "Texto do comentário com & e ’"
python scripts/comment.py descompactado/ 1 "Texto de resposta" --parent 0 # responder ao comentário 0
python scripts/comment.py descompactado/ 0 "Texto" --author "Autor Personalizado" # nome de autor personalizado
Em seguida, adicione marcadores ao document.xml (veja Comentários na Referência XML).
Etapa 3: Compactar
python scripts/office/pack.py descompactado/ saida.docx --original documento.docx
Valida com auto-reparo, condensa XML e cria o arquivo .docx.