dom-docx: HTML을 네이티브 편집 가능한 Word 문서로 변환

dom-docx: HTML을 네이티브 편집 가능한 Word 문서로 변환

개요

dom-docx는 시맨틱 HTML 조각을 네이티브하고 편집 가능한 Word 문서(OOXML)로 변환하도록 설계된 TypeScript 라이브러리입니다. 스크린샷이나 레이아웃 편법을 사용하는 도구와 달리, dom-docx는 단락, 런(run), 목록, 표와 같은 실제 Word 구조를 생성하여 결과 문서가 Microsoft Word 및 LibreOffice에서 완전히 편집 가능하도록 보장합니다.

핵심 기능

지원되는 HTML 요소

기본 inline 모드에서 이 라이브러리는 광범위한 시맨틱 HTML을 지원합니다:

  • 텍스트 및 구조: 제목, 단락, 목록 (<ul>, <ol>), 그리고 인용구.
  • 서식: 인라인 서식 (<strong>, <em>), 링크, 그리고 수평선 (<hr>).
  • 인용 및 레이아웃: 데이터 표, 음영 처리된 콜아웃, 그리고 간단한 flex 행(최대 4개 항목).
  • 시각적 요소: data: 이미지 및 저복잡도 인라인 SVG(특히 막대 및 텍스트).

고급 렌더링 옵션

스타일 및 복잡성에 대한 요구 사항에 따라 dom-docx는 변환을 위한 세 가지 별도의 경로를 제공합니다:

  1. 인라인 스타일 결정 (styleSource: "inline"): 기본값이며 순수 JavaScript 경로입니다. style="" 속성을 직접 파싱하며 브라우저 환경이 필요하지 않습니다.
  2. 계산된 스타일 결정 (styleSource: "computed"): getComputedStyle을 사용하여 <style> 블록, 클래스 및 ID 선택자를 결정합니다.
    • Node.js 환경: 헤드리스 방식으로 조각을 렌더링하기 위해 Playwright 및 Chromium이 필요합니다.
    • 브라우저 환경: 사용자의 탭에 있는 라이브 DOM을 사용하므로 추가 설치가 필요하지 않습니다.
  3. 래스터화 (rasterizeInPlace): 변환 전에 <canvas> 및 복잡한 <svg>(예: Highcharts)를 PNG 이미지로 변환합니다. 이는 복잡한 차트를 위해 권장되며, 고밀도 출력을 위해 scale: 2를 권장합니다.

기술 아키텍처

변환 파이프라인

라이브러리는 3단계 프로세스를 통해 HTML을 OOXML로 매핑합니다:

  1. 스타일 결정: 인라인 속성 또는 브라우저 계산된 스타일을 통해 최종 스타일을 결정합니다.
  2. 방문자 패턴 (Visitor Pattern): HTML 요소를 docx 단락, 표, 번호 매기기 및 하이퍼링크로 변환하는 Cheerio 워크(walk).
  3. 패키징 및 패치 (Pack & Patch): OOXML을 생성하고, Word 및 LibreOffice PDF 내보내기 시 목록 번호 매기기 및 음영 블록 정렬이 일관되게 유지되도록 패치를 적용합니다.

시각적 회귀를 통한 품질 보증

저자는 충실도를 반복적으로 개선하는 자율 루프인 "Autoresearch" 패턴을 사용하여 dom-docx를 개발했습니다. 이 프로세스는 다음을 포함합니다:

  • Chromium에서 HTML 렌더링.
  • dom-docx를 통해 HTML을 .docx로 변환.
  • LibreOffice를 사용하여 .docx 파일을 래스터화.
  • 브라우저 스크린샷과 LibreOffice 스크린샷을 비교하여 레이아웃 충실도, 편집 가능성 및 속도를 점수화함.

이 루프는 인간의 품질 평가와 높은 일치도를 보장하기 위해 37개의 실제 HTML 패턴을 대상으로 실행되었습니다.

통합 및 사용법

설치

npm install dom-docx

참고: Node.js ≥ 20이 필요합니다. Playwright는 계산된 스타일 또는 Node에서의 래스터화를 위해 사용되는 선택적 peer dependency입니다.

빠른 시작 예제

브라우저 사용 (순수 JS, Playwright 미사용):

import { convertHtmlToDocx } from "dom-docx/browser";

const html = `<h1 style="color:#1a1a2e">Quarterly Report</h1><p>Revenue grew <strong>12%</strong> year over year.</p>`;
const blob = await convertHtmlToDocx(html);
const a = document.createElement("a");
a.href = URL.createObjectURL(blob);
a.download = "output.docx";
a.click();

Node.js 사용:

import { writeFile } from "node:fs/promises";
import { convertHtmlToDocx } from "dom-docx";

const html = `<h1 style="color:#1a1a2e">Quarterly Report</h1><p>Revenue grew <strong>12%</strong> year over year`;
const docx = await convertHtmlToDocx(html);
await writeFile("output.docx", docx);

CLI 도구

코드 없이 빠른 변환을 위해 라이브러리는 CLI를 제공합니다:

npx dom-docx input.html -o output.docx

제한 사항

0.1.x 버전에서는 다음 기능이 지원되지 않습니다:

  • inline 경로에서의 외부 스타일시트.
  • Web 폰트, CSS grid, float 레이아웃, 및 absolute positioning.
  • Forms, <dl>, 및 table rowspan.
  • 복잡한 SVG 경로 및 그라데이션 ( rasterizeInPlace를 사용하지 않는 한).
  • 보장된 다중 페이지 레이아웃 충실도 또는 첫 페이지/짝수 페이지를 위한 특정 헤더/푸터 변형.

Sources