한글(HWP) COM 자동화 가이드¶

비개발자용. DOCX를 한글 파일(HWP)로 자동 변환하는 방법.

핵심 결론¶

DOCX를 먼저 완성하고, 한글 COM으로 열어서 HWP로 저장하는 게 정답. 한글 COM으로 직접 표/글꼴/배경색을 제어하면 디자인이 깨진다.

비유: 워드 문서를 "한글에서 열기 > 다른 이름으로 저장"하는 걸 코드로 하는 것.

환경¶

한글 2024 (v13, C:\Program Files (x86)\HNC\Office 2024\)
Python: pip install pywin32
한글이 설치되어 있어야 COM 객체가 등록됨

코드 템플릿 (DOCX -> HWP 변환)¶

import win32com.client

# 한글 실행
hwp = win32com.client.Dispatch('HWPFrame.HwpObject')
hwp.XHwpWindows.Item(0).Visible = True
hwp.RegisterModule("FilePathCheckDLL", "FilePathCheckerModule")

# DOCX 열기
hwp.HAction.GetDefault("FileOpen", hwp.HParameterSet.HFileOpenSave.HSet)
hwp.HParameterSet.HFileOpenSave.filename = r"D:\path\to\input.docx"
hwp.HParameterSet.HFileOpenSave.Format = "DOCX"
hwp.HAction.Execute("FileOpen", hwp.HParameterSet.HFileOpenSave.HSet)

# HWP로 저장
hwp.HAction.GetDefault("FileSaveAs_S", hwp.HParameterSet.HFileSaveAs.HSet)
hwp.HParameterSet.HFileSaveAs.SaveFileName = r"D:\path\to\output.hwp"
hwp.HParameterSet.HFileSaveAs.SaveFormat = "HWP"
hwp.HParameterSet.HFileSaveAs.SaveOverWrite = True
hwp.HAction.Execute("FileSaveAs_S", hwp.HParameterSet.HFileSaveAs.HSet)

주의사항 체크리스트¶

반드시 지킬 것¶

[ ] Dispatch 사용 (gencache.EnsureDispatch 쓰면 캐시 꼬여서 에러남)
[ ] RegisterModule 호출 (안 하면 파일 열기/저장 시 보안 차단)
[ ] 실행 전 기존 한글 프로세스 종료: taskkill /f /im Hwp.exe
[ ] filename 속성 사용 (소문자! OpenFileName은 에러남)

COM 직접 제어가 필요한 경우 (변환 후 추가 수정 등)¶

TableCreate는 CreateAction 방식만 사용
hwp.CreateAction("TableCreate") + act.CreateSet() + act.Execute(ts)
HParameterSet.HTableCreation 방식은 두 번째 표부터 서버 크래시 (RPC_E_SERVERFAULT)
표 너비: WidthValue + CreateItemArray("ColWidth", 1) 필수 (안 하면 너비 0)
액션 이름: ParagraphShape (O) vs ParaShape (X)
셀 테두리: BorderCorlorLeft (오타 아님, API 원래 이름)
페이지: PaperType 없음, PaperWidth/PaperHeight 직접 설정

단위 변환¶

변환	결과	참고
`hwp.MiliToHwpUnit(10)`	2834	10mm
`hwp.PointToHwpUnit(12)`	1200	12pt
A4 너비	`MiliToHwpUnit(210)`	59514
본문 너비 (여백 33mm)	`MiliToHwpUnit(144)`	40818

실전 사례¶

31기 기획안 양식 (ebook-project)¶

DOCX: node build_plan_31.js (docx-js로 디자인 완성)
HWP: python build_plan_31_hwp.py (DOCX를 열어서 HWP 저장)
배너, 예시박스, 색상, 글꼴 모두 정상 변환됨

왜 직접 제어를 포기했나¶

배경색: CellBorderFill.FillAttr.WinBrushFaceColor 설정해도 안 먹음
글꼴 크기: CharShape로 설정해도 일부만 적용, 나머지 뒤죽박죽
표: HParameterSet 방식으로 두 번째 표 만들면 한글 프로세스 자체가 크래시
결론: COM API가 불안정 -> DOCX 변환이 가장 안정적

다른 포맷도 가능¶

# PDF로도 저장 가능
hwp.HParameterSet.HFileSaveAs.SaveFormat = "PDF"

# HWP -> DOCX로 역변환도 가능
hwp.HParameterSet.HFileSaveAs.SaveFormat = "DOCX"

워크플로우 정리¶

DOCX 빌드 (node/python)
    │
    ▼
한글 COM으로 DOCX 열기
    │
    ▼
(필요시) COM으로 추가 수정
    │
    ▼
HWP로 저장
    │
    ▼
사용자가 한글에서 최종 확인