DOCSEARCHbyAlgolia
Submit Docs

hwp.js

repository·main·Indexed 23 days ago

https://github.com/hahnlee/hwp.js

An open-source library for viewing and parsing Hangul Word Processor (.hwp) files using web technologies. Built based on the official Hancom HWP file structure 5.0 documentation, it provides tools to parse HWP documents into structured programmatic models, including support for the FileHeader, document metadata, tables, shapes, and font classification via the Panose model.

Tokens
4.5K
Snippets
10
Records
32
Agent score
79%

What's inside hwp.js

  1. Overview of hwp.js

    main
    hwp.js is an open-source library powered by web technology designed to view and parse Hangul Word Processor (.hwp) files. It is developed based on the official Hancom HWP file structure 5.0 documentation.

  2. Interpret HWP file versions

    main

    The file version is a DWORD in the format 0xMMnnPPrr (e.g., 5.0.3.0). The components determine compatibility:

    • MM: Major format version. If this differs, the file is incompatible with older versions.
    • nn: Major structure version. If this differs, the file is incompatible with older versions.
    • PP: Record version. If this differs, the file is compatible with older versions (indicates new or incompatible records added).
    • rr: Revision version. If this differs, the file is compatible with older versions (indicates information added to records).

  3. Calculate Dimensions using HWPUNIT and SHWPUNIT

    main

    To represent sizes for characters, images, or page margins, HWP 5.0 uses HWPUNIT and SHWPUNIT. These units are based on 1/7200 of an inch to ensure consistent sizing regardless of device resolution.

    Conversion Example: To represent an image that is 2 inches wide by 1 inch high:

    • Width: $2 \text{ inches} \times 7200 = 14400$ HWPUNIT
    • Height: $1 \text{ inch} \times 7200 = 7200$ HWPUNIT

  4. Understand HWP 5.0 Data Types and Endianness

    main

    In HWP 5.0 files, information is stored using specific data types. All multi-byte data types use Little-endian byte ordering, meaning the least significant byte is stored first. One byte is defined as 8 bits.

    When data is represented as an array, it is denoted as DataType array[count]. For example, a word array with 10 elements is written as word array[10].

  5. Install hwp.js via npm or yarn

    main

    You can install the hwp.js library using either npm or yarn to use its HWP (Hangul Word Processor) viewer and parser capabilities in your web-based projects.

    npm install hwp.js
yarn add hwp.js

  6. Understand the HWP 5.0 FileHeader structure

    main

    The FileHeader stream is used to identify a file as an HWP document. It is a fixed-length structure of 256 bytes containing the signature, versioning, attributes, and encryption information.

    | 자료형            | 길이(바이트) | 설명 |
| --------------- |:---------:| -- |
| BYTE array[32]  | 32        | signature |
| DWORD           | 4         | 파일 버전 |
| DWORD           | 4         | 속성1 |
| DWORD           | 4         | 속성2 |
| DWORD           | 4         | EncryptVersion |
| BYTE            | 1         | 공공누리(KOGL) 라이선스 지원 국가 |
| BYTE array[207] | 207       | 예약 |
| 전체 길이         | 256       |

  8. Reference HWP 5.0 Data Type Specifications

    main

    The following table defines the data types used in HWP 5.0 files. Note that WCHAR is used for Unicode-based characters (including Hangul, English, and Hanja), and all characters occupy exactly 2 bytes.

    | 자료형          | 길이 | 부호 | 설명 |
| ------------- |:---:|:---:| --- |
| BYTE          | 1   |     | 부호 없는 한 바이트(0～255) |
| WORD          | 2   |     | 16비트 컴파일러에서 `unsigned int`에 해당 |
| DWORD         | 4   |     | 16비트 컴파일러에서 `unsigned long`에 해당 |
| WCHAR         | 2   |     | 한글의 기본 코드로 유니코드 기반 문자 |
| HWPUNIT       | 4   |     | 1/7200인치로 표현된 한글 내부 단위 |
| SHWPUNIT      | 4   | √   | 1/7200인치로 표현된 한글 내부 단위 |
| UINT8         | 1   |     | `unsigned __int8` 에 해당 |
| UINT16        | 2   |     | `unsigned __int16` 에 해당 |
| UINT32(=UINT) | 4   |     | `unsigned __int32` 에 해당 |
| INT8          | 1   | √   | `signed __int8` 에 해당 |
| INT16         | 2   | √   | `signed __int16` 에 해당 |
| INT32         | 4   | √   | `signed __int32` 에 해당 |
| HWPUNIT16     | 2   | √   | INT16 과 같다. |
| COLORREF      | 4   |     | RGB값(0x00bbggrr)을 십진수로 표시 (rr : red 1 byte, gg : green 1 byte, bb : blue 1 byte) |
| BYTE stream   |     |     | 일련의 BYTE로 구성됨. 본문 내에서 다른 구조를 참조할 경우에 사용됨 |

  10. Parse Attribute 2 (속성2) bitmask

    main

    The 속성2 field is a DWORD bitmask for licensing and reproduction constraints:

    BitDescription
    0CCL, KOGL (공공누리) license information
    1Reproduction restriction status
    2Permission to reproduce under same conditions (ignored if bit 1 is set)
    3-31Reserved

  11. Parse Attribute 1 (속성1) bitmask

    main

    The 속성1 field is a DWORD bitmask used to identify various document properties. Use the following bit mapping to parse the flags:

    BitDescription
    0Compression status
    1Encryption status
    2Distribution document status
    3Script storage status
    4DRM security document status
    5XMLTemplate storage existence
    6Document history management existence
    7Electronic signature information existence
    8Public certificate encryption
    9Electronic signature preliminary storage
    10Public certificate DRM security document
    11CCL document status
    12Mobile optimization status
    13Personal information security document status
    14Change tracking document status
    15KOGL (공공누리) copyright document
    16Video control inclusion
    17Table of contents field control inclusion
    18-31Reserved