문서 › 함수와 Node

함수 API: inspect, check, readRows

파일 정보 보기, 규칙 검사, 행 꺼내기, 양식에서 규칙 만들기, 빈 양식 만들기와 공통 옵션·한도.

입력은 File | Blob | ArrayBuffer | Uint8Array(Node의 Buffer 포함)입니다. 파일 경로 문자열은 받지 않습니다. CDN에서는 Excel82.… 로, npm에서는 import { … } from '82excel' 로 같은 이름입니다.

import { check, readRows, rulesFromTemplate, makeTemplate } from '82excel';

const rules = await rulesFromTemplate(templateBytes);          // { headers: [...], columns: 3 }
const result = await check(file, { ...rules, rows: { min: 1 }, locale: 'ko' });
const { rows } = await readRows(file);
const blob = makeTemplate(['이름', '전화번호', '금액'], 'xlsx');

inspect(file, opts?)

inspect(file, { headerRow?, previewRows?, locale?, telemetry?, delimiter?, maxUncompressedSize? }) 는 모든 시트를 훑어 { file, meta?, csv?, sheets[], definedNames, issues } 를 돌려줍니다. 시트마다 name, index, hidden, protected, range, columnCount, rowCount, columns, columnTypes, emptyCells, errorCells, mergedCells, hiddenRows, hiddenColumns, formulaCount, personalData?, preview. 암호·손상 파일에서도 throw하지 않고 issues 를 채웁니다. 값이 오류 셀(#DIV/0! 등)뿐인 열의 columnTypes 는 'empty' 입니다(오류 셀은 errorCells 로 따로 알려 줌).

const info = await Excel82.inspect(file);
info.file;          // { name, size, format, extension, encrypted, hasMacros }
info.sheets[0];     // { name, columns, columnTypes, rowCount, preview, … }
info.issues;        // [{ code: 'PASSWORD_PROTECTED', severity: 'error', message }]

check(file, rules)

{ ok, errors, warnings, info, rows? } 를 돌려줍니다. 규칙: headers, columns, rows: { min, max }, sheet, headerRow, maxSize, maxUncompressedSize, delimiter, accept, locale, readRows, maxCells, previewRows, failOn, telemetry.

기본으로 첫 시트만 검사하고, 문제를 모두 모아 돌려줍니다(파일을 아예 읽을 수 없으면 거기서 끝).
머리글은 NFC로 정규화해 순서까지 비교합니다. 공백·대소문자만 다르면 힌트 문구가 붙습니다.
경고는 ok에 영향이 없고, failOn: ['PERSONAL_DATA'] 처럼 지정한 경고는 오류가 됩니다.
throw는 잘못된 인자일 때만 합니다.

readRows(file, opts?)

readRows(file, { sheet?, headerRow?, locale?, delimiter?, maxUncompressedSize?, maxCells? }) 는 { rows, columns, issues } 를 돌려줍니다. 행은 {머리글: 값} 객체이고 프로토타입이 없습니다(__proto__ 머리글도 안전). 같은 머리글은 이름_2 처럼 번호를 붙이고 DUPLICATE_HEADER 경고를 냅니다. 값이 하나도 없는 줄은 건너뜁니다(rowCount 에는 셉니다).

rulesFromTemplate, makeTemplate

rulesFromTemplate(file, { sheet?, headerRow?, delimiter?, maxUncompressedSize? }): 양식 파일의 머리글 행에서 { headers, columns } 를 만듭니다.
makeTemplate(headers, 'csv' | 'xlsx', sheetName?): 머리글만 있는 빈 양식을 Blob으로 돌려줍니다(CSV는 UTF-8 BOM 포함).
registerLocale(name, messages): 메시지 묶음을 등록합니다. VERSION: 라이브러리 버전.

공통 옵션과 한도

옵션	설명
`delimiter`	CSV 구분자 `','`, `';'`, `'\t'` 중 하나. 주지 않으면 자동으로 알아냅니다. 줄마다 칸 수가 다른 `;` CSV처럼 감지가 빗나갈 때 지정하세요.
`maxSize`	`check` 만, 기본 50 MB. 파일 크기 상한. `File`/`Blob` 은 내용을 읽기 전에 크기를 봅니다.
`maxUncompressedSize`	기본 200 MB. xlsx 안에서 압축을 푼 크기의 합 상한. 넘으면 `FILE_TOO_LARGE`(압축 폭탄 방지).
`maxCells`	`readRows`, `check({ readRows: true })`, `upload-as="json"`, 기본 2,000,000. 데이터 행 수 × 열 너비 상한. 넘으면 행을 만들기 전에 `FILE_TOO_LARGE`(`{ maxCells }`)를 내고 행을 돌려주지 않습니다.

엑셀 격자 밖(xlsx 1,048,576행 × 16,384열, xls 65,536행 × 256열)에 있는 셀은 무시합니다. CSV는 UTF-8(BOM 유무), UTF-16, EUC-KR(CP949) 인코딩을 자동으로 알아냅니다.

오류 코드와 메시지는 오류 코드표에 있습니다.