Создание, редактирование и анализ DOCX

.docx — это ZIP-архив XML-файлов. Выбирайте подход в зависимости от задачи:

Задача	Подход
Создать новый документ	Написать скрипт с использованием docx (npm) — см. предупреждения ниже
Редактировать существующий документ	unzip → редактировать word/document.xml → zip (docx-js не может открыть существующие файлы)
Прочитать содержимое	pandoc -t markdown file.docx

Пути к скриптам ниже относительно каталога этого навыка.

Создание с docx-js — предупреждения

docx предустановлен — не запускайте npm install сначала; пишите скрипт и используйте require('docx') напрямую. Только если этот require не сработает: npm install docx. Модель знает API; вот основные подводные камни:

• Размер страницы по умолчанию — A4. Для US Letter установите page: { size: { width: 12240, height: 15840 } } (DXA; 1440 = 1″).
• Альбомная ориентация: передайте портретные размеры и orientation: PageOrientation.LANDSCAPE — docx-js внутри меняет ширину и высоту местами.
• Таблицы требуют двойных ширин: задайте columnWidths для таблицы И width для каждой ячейки, оба в WidthType.DXA (PERCENTAGE ломается в Google Docs). Сумма ширин столбцов должна равняться ширине таблицы.
• Заливка таблицы: используйте ShadingType.CLEAR, никогда не SOLID (иначе будет чёрный цвет).
• Списки: никогда не вставляйте символ • напрямую; используйте конфигурацию numbering с LevelFormat.BULLET.
• ImageRun требует type: ("png", "jpg", …).
• PageBreak должен быть внутри Paragraph.
• Никогда не используйте \n — используйте отдельные элементы Paragraph.
• Оглавление: заголовки должны использовать встроенные HeadingLevel.*; для пользовательских стилей заголовков нужно задать outlineLevel, иначе они не появятся.
• Не используйте таблицу как горизонтальную линию — используйте нижнюю границу абзаца.
• Точки-лидеры / выравнивание по правому краю на одной строке: используйте PositionalTab (alignment: PositionalTabAlignment.RIGHT, leader: PositionalTabLeader.DOT) внутри TextRun, а не буквальные . или пробелы.

Проверка результата

После создания .docx откройте его и посмотрите:

python scripts/office/soffice.py --headless --convert-to pdf output.docx
pdftoppm -jpeg -r 100 output.pdf page
ls page-*.jpg   # затем просмотрите изображения

pdftoppm дополняет номера страниц нулями до ширины количества страниц (page-01.jpg…page-12.jpg).

Редактирование существующих документов

Файлы старого формата .doc нужно сначала конвертировать: python scripts/office/soffice.py --headless --convert-to docx file.doc.

unzip -q doc.docx -d unpacked/
find unpacked -type l -delete   # удаляем символические ссылки — docx из внешних источников ненадежен
python scripts/merge_runs.py unpacked/   # объединяем фрагментированные runs, чтобы текст был доступен для поиска
# редактируйте unpacked/word/document.xml на месте — НЕ форматируйте и не делайте pretty-print
(cd unpacked && rm -f ../out.docx && zip -Xr ../out.docx .)
python scripts/office/validate.py out.docx --original doc.docx   # проверка XSD; --auto-repair исправляет распространённые ошибки
# отслеживаемые изменения? добавьте --author "<имя, под которым вы делаете правки>", чтобы проверить, что каждое изменение отслеживается

Word разбивает текст на множество <w:r> (runs) (идентификаторы ревизий, метки проверки орфографии), поэтому фраза, видимая в документе, часто не существует как непрерывная строка в XML. merge_runs.py объединяет соседние runs с одинаковым форматированием в word/document.xml без изменения содержимого или отображения; он также принимает .docx напрямую (python scripts/merge_runs.py doc.docx -o merged.docx).

Отслеживаемые изменения: при редактировании с отслеживанием используйте --author "<имя, под которым вы редактируете>" (требуется --original) — это сообщает о любом изменённом тексте без обёртки <w:ins>/<w:del>, что легко сделать случайно и что невидимо в принятом виде. Оборачивайте runs в <w:ins>/<w:del> с атрибутами w:id, w:author, w:date. Внутри <w:del> текстовый элемент — <w:delText>, а не <w:t>. Удалённый знак абзаца (<w:pPr><w:rPr><w:del w:id=".." w:author=".." w:date=".."/></w:rPr></w:pPr>) означает «объединить этот абзац со следующим» — поэтому полное удаление абзаца — это это плюс <w:del> вокруг каждого run. <w:del/> должен идти перед другими дочерними элементами rPr; порядок задан схемой.

Чтобы получить чистую копию с принятыми всеми отслеживаемыми изменениями: python scripts/accept_changes.py in.docx out.docx.

Принятие удалённого знака абзаца должно объединить этот абзац с нижележащим, так что абзац, у которого все runs удалены, исчезает. Word делает это; accept_changes.py и pandoc --track-changes=accept делают это не всегда. Оба ведут себя одинаково — удаляют текст, но оставляют пустой абзац, который воспринимается как лишний пустой пункт при авто-нумерации:

• pandoc --track-changes=accept никогда не объединяет абзацы.
• accept_changes.py (LibreOffice) объединяет правильно, кроме случаев, когда удалённый абзац следует за пустым абзацем-разделителем.

Пустой пункт в любом виде — артефакт этого вида, а не дефект документа. Проверьте удаление абзацев в XML.

Комментарии

Комментарии требуют шести взаимосвязанных файлов. Используйте помощник — режим каталога, если вы также редактируете document.xml (экономит цикл распаковки/запаковки), режим прямой работы с .docx в остальных случаях:

# Для уже распакованного каталога (предпочтительно при добавлении маркеров)
python scripts/comment.py unpacked/ "Предел расходов слишком низок"
python scripts/comment.py unpacked/ "Согласовано" --parent 0

# Для .docx напрямую
python scripts/comment.py contract.docx "Этот предел слишком низок" -o annotated.docx

Скрипт создаёт comments.xml, commentsExtended.xml, commentsIds.xml, commentsExtensible.xml, связи и переопределения типов содержимого. ID комментариев назначаются автоматически. Затем он выводит фрагмент <w:commentRangeStart>/<w:commentRangeEnd>/<w:commentReference>, который нужно добавить в word/document.xml, чтобы привязать комментарий к конкретному тексту — пока вы не разместите эти маркеры, комментарий существует, но не виден.

Зависимости

docx (npm, предустановлен — устанавливайте только если require('docx') не работает) · pandoc · LibreOffice (soffice) · pdftoppm (Poppler)