Creación, edición y análisis de DOCX
Descripción general
Un archivo .docx es un archivo ZIP que contiene archivos XML.
Referencia rápida
| Tarea | Enfoque |
|---|---|
| Leer/analizar contenido | markitdown o desempaquetar para XML sin procesar |
| Crear nuevo documento | Usar docx-js - ver Creación de Nuevos Documentos a continuación |
| Editar documento existente | Desempaquetar → editar XML → reempaquetar - ver Edición de Documentos Existentes a continuación |
Lectura de contenido
# Extracción de texto
markitdown document.docx > output.md
# Acceso a XML sin procesar
python scripts/office/unpack.py document.docx unpacked/
Aceptación de cambios controlados
Para producir un documento limpio con todos los cambios controlados aceptados:
python scripts/accept_changes.py input.docx output.docx
Creación de Nuevos Documentos
Genere archivos .docx con JavaScript y luego valídelos. Instale: npm install -g docx
Configuración
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: [/* contenido */] }] });
Packer.toBuffer(doc).then(buffer => fs.writeFileSync("doc.docx", buffer));
Validación
Después de crear el archivo, valídelo. Si la validación falla, desempáquelo, corrija el XML y reempaquételo.
python scripts/office/validate.py doc.docx
Tamaño de página
// CRÍTICO: docx-js usa A4 por defecto, no Carta EE.UU.
// Siempre establezca el tamaño de página explícitamente para obtener resultados consistentes
sections: [{
properties: {
page: {
size: {
width: 12240, // 8.5 pulgadas en DXA
height: 15840 // 11 pulgadas en DXA
},
margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } // Márgenes de 1 pulgada
}
},
children: [/* contenido */]
}]
Tamaños de página comunes (unidades DXA, 1440 DXA = 1 pulgada):
| Papel | Ancho | Alto | Ancho de contenido (márgenes de 1") |
|---|---|---|---|
| Carta EE.UU. | 12,240 | 15,840 | 9,360 |
| A4 (predeterminado) | 11,906 | 16,838 | 9,026 |
Orientación horizontal: docx-js intercambia ancho/alto internamente, así que pase las dimensiones verticales y deje que maneje el intercambio:
size: {
width: 12240, // Pase el borde CORTO como ancho
height: 15840, // Pase el borde LARGO como alto
orientation: PageOrientation.LANDSCAPE // docx-js los intercambia en el XML
},
// Ancho de contenido = 15840 - margen izquierdo - margen derecho (usa el borde largo)
Estilos (Anular estilos de título integrados)
Use Arial como fuente predeterminada (compatible universalmente). Mantenga los títulos en negro para facilitar la lectura.
const doc = new Document({
styles: {
default: { document: { run: { font: "Arial", size: 24 } } }, // 12pt predeterminado
paragraphStyles: [
// IMPORTANTE: Use ID exactos para anular los estilos integrados
{ 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 requerido 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 viñetas Unicode)
// ❌ INCORRECTO - nunca inserte caracteres de viñeta manualmente
new Paragraph({ children: [new TextRun("• Elemento")] }) // MALO
new Paragraph({ children: [new TextRun("\u2022 Elemento")] }) // MALO
// ✅ CORRECTO - use la configuración de numeración con 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("Elemento de viñeta")] }),
new Paragraph({ numbering: { reference: "numbers", level: 0 },
children: [new TextRun("Elemento numerado")] }),
]
}]
});
// ⚠️ Cada referencia crea una numeración INDEPENDIENTE
// Misma referencia = continúa (1,2,3 luego 4,5,6)
// Referencia diferente = reinicia (1,2,3 luego 1,2,3)
Tablas
CRÍTICO: Las tablas necesitan anchos duales - establezca tanto columnWidths en la tabla como width en cada celda. Sin ambos, las tablas se renderizan incorrectamente en algunas plataformas.
// CRÍTICO: Siempre establezca el ancho de la tabla para un renderizado consistente
// CRÍTICO: Use ShadingType.CLEAR (no SOLID) para evitar fondos negros
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 }, // Siempre use DXA (los porcentajes fallan en Google Docs)
columnWidths: [4680, 4680], // Deben sumar el ancho de la tabla (DXA: 1440 = 1 pulgada)
rows: [
new TableRow({
children: [
new TableCell({
borders,
width: { size: 4680, type: WidthType.DXA }, // También establecido en cada celda
shading: { fill: "D5E8F0", type: ShadingType.CLEAR }, // CLEAR no SOLID
margins: { top: 80, bottom: 80, left: 120, right: 120 }, // Relleno de celda (interno, no se suma al ancho)
children: [new Paragraph({ children: [new TextRun("Celda")] })]
})
]
})
]
})
Cálculo del ancho de la tabla:
Siempre use WidthType.DXA — WidthType.PERCENTAGE falla en Google Docs.
// Ancho de tabla = suma de columnWidths = ancho de contenido
// Carta EE.UU. con márgenes de 1": 12240 - 2880 = 9360 DXA
width: { size: 9360, type: WidthType.DXA },
columnWidths: [7000, 2360] // Deben sumar el ancho de la tabla
Reglas de ancho:
- Siempre use
WidthType.DXA— nuncaWidthType.PERCENTAGE(incompatible con Google Docs) - El ancho de la tabla debe ser igual a la suma de
columnWidths - El
widthde la celda debe coincidir con elcolumnWidthcorrespondiente - Los
marginsde la celda son relleno interno; reducen el área de contenido y no se agregan al ancho de la celda - Para tablas de ancho completo: use el ancho de contenido (ancho de página menos márgenes izquierdo y derecho)
Imágenes
// CRÍTICO: el parámetro type es OBLIGATORIO
new Paragraph({
children: [new ImageRun({
type: "png", // Requerido: png, jpg, jpeg, gif, bmp, svg
data: fs.readFileSync("image.png"),
transformation: { width: 200, height: 150 },
altText: { title: "Título", description: "Descripción", name: "Nombre" } // Los tres son obligatorios
})]
})
Saltos de página
// CRÍTICO: PageBreak debe estar dentro de un Paragraph
new Paragraph({ children: [new PageBreak()] })
// O use pageBreakBefore
new Paragraph({ pageBreakBefore: true, children: [new TextRun("Nueva página")] })
Hipervínculos
// Enlace externo
new Paragraph({
children: [new ExternalHyperlink({
children: [new TextRun({ text: "Haga clic aquí", style: "Hyperlink" })],
link: "https://example.com",
})]
})
// Enlace interno (marcador + referencia)
// 1. Crear marcador en el destino
new Paragraph({ heading: HeadingLevel.HEADING_1, children: [
new Bookmark({ id: "chapter1", children: [new TextRun("Capítulo 1")] }),
]})
// 2. Enlazar a él
new Paragraph({ children: [new InternalHyperlink({
children: [new TextRun({ text: "Ver Capítulo 1", style: "Hyperlink" })],
anchor: "chapter1",
})]})
Notas al pie
const doc = new Document({
footnotes: {
1: { children: [new Paragraph("Fuente: Informe Anual 2024")] },
2: { children: [new Paragraph("Consulte el apéndice para conocer la metodología")] },
},
sections: [{
children: [new Paragraph({
children: [
new TextRun("Los ingresos crecieron un 15%"),
new FootnoteReferenceRun(1),
new TextRun(" usando métricas ajustadas"),
new FootnoteReferenceRun(2),
],
})]
}]
});
Tabulaciones
// Alinear texto a la derecha en la misma línea (ej. fecha opuesta a un título)
new Paragraph({
children: [
new TextRun("Nombre de la empresa"),
new TextRun("\tEnero 2025"),
],
tabStops: [{ type: TabStopType.RIGHT, position: TabStopPosition.MAX }],
})
// Líder de puntos (ej. estilo TOC)
new Paragraph({
children: [
new TextRun("Introducción"),
new TextRun({ children: [
new PositionalTab({
alignment: PositionalTabAlignment.RIGHT,
relativeTo: PositionalTabRelativeTo.MARGIN,
leader: PositionalTabLeader.DOT,
}),
"3",
]}),
],
})
Diseños de varias columnas
// Columnas de igual ancho
sections: [{
properties: {
column: {
count: 2, // número de columnas
space: 720, // espacio entre columnas en DXA (720 = 0.5 pulgadas)
equalWidth: true,
separate: true, // línea vertical entre columnas
},
},
children: [/* el contenido fluye naturalmente a través de las columnas */]
}]
// Columnas de ancho personalizado (equalWidth debe ser false)
sections: [{
properties: {
column: {
equalWidth: false,
children: [
new Column({ width: 5400, space: 720 }),
new Column({ width: 3240 }),
],
},
},
children: [/* contenido */]
}]
Fuerce un salto de columna con una nueva sección usando type: SectionType.NEXT_COLUMN.
Tabla de contenido
// CRÍTICO: Los títulos deben usar SOLO HeadingLevel - sin estilos personalizados
new TableOfContents("Tabla de contenido", { hyperlink: true, headingStyleRange: "1-3" })
Encabezados/Pies de página
sections: [{
properties: {
page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } // 1440 = 1 pulgada
},
headers: {
default: new Header({ children: [new Paragraph({ children: [new TextRun("Encabezado")] })] })
},
footers: {
default: new Footer({ children: [new Paragraph({
children: [new TextRun("Página "), new TextRun({ children: [PageNumber.CURRENT] })]
})] })
},
children: [/* contenido */]
}]
Reglas críticas para docx-js
- Establezca el tamaño de página explícitamente - docx-js usa A4 por defecto; use Carta EE.UU. (12240 x 15840 DXA) para documentos estadounidenses
- Horizontal: pase dimensiones verticales - docx-js intercambia ancho/alto internamente; pase el borde corto como
width, el borde largo comoheight, y establezcaorientation: PageOrientation.LANDSCAPE - Nunca use
\n- use elementos Paragraph separados - Nunca use viñetas Unicode - use
LevelFormat.BULLETcon configuración de numeración - PageBreak debe estar en Paragraph - independiente crea XML no válido
- ImageRun requiere
type- especifique siempre png/jpg/etc. - Siempre establezca el
widthde la tabla con DXA - nunca useWidthType.PERCENTAGE(falla en Google Docs) - Las tablas necesitan anchos duales - matriz
columnWidthsYwidthde celda, ambos deben coincidir - Ancho de tabla = suma de columnWidths - para DXA, asegúrese de que sumen exactamente
- Siempre agregue márgenes de celda - use
margins: { top: 80, bottom: 80, left: 120, right: 120 }para un relleno legible - Use
ShadingType.CLEAR- nunca SOLID para sombreado de tabla - Nunca use tablas como divisores/reglas - las celdas tienen una altura mínima y se renderizan como cuadros vacíos (incluso en encabezados/pies de página); use
border: { bottom: { style: BorderStyle.SINGLE, size: 6, color: "2E75B6", space: 1 } }en un Paragraph en su lugar. Para pies de página de dos columnas, use tabulaciones (consulte la sección Tabulaciones), no tablas - TOC requiere solo HeadingLevel - sin estilos personalizados en párrafos de títulos
- Anule los estilos integrados - use ID exactos: "Heading1", "Heading2", etc.
- Incluya
outlineLevel- requerido para TOC (0 para H1, 1 para H2, etc.)
Edición de Documentos Existentes
Siga los 3 pasos en orden.
Paso 1: Desempaquetar
python scripts/office/unpack.py document.docx unpacked/
Extrae XML, preformatea, fusiona ejecuciones adyacentes y convierte comillas inteligentes en entidades XML (“ etc.) para que sobrevivan a la edición. Use --merge-runs false para omitir la fusión de ejecuciones.
Paso 2: Editar XML
Edite los archivos en unpacked/word/. Consulte la Referencia XML a continuación para conocer los patrones.
Use "Claude" como autor para cambios controlados y comentarios, a menos que el usuario solicite explícitamente usar un nombre diferente.
Use la herramienta Editar directamente para el reemplazo de cadenas. No escriba scripts de Python. Los scripts introducen complejidad innecesaria. La herramienta Editar muestra exactamente lo que se está reemplazando.
CRÍTICO: Use comillas inteligentes para contenido nuevo. Al agregar texto con apóstrofos o comillas, use entidades XML para producir comillas inteligentes:
<!-- Use estas entidades para tipografía profesional -->
<w:t>Aquí’s una cita: “Hola”</w:t>
| Entidad | Carácter |
|---|---|
‘ | ‘ (comilla simple izquierda) |
’ | ’ (comilla simple derecha / apóstrofo) |
“ | “ (comilla doble izquierda) |
” | ” (comilla doble derecha) |
Agregar comentarios: Use comment.py para manejar el código repetitivo en múltiples archivos XML (el texto debe estar previamente escapado en XML):
python scripts/comment.py unpacked/ 0 "Texto del comentario con & y ’"
python scripts/comment.py unpacked/ 1 "Texto de respuesta" --parent 0 # responder al comentario 0
python scripts/comment.py unpacked/ 0 "Texto" --author "Autor personalizado" # nombre de autor personalizado
Luego agregue marcadores a document.xml (consulte Comentarios en la Referencia XML).
Paso 3: Empaquetar
python scripts/office/pack.py unpacked/ output.docx --original document.docx
Valida con reparación automática, condensa XML y crea el archivo de salida.
Referencia XML
Elementos comunes del cuerpo del documento
<w:p> <!-- Párrafo -->
<w:pPr> <!-- Propiedades del párrafo -->
<w:pStyle w:val="Heading1"/> <!-- Estilo de párrafo -->
<w:rPr>...</w:rPr> <!-- Ejecución predeterminada para TODO el párrafo -->
</w:pPr>
<w:r> <!-- Ejecución ->
<w:rPr> <!-- Propiedades de ejecución (anula pPr.rPr) -->
<w:b/> <!-- Negrita -->
<w:i/> <!-- Cursiva -->
<w:u w:val="single"/> <!-- Subrayado -->
<w:color w:val="FF0000"/> <!-- Color -->
<w:sz w:val="24"/> <!-- Tamaño en medios puntos (24 = 12pt) -->
</w:rPr>
<w:t>Texto</w:t> <!-- Contenido del texto -->
</w:r>
</w:p>
Propiedades del párrafo (w:pPr):
| Elemento | Propósito | Atributos |
|---|---|---|
w:jc | Alineación | w:val="left" / "center" / "right" / "both" |
w:spacing | Espaciado | w:before, w:after, w:line (240 = espaciado simple) |
w:ind | Sangría | w:left, w:right, w:firstLine, w:hanging (en DXA) |
w:outlineLvl | Nivel de esquema | w:val="0" (requerido para TOC) |
w:pageBreakBefore | Salto de página antes | sin atributos |
Propiedades de ejecución (w:rPr):
Consulte las propiedades de ejecución de ejemplo anteriores.
Listas (Numeración)
CRÍTICO: Las listas con viñetas deben usar numeración, no caracteres de viñeta Unicode.
Definiciones numéricas en numbering.xml. Los párrafos en document.xml hacen referencia a ellas:
<w:p>
<w:pPr>
<w:numPr>
<w:ilvl w:val="0"/> <!-- Nivel de lista -->
<w:numId w:val="1"/> <!-- ID del número -->
</w:numPr>
</w:pPr>
<w:r><w:t>Elemento de viñeta</w:t></w:r>
</w:p>
Para reiniciar la numeración, cree una nueva w:num en numbering.xml (w:numId debe ser único) que apunte a la misma w:abstractNumId.
Tablas
<w:tbl> <!-- Tabla -->
<w:tblPr> <!-- Propiedades de la tabla -->
<w:tblW w:w="9360" w:type="dxa"/> <!-- Ancho de la tabla (use dxa NO pct) -->
</w:tblPr>
<w:tblGrid> <!-- Definiciones de columnas -->
<w:gridCol w:w="4680"/> <!-- Ancho de columna en DXA -->
<w:gridCol w:w="4680"/>
</w:tblGrid>
<w:tr> <!-- Fila de tabla -->
<w:tc> <!-- Celda de tabla -->
<w:tcPr> <!-- Propiedades de la celda -->
<w:tcW w:w="4680" w:type="dxa"/> <!-- Ancho de celda -->
<w:shd w:fill="D5E8F0" w:val="clear"/> <!-- Sombreado -->
<w:tcMar> <!-- Márgenes de celda -->
<w:top w:w="80" w:type="dxa"/>
<w:bottom w:w="80" w:type="dxa"/>
<w:start w:w="120" w:type="dxa"/>
<w:end w:w="120" w:type="dxa"/>
</w:tcMar>
</w:tcPr>
<w:p><w:r><w:t>Celda</w:t></w:r></w:p>
</w:tc>
</w:tr>
</w:tbl>
Bordes
<!-- Borde de párrafo (use en lugar de tablas para líneas divisorias) -->
<w:pPr>
<w:pBdr>
<w:bottom w:val="single" w:sz="6" w:space="1" w:color="2E75B6"/>
</w:pBdr>
</w:pPr>
<!-- Bordes de tabla con estilo -->
<w:tblBorders>
<w:top w:val="single" w:sz="4" w:space="0" w:color="CCCCCC"/>
<w:bottom w:val="single" w:sz="4" w:space="0" w:color="CCCCCC"/>
<w:left w:val="single" w:sz="4" w:space="0" w:color="CCCCCC"/>
<w:right w:val="single" w:sz="4" w:space="0" w:color="CCCCCC"/>
</w:tblBorders>
Imágenes
<w:drawing>
<wp:inline distT="0" distB="0" distL="0" distR="0">
<wp:extent cx="2000000" cy="1500000"/> <!-- Tamaño en EMU (1" = 914400 EMU) -->
<wp:effectExtent l="0" t="0" r="0" b="0"/>
<wp:docPr id="1" name="Imagen 1" title="Título" descr="Descripción"/>
<a:graphic>
<a:graphicData uri="...">
<pic:pic>
<pic:blipFill>
<a:blip r:embed="rId1"/> <!-- Referencia a la relación de imagen -->
</pic:blipFill>
<pic:spPr>
<a:xfrm><a:off x="0" y="0"/><a:ext cx="2000000" cy="1500000"/></a:xfrm>
<a:prstGeom prst="rect"/>
</pic:spPr>
</pic:pic>
</a:graphicData>
</a:graphic>
</wp:inline>
</w:drawing>
Hipervínculos
Los hipervínculos externos requieren una relación en word/_rels/document.xml.rels, luego:
<w:hyperlink r:id="rId5" w:history="1">
<w:r><w:rPr><w:rStyle w:val="Hyperlink"/></w:rPr><w:t>Haga clic aquí</w:t></w:r>
</w:hyperlink>
Hipervínculos internos (marcador en destino, w:hyperlink w:anchor="chapter1" en el enlace).
Marcadores
<!-- Destino del marcador -->
<w:bookmarkStart w:id="0" w:name="chapter1"/>
<w:r><w:t>Capítulo 1</w:t></w:r>
<w:bookmarkEnd w:id="0"/>
Comentarios (Track Changes)
<!-- Iniciar comentario (insertar alrededor del texto) -->
<w:commentRangeStart w:id="0"/>
<w:r><w:t>Texto del comentario</w:t></w:r>
<w:commentRangeEnd w:id="0"/>
<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr>
<w:commentReference w:id="0"/></w:r>
El contenido del comentario en sí reside en comments.xml:
<w:comments>
<w:comment w:id="0" w:author="Claude" w:date="2024-01-01T00:00:00Z">
<w:p><w:r><w:t>Texto del comentario</w:t></w:r></w:p>
</w:comment>
</w:comments>
Cambios controlados
<!-- Insertar -->
<w:ins w:id="1" w:author="Claude" w:date="2024-01-01T00:00:00Z">
<w:r><w:t>texto insertado</w:t></w:r>
</w:ins>
<!-- Eliminar -->
<w:del w:id="2" w:author="Claude" w:date="2024-01-01T00:00:00Z">
<w:r><w:delText>texto eliminado</w:delText></w:r>
</w:del>
<!-- Propiedades de párrafo modificadas (uso de w:pPrChange dentro de w:pPr) -->
<w:pPr>
<w:jc w:val="center"/>
<w:pPrChange w:id="3" w:author="Claude" w:date="2024-01-01T00:00:00Z">
<w:pPr><w:jc w:val="left"/></w:pPr>
</w:pPrChange>
</w:pPr>
Tabla de contenido (TOC)
<w:sdt>
<w:sdtPr>
<w:docPartObj><w:docPartGallery w:val="Tabla de contenido"/></w:docPartObj>
</w:sdtPr>
<w:sdtContent>
<w:p><w:r><w:t>Tabla de contenido</w:t></w:r></w:p>
<w:p><w:r><w:tab/><w:fldChar w:fldCharType="begin"/></w:r>
<w:r><w:instrText> TOC \o "1-3" \h \z \u </w:instrText></w:r>
<w:r><w:fldChar w:fldCharType="separate"/></w:r>
<w:r><w:t>Campos del TOC...</w:t></w:r>
<w:r><w:fldChar w:fldCharType="end"/></w:r></w:p>
</w:sdtContent>
</w:sdt>