Headers and footers

Insert page headers, footers, and page numbers programmatically

머리말(header) 과 꼬리말(footer) 은 HWP 의 컨트롤(HeaderFooter) 이라, 일반 문단 텍스트가 아닌 액션을 통해 만들어집니다. 이 레시피는 가장 자주 쓰는 머리말/꼬리말 시나리오 4가지를 묶어 보여줍니다.

1. 본문 상단에 머리말 텍스트 한 줄

from hwpapi import App

with App() as app:
    app.open("report.hwp")

    action = app.actions.HeaderFooter
    pset = action.pset
    pset.CtrlType = 0      # 0 = 머리말, 1 = 꼬리말
    pset.Type = 0          # 0 = 양쪽, 1 = 짝수쪽, 2 = 홀수쪽
    action.run(pset)

    # 액션 실행으로 머리말 영역에 커서가 들어옴 — 그냥 입력
    app.doc.insert_text("2026 Q1 — Internal Report")

    # 본문으로 복귀
    app.api.Run("CloseEx")

    app.save()

2. 페이지 번호가 들어간 꼬리말

from hwpapi import App

with App() as app:
    app.open("report.hwp")

    # 꼬리말 진입
    action = app.actions.HeaderFooter
    pset = action.pset
    pset.CtrlType = 1      # 꼬리말
    pset.Type = 0          # 양쪽
    action.run(pset)

    # 가운데 정렬 후 "n / total" 형식 페이지 번호
    app.api.Run("ParagraphShapeAlignCenter")
    app.api.Run("AutoChangeMode")              # 페이지 자동 변경 활성
    app.api.Run("InsertPageNum")               # 현재 페이지 번호
    app.doc.insert_text(" / ")
    app.api.Run("InsertPageCount")             # 총 페이지 수

    app.api.Run("CloseEx")
    app.save()

3. 짝수/홀수쪽 다른 머리말

양면 인쇄에서 흔한 패턴 — 짝수쪽엔 책 제목, 홀수쪽엔 장 제목.

from hwpapi import App

def insert_header(app, text: str, *, type_: int) -> None:
    """type_: 1=짝수쪽, 2=홀수쪽"""
    action = app.actions.HeaderFooter
    pset = action.pset
    pset.CtrlType = 0
    pset.Type = type_
    action.run(pset)

    app.api.Run(
        "ParagraphShapeAlignLeft" if type_ == 2 else "ParagraphShapeAlignRight"
    )
    app.doc.insert_text(text)
    app.api.Run("CloseEx")


with App() as app:
    app.open("book.hwp")
    insert_header(app, "한글 자동화 가이드", type_=1)        # 짝수
    insert_header(app, "Chapter 3 — Collections", type_=2)   # 홀수
    app.save()

4. 모든 머리말/꼬리말 지우기

from hwpapi import App

with App() as app:
    app.open("report.hwp")

    # 한 번 호출에 모든 머리말/꼬리말 컨트롤 제거
    app.api.Run("HeaderFooterDelete")

    app.save()

5. HeaderFooter ParameterSet 필드 요약

필드	의미	값
`CtrlType`	종류	`0` = 머리말, `1` = 꼬리말
`Type`	위치	`0` = 양쪽, `1` = 짝수쪽, `2` = 홀수쪽
`HeaderFooterCtrlType`	한글2007+ 종류	`0` = 머리말, `1` = 꼬리말
`HeaderFooterStyle`	마당 스타일	한글2007+
`DialogOption`	대화상자 “편집” 버튼 표시	`1` = 보이기
`DialogResult`	대화상자 결과	`1` = 만들기, `2` = 편집

전체 정의는 hwpapi/low/parametersets/sets/document.py:121 의 HeaderFooter 클래스 또는 Reference 페이지 에서 확인하세요.

See also