Elements

문단, run, 표, 셀을 위한 값 객체

“Element” 란?

Element 는 컬렉션을 subscript 했을 때 얻는 가벼운 객체입니다. 문서의 한 항목 — 문단, run, 표 셀 — 을 감싸고 관심 있는 프로퍼티를 Pythonic 한 속성으로 노출합니다.

두 가지 규칙이 있습니다.

  1. 생성은 무료입니다. Element 는 소유 App 에 대한 참조와 좌표(인덱스, 이름, 행/열)를 감싼 것입니다. 속성을 읽기 전까지는 COM 을 건드리지 않습니다.
  2. 읽기는 라이브입니다. 모든 프로퍼티 getter 는 호출 시점에 HWP 를 참조합니다 — 캐싱은 없습니다. 문단 0 의 p.text = "…" 에 할당한 뒤 다시 p.text 를 읽으면 새 값이 나옵니다. 문서가 다른 경로로 변경되었다면(사용자 undo, 동시 스크립트), 현재 상태가 보입니다.

Element 카탈로그

타입 출처 주요 프로퍼티
Paragraph app.doc.paragraphs[i] .text, .style, .charshape, .parashape, .runs
Run paragraph.runs[j] .text, .charshape, .start, .end
Table app.doc.tables[k] .rows, .cols, .name, .cell(r, c)
Cell table.cell(r, c) .text, .row, .col, .border, .fill
Field app.doc.fields[n] .name, .value, .goto()
Bookmark app.doc.bookmarks[n] .name, .goto()

문단과 run

Paragraph 는 HWP 의 문단 구분자로 분리된 텍스트 한 블록입니다. 그 runs 는 하나의 CharShape 를 공유하는 연속된 슬라이스입니다 — 그래서 “굵게 와 기울임” 은 한 문단 위의 두 run 입니다.

p = app.doc.paragraphs[0]

p.text                  # → str (전체 문단)
p.style                 # → str (HWP 스타일 이름)
p.charshape             # → CharShape (아래 참고)
p.parashape             # → ParaShape

for r in p.runs:
    print(r.text, r.charshape.bold)

모양(shape) 설정

.charshape 또는 .parashape 에 할당하면 전체 문단(또는 run)에 서식이 적용됩니다.

from hwpapi.low.parametersets import CharShape, ParaShape

p = app.doc.paragraphs[0]

# charshape 통째로 교체
p.charshape = CharShape(Bold=True, Height=1400, TextColor="#C0392B")

# 또는 한 필드씩 설정 (현재 값 읽고, 편집한 뒤, 되쓰기)
current = p.charshape
current.Italic = True
p.charshape = current

이는 v1 의 app.set_charshape(...) 메서드의 후속입니다 — 마이그레이션 가이드 를 참고하세요.

선택적 순회

ParagraphCollection 은 .filter(predicate) 를 지원합니다.

headings = app.doc.paragraphs.filter(lambda p: p.style.startswith("제목"))
for h in headings:
    print(h.text)

표와 셀

Table element 는 행/열 기하 정보를 노출하고, Cell element 는 (행, 열) 로 주소가 지정됩니다.

tbl = app.doc.tables[0]

tbl.rows, tbl.cols
tbl.name

c = tbl.cell(0, 0)
c.text = "헤더"
c.fill = "#F5F5F5"
c.border = {"top": "thick", "bottom": "thick"}

값 vs. 참조 의미론

Element 는 항상 문서 상태에 대한 참조 이며, 결코 스냅샷이 아닙니다.

p = app.doc.paragraphs[0]
p.text                     # "hello"

app.doc.paragraphs[0]      # → 다른 Paragraph 인스턴스 …
app.doc.paragraphs[0].text # … 그러나 둘 다 문단 0 을 가리키므로 같은 텍스트

스냅샷이 필요하다면 — diff-and-restore 패턴 등 — 관심 있는 속성을 dataclass 나 dict 에 직접 복사하세요.

dataclass 가 아님

v1 코드베이스에는 추가로 표현 계층이 있었습니다. ParameterSet 클래스 옆에 @dataclass Paragraph / @dataclass CharShape / @dataclass PageShape 클래스들이 있었습니다. v2 는 dataclass 계층을 삭제하고 단일 Paragraph-as-reference 설계를 노출합니다. round-tripping 용으로 v1 dataclass 를 사용하고 있었다면, 다음을:

# v1
from hwpapi.classes.shapes import Paragraph as ParaDC
snap = ParaDC(text=p.text, style=p.style, ...)
# ... 편집 ...
p.text = snap.text

평범한 dict 로 교체하세요.

# v2
snap = {"text": p.text, "style": p.style}
# ... 편집 ...
p.text = snap["text"]

Element 표면은 의도적으로 작습니다 — 필요한 헬퍼는 직접 추가하세요.

더 보기

맨 위로