docx

Criação, edição e análise de DOCX

Visão Geral

Um usuário pode pedir que você crie, edite ou analise o conteúdo de um arquivo .docx. Um arquivo .docx é essencialmente um arquivo ZIP contendo arquivos XML e outros recursos que podem ser lidos ou editados. Você dispõe de diferentes ferramentas e fluxos de trabalho para diferentes tarefas.

Árvore de Decisão do Fluxo de Trabalho

Leitura/Análise de Conteúdo

Use as seções "Extração de texto" ou "Acesso XML bruto" abaixo

Criação de Novo Documento

Use o fluxo de trabalho "Criando um novo documento Word"

Edição de Documento Existente

• Seu próprio documento + alterações simples Use o fluxo de trabalho "Edição OOXML básica"

• Documento de outra pessoa Use o "Fluxo de redlining" (recomendado como padrão)

• Documentos jurídicos, acadêmicos, comerciais ou governamentais Use o "Fluxo de redlining" (obrigatório)

Lendo e analisando conteúdo

Extração de texto

Se você precisa apenas ler o conteúdo textual de um documento, converta-o para markdown usando pandoc. O pandoc oferece excelente suporte para preservar a estrutura do documento e pode exibir alterações controladas:

# Converter documento para markdown com alterações controladas
pandoc --track-changes=all caminho-para-arquivo.docx -o output.md
# Opções: --track-changes=accept/reject/all

Acesso XML bruto

Você precisa de acesso XML bruto para: comentários, formatação complexa, estrutura do documento, mídia incorporada e metadados. Para qualquer um desses recursos, você precisará descompactar um documento e ler seu conteúdo XML bruto.

Descompactando um arquivo

python ooxml/scripts/unpack.py <office_file> <output_directory>

Estruturas de arquivo principais

• word/document.xml - Conteúdo principal do documento
• word/comments.xml - Comentários referenciados em document.xml
• word/media/ - Imagens e arquivos de mídia incorporados
• Alterações controladas usam tags <w:ins> (inserções) e <w:del> (exclusões)

Criando um novo documento Word

Ao criar um novo documento Word do zero, use docx-js, que permite criar documentos Word usando JavaScript/TypeScript.

Fluxo de trabalho

1. OBRIGATÓRIO - LEIA O ARQUIVO INTEIRO: Leia docx-js.md (~500 linhas) completamente do início ao fim. NUNCA defina limites de intervalo ao ler este arquivo. Leia o conteúdo completo para obter a sintaxe detalhada, regras críticas de formatação e melhores práticas antes de prosseguir com a criação do documento.
2. Crie um arquivo JavaScript/TypeScript usando os componentes Document, Paragraph, TextRun (Você pode presumir que todas as dependências estão instaladas; caso contrário, consulte a seção de dependências abaixo)
3. Exporte como .docx usando Packer.toBuffer()

Editando um documento Word existente

Ao editar um documento Word existente, use a Document library (uma biblioteca Python para manipulação de OOXML). A biblioteca gerencia automaticamente a configuração da infraestrutura e fornece métodos para manipulação de documentos. Para cenários complexos, você pode acessar o DOM subjacente diretamente através da biblioteca.

Fluxo de trabalho

1. OBRIGATÓRIO - LEIA O ARQUIVO INTEIRO: Leia ooxml.md (~600 linhas) completamente do início ao fim. NUNCA defina limites de intervalo ao ler este arquivo. Leia o conteúdo completo para obter a API da Document library e padrões XML para edição direta de arquivos de documento.
2. Descompacte o documento: python ooxml/scripts/unpack.py <office_file> <output_directory>
3. Crie e execute um script Python usando a Document library (consulte a seção "Document Library" em ooxml.md)
4. Empacote o documento final: python ooxml/scripts/pack.py <input_directory> <office_file>

A Document library fornece métodos de alto nível para operações comuns e acesso direto ao DOM para cenários complexos.

Fluxo de redlining para revisão de documentos

Este fluxo de trabalho permite planejar alterações controladas abrangentes usando markdown antes de implementá-las em OOXML. CRÍTICO: Para alterações controladas completas, você deve implementar TODAS as alterações de forma sistemática.

Estratégia de Lotes: Agrupe alterações relacionadas em lotes de 3 a 10 alterações. Isso torna a depuração gerenciável, mantendo a eficiência. Teste cada lote antes de passar para o próximo.

Princípio: Edições Mínimas e Precisas Ao implementar alterações controladas, marque apenas o texto que realmente muda. Repetir texto inalterado dificulta a revisão das edições e parece pouco profissional. Divida as substituições em: [texto inalterado] + [exclusão] + [inserção] + [texto inalterado]. Preserve o RSID da execução original para texto inalterado extraindo o elemento <w:r> original e reutilizando-o.

Exemplo - Alterando "30 dias" para "60 dias" em uma frase:

# RUIM - Substitui a frase inteira
'<w:del><w:r><w:delText>O prazo é de 30 dias.</w:delText></w:r></w:del><w:ins><w:r><w:t>O prazo é de 60 dias.</w:t></w:r></w:ins>'

# BOM - Marca apenas o que mudou, preserva o <w:r> original para texto inalterado
'<w:r w:rsidR="00AB12CD"><w:t>O prazo é de </w:t></w:r><w:del><w:r><w:delText>30</w:delText></w:r></w:del><w:ins><w:r><w:t>60</w:t></w:r></w:ins><w:r w:rsidR="00AB12CD"><w:t> dias.</w:t></w:r>'

Fluxo de trabalho de alterações controladas

1. Obter representação em markdown: Converta o documento para markdown com alterações controladas preservadas:

   pandoc --track-changes=all caminho-para-arquivo.docx -o current.md
   

2. Identificar e agrupar alterações: Revise o documento e identifique TODAS as alterações necessárias, organizando-as em lotes lógicos:

   Métodos de localização (para encontrar alterações no XML):

   • Números de seção/cabeçalho (ex.: "Seção 3.2", "Artigo IV")
   • Identificadores de parágrafo se numerados
   • Padrões grep com texto circundante único
   • Estrutura do documento (ex.: "primeiro parágrafo", "bloco de assinatura")
   • NÃO use números de linha do markdown - eles não correspondem à estrutura XML

   Organização de lotes (agrupe de 3 a 10 alterações relacionadas por lote):

   • Por seção: "Lote 1: Emendas da Seção 2", "Lote 2: Atualizações da Seção 5"
   • Por tipo: "Lote 1: Correções de datas", "Lote 2: Alterações de nomes de partes"
   • Por complexidade: Comece com substituições simples de texto, depois aborde alterações estruturais complexas
   • Sequencial: "Lote 1: Páginas 1-3", "Lote 2: Páginas 4-6"

3. Ler documentação e descompactar:

   • OBRIGATÓRIO - LEIA O ARQUIVO INTEIRO: Leia ooxml.md (~600 linhas) completamente do início ao fim. NUNCA defina limites de intervalo ao ler este arquivo. Preste atenção especial às seções "Document Library" e "Tracked Change Patterns".
   • Descompacte o documento: python ooxml/scripts/unpack.py <arquivo.docx> <dir>
   • Anote o RSID sugerido: O script de descompactação sugerirá um RSID para usar em suas alterações controladas. Copie este RSID para uso na etapa 4b.

4. Implementar alterações em lotes: Agrupe as alterações logicamente (por seção, por tipo ou por proximidade) e implemente-as juntas em um único script. Esta abordagem:

   • Facilita a depuração (lote menor = mais fácil isolar erros)
   • Permite progresso incremental
   • Mantém a eficiência (tamanho do lote de 3 a 10 alterações funciona bem)

   Agrupamentos de lote sugeridos:

   • Por seção do documento (ex.: "Alterações da Seção 3", "Definições", "Cláusula de rescisão")
   • Por tipo de alteração (ex.: "Alterações de datas", "Atualizações de nomes de partes", "Substituições de termos legais")
   • Por proximidade (ex.: "Alterações nas páginas 1-3", "Alterações na primeira metade do documento")

   Para cada lote de alterações relacionadas:

   a. Mapear texto para XML: Use grep no word/document.xml para verificar como o texto está dividido entre elementos <w:r>.

   b. Criar e executar script: Use get_node para encontrar nós, implemente as alterações e depois doc.save(). Consulte a seção "Document Library" em ooxml.md para padrões.

   Nota: Sempre execute grep em word/document.xml imediatamente antes de escrever um script para obter os números de linha atuais e verificar o conteúdo do texto. Os números de linha mudam após cada execução de script.

5. Empacotar o documento: Após todos os lotes estarem concluídos, converta o diretório descompactado de volta para .docx:

   python ooxml/scripts/pack.py descompactado documento-revisado.docx
   

6. Verificação final: Faça uma verificação abrangente do documento completo:

   • Converta o documento final para markdown:

     pandoc --track-changes=all documento-revisado.docx -o verificacao.md
     

   • Verifique se TODAS as alterações foram aplicadas corretamente:

     grep "frase original" verificacao.md  # NÃO deve encontrá-la
     grep "frase de substituição" verificacao.md  # Deve encontrá-la
     

   • Verifique se nenhuma alteração não intencional foi introduzida

Convertendo Documentos para Imagens

Para analisar visualmente documentos Word, converta-os para imagens usando um processo de duas etapas:

1. Converter DOCX para PDF:

   soffice --headless --convert-to pdf documento.docx
   

2. Converter páginas PDF para imagens JPEG:

   pdftoppm -jpeg -r 150 documento.pdf pagina
   

   Isso cria arquivos como pagina-1.jpg, pagina-2.jpg, etc.

Opções:

• -r 150: Define a resolução para 150 DPI (ajuste para equilíbrio qualidade/tamanho)
• -jpeg: Saída no formato JPEG (use -png para PNG, se preferir)
• -f N: Primeira página a converter (ex.: -f 2 começa da página 2)
• -l N: Última página a converter (ex.: -l 5 para na página 5)
• pagina: Prefixo para arquivos de saída

Exemplo para intervalo específico:

pdftoppm -jpeg -r 150 -f 2 -l 5 documento.pdf pagina  # Converte apenas as páginas 2-5

Diretrizes de Estilo de Código

IMPORTANTE: Ao gerar código para operações DOCX:

• Escreva código conciso
• Evite nomes de variáveis verbosos e operações redundantes
• Evite instruções print desnecessárias

Dependências

Dependências necessárias (instale se não estiverem disponíveis):

• pandoc: sudo apt-get install pandoc (para extração de texto)
• docx: npm install -g docx (para criar novos documentos)
• LibreOffice: sudo apt-get install libreoffice (para conversão para PDF)
• Poppler: sudo apt-get install poppler-utils (para pdftoppm converter PDF para imagens)
• defusedxml: pip install defusedxml (para análise XML segura)