> For AI agents: the complete documentation index is available at /hwpjs/llms.txt, the full documentation bundle is available at /hwpjs/llms-full.txt.

# 공개 API 직접 실행

샘플 API와 JSON 인수를 선택해 실제 반환값·오류·전후 상태를 확인하세요. 문서 열기·선택·입력·실행 취소·저장 흐름을 직접 살펴볼 수 있습니다.

이 도구는 함께 배포한 현재 개발 버전의 패키지·WASM을 사용합니다. 설치한 npm 버전의 지원 범위는 [패키지 이름과 게시 상태](/hwpjs/guide/package-names.md)에서 확인하세요.

## 쪽 텍스트 조회

`load`에 `{"format":"hwpx","fixture":"page"}`를 입력하고 실행하세요. `getPageText`를 선택하면 같은 Canvas에 표시된 문서에서 물리 쪽 인덱스와 본문·표·글상자·캡션을 선택할 수 있습니다. 첫 쪽은 0이며, 이 샘플의 쪽 2는 본문이 비어 있습니다. 글상자와 캡션을 비교하려면 `fixture`를 `textbox`로 바꾸세요. 두 샘플은 `format`을 `hwp5`로 바꿔도 실행할 수 있습니다. 표 셀 텍스트를 보려면 HWPX `multicolumns-layout` 샘플의 쪽 4에서 표를 선택하세요.

결과의 `complete`는 선택한 종류의 범위를 확인했음을 뜻합니다. `partial`이면 반환된 텍스트와 함께 `issues`에 범위 제한이 표시됩니다. `unavailable`에는 현재 쪽을 읽을 수 없는 이유가 표시됩니다.

## HWPX 누름틀 만들기

패널에서 편집할 HWPX 파일을 열고 Canvas에서 본문 글자를 선택하거나 빈 입력 위치에 커서를 놓으세요. **현재 선택 가져오기**를 누른 뒤 이름, 안내문, 도움말을 입력하고 **누름틀 만들기**를 실행하세요. API의 `select`로 정한 선택도 사용할 수 있습니다.

문단 안의 한 텍스트 요소에 속한 선택을 지원합니다. 선택한 글자와 서식을 유지하며 빈 위치에는 빈 누름틀을 만듭니다. 보호된 필드와 겹치는 선택, 여러 요소에 걸친 선택이나 중복 이름은 생성할 수 없는 이유가 표시됩니다. 생성 후에는 같은 패널에서 값을 읽고 바꿀 수 있으며 실행 취소·다시 실행과 저장을 사용할 수 있습니다.

## 누름틀 안내문·도움말 수정

HWPX 파일을 연 뒤 필드 이름과 필요한 순번을 입력하고 **누름틀 속성 읽기**를 누르세요. 안내문과 도움말을 수정하고 **속성 적용**으로 저장합니다. 미지정(`null`)과 빈 문자열을 구분하며, 미지정 값을 비우려면 해당 확인란을 선택해야 합니다. 원문 텍스트와 필드 이름은 유지합니다.

파일을 수정하지 않고 확인하려면 패널의 **열기 모드 → 읽기 전용**을 선택하고 파일을 여세요. 보호 필드와 읽기 전용 문서에서도 지원되는 속성은 조회할 수 있고 적용은 비활성화됩니다. 다른 문서나 선택으로 바뀌면 속성을 다시 읽어야 합니다.

헤드리스 API는 `readNamedFieldParameters`와 `SET_NAMED_FIELD_PARAMETERS_COMMAND`를 사용합니다. `read` 결과의 `token`, `selectionVersion`, 기존 `parameters`를 수정 요청의 기대값으로 전달합니다. 문단 글머리표의 기존 선언 적용·해제는 `APPLY_FORMATTING_PATCH_COMMAND`의 `paragraph.bullet`를 사용합니다. 새 문자 선언의 생성·수정은 아래 typed 명령을 사용합니다.

## 문자 글머리표 정의 조회·생성·수정

이 연결은 **현재 GitHub 구현 기준**이며 npm 게시 버전을 뜻하지 않습니다. 공개 설치 이름은 `npm install @ohah/hwpjs`입니다. 새 기능은 해당 구현을 포함한 빌드가 필요합니다. [HeadlessEditor 예제](/hwpjs/api/editor.md#글머리표-정의-조회생성수정)의 import도 `@ohah/hwpjs`를 사용합니다.

`load`로 편집 가능한 HWPX를 열고 `listParagraphBulletDefinitions`를 실행하세요. 실제 Core가 현재 헤더 전체를 조회합니다. `scope: "current-header"`, `coverage: "complete"`, `definitionWriter: "character-definitions-v1"`을 확인하세요. 정의별 `canApply`는 현재 선택에 대한 쓰기 권한을 뜻하지 않습니다.

`editParagraphBulletDefinition`은 `target`에 `{ "section": 0, "paragraph": 1, "start": 0, "end": 0 }`처럼 현재 화면 문단 좌표를 명시합니다. 현재 엔진 상태의 `stateVersion`을 `selectionVersion`으로 전달하세요. 항목을 선택할 때 현재 버전을 예제에 채우며 문서·선택·이력 변경 후에는 다시 선택해 갱신해야 합니다. 실행 예제는 `createParagraphSelection`으로 같은 문서의 target을 발급한 후 `EDIT_PARAGRAPH_BULLET_DEFINITION_COMMAND`를 실행합니다.

`edit`는 `{ mode: "create", definition, apply: true }`입니다. 수정은 `{ mode: "update", id, definition, apply: false }`로 지정하며 동일 ID를 사용하는 모든 문단에 영향을 줍니다. definition의 필수 8개 값은 [API 계약](/hwpjs/api/editor.md#글머리표-정의-조회생성수정)을 따릅니다. 쓰기 오류·오래된 선택·읽기 전용·지원하지 않는 owner·구형 엔진의 writer 부재는 오류와 전후 상태로 확인합니다. HWP5 정의 쓰기는 지원하지 않습니다. 문서 교체나 패널 종료 후 이전 요청을 재사용하지 마세요.


API와 JSON 인수를 선택해 실제 엔진의 반환값·오류·전후 상태를 확인하세요.[별도 창에서 실행](/hwpjs/editor/api/index.html)

문서를 먼저 열고 전체 바꾸기를 실행하세요. `getReplaceAllCapabilities`는 가용성을 조회하고, `planReplaceAll`은 변경 계획만 표시합니다. `replaceAll`은 리터럴 일괄 교체를 실행합니다. 계획과 실행의 JSON에는 `query`와 `replacement`만 입력하세요.


[HeadlessEditor 가이드](/hwpjs/api/editor.md) · [선택과 서식](/hwpjs/api/selection.md) · [패키지 이름과 게시 상태](/hwpjs/guide/package-names.md)