DoHyun468/claw-hwp / plugins/claw-hwp/skills/hwp
hwp
Unverifiedreferences/hwpx-object-placement.md
View on GitHub# HWPX 객체 배치 매뉴얼 — wrap / position / size / margin 올바르게 고르기
차트·이미지·도형·표 같은 객체를 본문에 넣을 때, **무엇을 넣느냐에 따라 배치(wrap) 모드와
크기·여백·위치를 맞춰야** 자연스럽게 나온다. 옵션이 나쁜 게 아니라 **상황에 안 맞는 설정**이
문서를 깨뜨린다(예: 전폭 차트를 `square`로 넣으면 글이 흐를 자리가 없어 섹션이 옆으로 밀려 깨짐).
아래는 모든 모드를 한컴 docs web 렌더로 검증한 레시피다(2026-06-19).
적용 op: `insert_chart`/`insert_shape`는 `wrap`·`x_mm`·`y_mm`·`margin_mm`을 직접 받음.
`insert_image`/`insert_equation`은 인라인 고정 → 다른 배치가 필요하면 삽입 후 `set_object_position`
(`target`, `index`, `x_mm?`, `y_mm?`, `wrap?`)으로 바꾼다. `set_table_props`(표)·`set_object_*`도
동일 enum.
## 한눈 결정표 — "무엇을 넣나" → 모드 + 설정
| 넣는 것 / 의도 | wrap | 크기·위치·여백 |
|---|---|---|
| 보고서 도표·그래프(섹션 안 그림) | **inline**(기본) | 전폭 ~110–120mm, 자기 줄. 가장 안전·예측가능 |
| 전폭 그림 한 줄 띄워 배치 | **topbottom** | 폭 자유, 글은 위/아래만. inline과 함께 깔끔 |
| 좁은 사진·미니 차트 옆에 글 흐르기(잡지식) | **square** | **폭 ≤ 60mm 필수**, `margin_mm:3`, 한쪽(좌/우) 정렬 |
| 워터마크·강조 배경 밴드(글 뒤) | **behind** | **연한 색**(글 안 가리게), `x_mm`/`y_mm`로 위치 지정 |
| 도장·콜아웃·말풍선(내용 위 오버레이) | **front** | 작게, `x_mm`/`y_mm`로 빈 자리에 배치 |
| 표 | (블록) | `insert_table`는 자체 문단=블록. wrap 불필요(자리차지 기본) |
## 모드별 레시피 (검증됨)
### inline (글자처럼) — **기본값**, 도표/그림 99%는 이걸로
- 객체가 **삽입한 그 자리·자기 줄**에 박히고 글은 위/아래로만 흐름. 뒤 페이지로 안 떠내려감.
- `insert_chart`는 자체 문단을 만들어 넣으므로 차트가 한 줄 독차지(가운데/좌측). 폭 110–120mm 무난.
- 셀 안 객체(`set_cell_*`)도 전부 inline.
- 함정 없음. 고민되면 inline.
### topbottom (자리차지) — 전폭 그림을 띄워 배치
- 플로팅이지만 **좌우로 글이 안 흐름**(위/아래만). 전폭 차트/그림에 깔끔.
- inline과 결과 비슷. 단 플로팅이라 위치가 약간 이동할 수 있음 → 자리 고정 원하면 inline.
### square (어울림) — **좁은 객체 + 긴 문단**일 때만
- 객체 옆으로 글이 흐른다(잡지 레이아웃). **반드시 좁게**: `width_mm ≤ 60`.
- `margin_mm:3`(글-객체 간격) 주고, 좌/우 한쪽에 둔다.
- 옆에 흐를 **문단이 충분히 길어야** 자연스럽다(짧은 불릿 옆 square는 어색).
- ❌ 안티패턴: 전폭(>100mm) 객체 + square → 글 흐를 폭이 없어 섹션 제목이 좁은 칸으로 밀려 깨짐.
- 검증: 55mm 파이차트 + margin 3 → 본문이 오른쪽으로 자연스럽게 흐름.
### behind (글 뒤) — 워터마크·강조 배경
- 객체가 **글 아래** 깔림. 글을 가리지 않으려면 **연한 색/투명 이미지**.
- 위치를 `x_mm`/`y_mm`로 지정(미지정 시 0,0에 겹침). 도형이면 연한 `fill_color`(예: `EEF2F9`).
- 검증: 연한 파랑 밴드(150×40mm, EEF2F9, x20 y60) → 글이 그 위로 읽힘(강조 배경).
### front (글 앞) — 콜아웃·도장 오버레이
- 객체가 **글 위에** 뜸. 내용을 가리므로 **작게 + 빈 자리에** 위치 지정 필수.
- 검증: 주황 콜아웃(70×22mm, x120 y40) → 우측 여백 위에 오버레이.
#### floating(앞으로) 위치 모델 — 실측 (front/square/behind 공통, 도장뿐 아니라 모든 띄움 객체)
한컴 렌더로 직접 측정한 좌표 규칙. 띄움 객체를 의도한 자리에 보내려면 이걸 알아야 한다.
- **좌표 프레임(위치 기준)**: 오프셋 (0,0)이 가는 원점 —
- `para`(문단) = **앵커 문단** 좌상단. ⚠️ **그 문단 top 위로는 못 올라감(클램프)** → 한 줄짜리 본문에선 객체가 줄에 걸려 **아래로만** 삐져나옴(줄 세로중앙에 못 맞춤).
- `page`(쪽) = **본문영역** 좌상단(여백 안쪽, A4 기본 ≈ 30.4, 35.7mm). **문단 클램프 없음** → 절대좌표(`x_mm`/`y_mm`)로 줄 위 어디든·정중앙 배치 가능.
- `paper`(종이) = 물리 용지 (0,0) 코너.
- **⚠️ flowWithText 가 켜지면 "앞으로"인데도 표/칸이 커진다**: floating(글자처럼취급 해제)이라도 `flowWithText="1"`이면 한컴이 객체 높이만큼 셀/문단에 세로공간을 예약 → **셀 행·페이지가 부풂**. 표/페이지를 안 키우려면 `flowWithText="0"`(고정) — 그럼 큰 객체는 칸 밖으로 **삐져나옴(peek)**.
- **표 셀 안 띄움 객체의 원점은 "셀"이 아니라 "표"**(표 top·텍스트영역 left). 특정 셀에 보내려면 앞 열 폭 합 + 앞 행 높이 합 + 표/셀 여백을 더해야 함. (셀엔 클램프 없음 → 위아래 자유.)
- **가로세로비**: 띄움 이미지는 원본 비율 유지(정사각 강제 금지). 폭이 칸/여유보다 크면 줄여서 안 넘치게.
- 줄 위 세로중앙이 필요하면 `page` 프레임 + 절대 Y. 칸(셀) 안은 클램프 없어 기본 배치로도 중앙 OK.
## 크기·여백·위치 레퍼런스
- **size**: `width_mm`/`height_mm`(mm). 본문 전폭 ≈ 150mm(A4 좌우 여백 제외). 전폭 도표 110–120mm,
square용 좁은 객체 ≤60mm, 셀 안은 셀폭 자동맞춤.
- **margin_mm**: 객체-글 바깥 간격. inline/topbottom은 2~3mm로 충분, square는 3mm 권장(안 주면 글이 붙음).
- **position(`x_mm`,`y_mm`)**: 오프셋. floating(square/behind/front)에서만 의미. inline은 위치 무시(글 흐름 따라감).
- **`frame`(`para`/`page`/`paper`/`column`)**: x/y의 기준 원점 — para=앵커 문단 좌상단(⚠️문단 top 위로 클램프), page=본문영역 좌상단, paper=용지 코너, column=단. **줄 위로 자유롭게 올리려면 page/paper**(para는 클램프). `set_object_position`에서 지정.
- **no-grow 자동**: `set_object_position`/`insert_*`로 wrap을 floating(front/square/…)으로 주면 `flowWithText="0"`가 자동 적용돼 **표/페이지가 안 커진다**(front라도 flowWithText=1이면 커지는 한컴 동작 회피). inline으로 주면 글자처럼 줄에 들어감.
- **여러 객체 겹침**: 같은 index에 floating 객체 여러 개 = 겹침 → index를 다르게 하거나 x/y로 분리.
## 페이지 채우기(밀도) 팁
- 1페이지 꽉: 본문 흐름형 문서는 `index`(문단 번호)로 차트·표·이미지를 앞쪽(6~12)에 넣어 page1에 packed.
표는 `insert_table cells`로 행·열 대량 채움 + 중첩 폼 그리드는 `set_cell_text`(표 index=`--inspect`).
- ⚠️ index 없이 넣으면 문서 **맨 끝**에 붙음(긴 보도자료는 8~9쪽 뒤로 묻힘). 본문 배치는 반드시 index 지정.
- 보도자료처럼 머리글이 표/프레임인 문서는 머리글 사이로 끼어 어색 → 본문 시작 이후 index를 노려라.
관련: `hwpx-edit-ops.md`(op 시그니처), 메모리 [[hwpx-nested-table-cellops]].
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |