ownhwpx

📦 설치 Installation

npm을 통해 간단히 설치할 수 있습니다.

Install via npm.

npm install ownhwpx

Node.js 18 이상이 필요합니다.

Requires Node.js 18 or later.

🚀 빠른 시작 Quick Start

HWPX 문서를 읽고 텍스트를 추출하는 기본 예제입니다.

Basic example: read a HWPX document and extract text.

문서 읽기 · Read a Document

import { HWPXReader } from 'ownhwpx'

const doc = HWPXReader.fromFilepath('document.hwpx')
console.log(`Sections: ${doc.sectionXMLFileList.length}`)

const section = doc.sectionXMLFileList.get(0)
for (let i = 0; i < section.paraListCore.count; i++) {
  const para = section.paraListCore.getPara(i)
  console.log(`Paragraph ${i}: ${para.runList.length} runs`)
}

문서 쓰기 · Write a Document

import { HWPXWriter, BlankFileMaker } from 'ownhwpx'

// 빈 문서 생성
const blank = BlankFileMaker.make()
await HWPXWriter.toFilepath(blank, 'blank.hwpx')

// 수정된 문서 저장
await HWPXWriter.toFilepath(doc, 'output.hwpx')

텍스트 추출 · Extract Text

import { TextExtractor, TextExtractMethod } from 'ownhwpx'

const text = TextExtractor.extract(
  doc,
  TextExtractMethod.AppendControlTextAfterParagraphText,
  true,
  null
)
console.log(text)

📚 API 문서 API Reference

ownhwpx가 제공하는 주요 클래스와 메서드입니다.

Key classes and methods provided by ownhwpx.

💡 사용 예제 Usage Examples

템플릿 · Templates

import { TemplateEngine, BlankFileMaker } from 'ownhwpx'

const blank = BlankFileMaker.make()
const section = blank.sectionXMLFileList.get(0)
const para = section.paraListCore.getPara(0)

para.addNewRun().addNewT().addText('Hello, {{name}}!')

TemplateEngine.render(blank, { name: 'World' })
// 문서의 {{name}}이 'World'로 치환됨

표 생성 · Tables

import { TableFromArray } from 'ownhwpx'

const table = TableFromArray.make([
  ['Name', 'Age', 'City'],
  ['Alice', '30', 'Seoul'],
  ['Bob', '25', 'Busan'],
], { headerRows: 1 })

// 문단에 표 추가
para.addNewRun().addItem(table)

목차 · Table of Contents

import { TocMaker } from 'ownhwpx'

const entries = TocMaker.generate(doc)
console.log(entries)

TocMaker.insertToc(doc, {
  tocTitle: 'Table of Contents',
  maxLevel: 3,
})

객체 검색 · Object Search

import { ObjectFinder, ObjectType } from 'ownhwpx'

const results = ObjectFinder.find(doc, {
  isMatched: obj => obj.objectType() === ObjectType.hp_fieldBegin
}, false)

필드 검색 · Field Search

import { FieldFinder } from 'ownhwpx'

const results = FieldFinder.find(doc, 'CustomerName', false)
for (const r of results) {
  console.log(r.beginField?.name, r.endField?.beginIDRef)
}

가로선 · Horizontal Rule

import { HrMaker, LineWidth, LineType2 } from 'ownhwpx'

HrMaker.insertAfter(para, {
  thickness: LineWidth.MM_0_4,
  color: '#CCCCCC',
})

구역 나누기 · Section Break

import { SectionBreakMaker } from 'ownhwpx'

// 새 구역 추가 (가로 레이아웃)
SectionBreakMaker.append(doc, { landscape: true })

// 특정 위치에 구역 삽입
SectionBreakMaker.insertAt(doc, 1, { marginTop: 3000 })

🎮 라이브 문서 생성 · Live Document Generator

sample01.hwpx를 템플릿으로 불러와 JSON 데이터로 {{variable}}를 치환합니다.
Loads sample01.hwpx as a template and renders {{variable}} placeholders with your JSON data.
✅ 템플릿은 {{variable}} 텍스트 치환 방식과 누름틀(CLICK_HERE) 필드 방식을 모두 지원합니다.
✅ The template supports both {{variable}} text substitution and CLICK_HERE field (누름틀) approaches.

POST /api/render-hwpx
Content-Type: application/json

{
  "template": "본문 내용 {{variable}}...",
  "data": {
    "contractDate": "2026-07-11",
    "clientName": "홍길동",
    "items": [
      { "name": "디자인", "qty": 1, "price": 500000 }
    ],
    "amount": "500,000",
    "signature": "홍길동"
  }
}

→ 200
{
  "text": "...",
  "hwpxBase64": "UEsDBBQAAAAIA...",
  "size": 12345
}

📑 목차 생성 · Table of Contents

템플릿 없이 제목 단계(Heading Level) 데이터로 목차가 포함된 문서를 생성합니다.
Generates a HWPX document with a table of contents without a template — headings and hierarchy only.

POST /api/generate-toc
Content-Type: application/json

{
  "title": "프로젝트 계획서",
  "entries": [
    { "text": "개요", "level": 1 },
    { "text": "배경", "level": 2 },
    { "text": "목표", "level": 2 },
    { "text": "세부 계획", "level": 1 },
    { "text": "일정", "level": 2 },
    { "text": "개발 단계", "level": 3 },
    { "text": "테스트 단계", "level": 3 },
    { "text": "예산", "level": 2 },
    { "text": "결론", "level": 1 }
  ]
}

→ 200
{
  "text": "...",
  "hwpxBase64": "UEsDBBQAAAAIA...",
  "size": 12345
}

📊 표 생성 · Table from Array

템플릿 없이 배열 데이터로 직접 표를 생성합니다.
Generates a table HWPX document without a template — headers and rows only.

POST /api/generate-table
Content-Type: application/json

{
  "headers": ["Name", "Age", "City"],
  "rows": [
    ["Alice", "30", "Seoul"],
    ["Bob", "25", "Busan"],
    ["Charlie", "35", "Incheon"]
  ]
}

→ 200
{
  "text": "...",
  "hwpxBase64": "UEsDBBQAAAAIA...",
  "size": 12345
}