문서 › 레퍼런스

API 레퍼런스

@82label/core(전역 Label82)가 내보내는 모든 함수와 값.

아래는 import { … } from '@82label/core' 와 CDN 의 전역 Label82 에 똑같이 들어 있습니다.

인쇄

이름	설명
`print(template, rows?, options?)`	서식(객체 또는 ID)과 데이터로 인쇄. `Promise<PrintResult>`. 인쇄 참고.
`printers()`	출력 프로그램의 프린터 목록 `{ name, isDefault, dpi? }[]`, 없으면 `null`.
`agentStatus()`	`{ version, allowed, licensed }` 또는 `null`.
`printViaBrowser(svgs, size)`	페이지 SVG 목록을 브라우저 인쇄 창으로(`size` = `{ width, height }` mm).
`rasterize(svg, widthMm, heightMm, dpi)`	SVG 를 dpi 해상도 PNG `Blob` 으로.
`AgentError`	`mode: 'agent'` 실패. `code`: unavailable · denied · license_required · failed.
`toPDF(template, rows?, options?)`	라벨 PDF `Blob`. 바코드·QR·선은 벡터. 브라우저 전용. PDF 저장 참고.
`downloadPDF(template, rows?, filename?, options?)`	PDF 를 만들어 바로 내려받습니다.
`calibrationKey(via, printer?)`	보정 저장 키: `'browser'` 또는 `'agent:프린터'`.
`getCalibration(key) / setCalibration(key, cal \| null)`	이 브라우저에 저장한 보정 `{ offsetX, offsetY, scale }`. 인쇄 보정 참고.
`calibrationTemplate(template)`	같은 용지의 시험 인쇄 서식(테두리, 1 cm 눈금, 십자, 크기).
`AGENT_PORTS`	출력 프로그램이 듣는 포트 후보 `[18282, 18283, 18284]`.

저장한 서식

이름	설명
`loadTemplate(id, base?)`	`https://82label.app/api/t/<id>` 에서 서식을 받습니다. 같은 ID 는 페이지에서 한 번만 받습니다.
`loadCourierTemplate(id, base?)`	택배 송장 기본서식(구독자, 82label.app 로그인 쿠키 필요).
`clearTemplateCache()`	받아 둔 서식을 비웁니다.
`TemplateNotFound`	없는 ID, 지운 서식, 네트워크 오류, 잘못된 JSON.
`PaymentRequired`	402: 결제가 멈춘 유료 서식 또는 구독이 필요한 택배 서식.

그리기

이름	설명
`renderToSVG(template, row?, options?)`	라벨 한 장의 SVG 문자열(`row` 가 없으면 예시값). DOM 불필요.
`renderLabelSVG(template, row?, options?)`	`{ svg, errors }`.
`renderPageSVG(template, page, rows, options?)`	한 페이지(시트 한 장 또는 롤 한 장)의 `{ svg, errors }`.
`barcodeSVG(value, { format, height, moduleWidth, showText, codeSet })`	라벨 없이 바코드 그림만.
`qrSVG(value, { ecc, size })`	라벨 없이 QR 그림만.
`measureText(text, sizeMm, font?, bold?)`	글자 폭(mm). 브라우저에서는 canvas 로 잽니다.
`layoutPages(template, count, startAt?)`	라벨 `count` 장의 페이지와 칸 좌표 `Page[]`.
`pageSize(template)`	인쇄 페이지 크기 `{ width, height }` mm.

바코드·QR

이름	설명
`encodeBarcode(format, value, { codeSet? })`	막대 모듈 배열과 사람이 읽는 글자. 잘못된 값이면 `BarcodeError`.
`eanCheckDigit(digits)`	EAN·UPC 체크 숫자.
`mod7Check(digits)`	7로 나눈 나머지(일부 택배사 송장번호 검사).
`encodeQR(value, ecc?)`	QR 모듈 행렬. 너무 길면 `QrError`.
`BarcodeError, QrError`	값 오류.

필드

이름	설명
`extractFields(template)`	서식에 쓰인 `{{이름}}` 목록.
`fill(text, row, ctx?)`	`{{이름}}`·`{{이름\|서식}}`·`{{seq}}`·`{{today}}` 을 값으로 바꾼 글자. `ctx` = `{ index, serialStart, now }`.
`FIELD_FORMATS`	값 서식 목록 `{ id, label, example }[]`. 값 서식 참고.
`exampleRow(template)`	`fields[].example` 로 만든 예시 행.
`escapeXml(text)`	SVG·HTML 에 넣을 수 있게 이스케이프.

용지와 단위

이름	설명
`FORMTEC`	폼텍 A4 시트 규격 목록 `SheetSpec[]`(코드, 칸, 크기, 여백, 확인 여부, 출처).
`ROLL_SIZES`	자주 쓰는 롤 크기 `{ w, h, label, use }[]`.
`COURIERS`	택배 서식 정보(공개 패키지에서는 빈 목록, 사이트가 채움).
`presetTemplate('roll', w, h) / presetTemplate('formtec', id)`	빈 서식.
`SAMPLES / sampleTemplate(id)`	무료 시작 서식: 쿠팡 로켓그로스 바코드(50×30, 60×40, 70×40, A4 21·40칸), 표시사항, 가격표, 자산 번호.
`sheetPaper(id)`	폼텍 규격의 `paper` 객체.
`mmToPx(mm, dpi?), mmToDots(mm, dpi), ptToMm(pt), MM_PER_PT`	단위 변환.

기타

이름	설명
`defineLabelElement(tag?)`	`<label-82>`(또는 다른 이름) 등록. CDN 빌드는 자동.
`VERSION`	라이브러리 버전 문자열.

타입

type Template = { v: 1; name: string; paper: RollPaper | SheetPaper; label: { width; height; radius? }; elements: Element[]; fields?: FieldDef[] };
type RollPaper = { kind: 'roll'; gap?; dpi?: 203 | 300 | 600; direction?: 0 | 90 | 180 | 270 };
type SheetPaper = { kind: 'sheet'; preset?; page: 'A4' | 'Letter' | { width; height }; cols; rows; marginTop; marginLeft; pitchX; pitchY; shape?: 'rect' | 'circle' | 'ring'; innerDiameter? };
type Row = Record<string, string | number | null | undefined>;
type PrintOptions = { printer?; copies?; startAt?; mode?: 'auto' | 'agent' | 'browser'; dpi?; frames?; base?; serialStart?; now?: Date; calibration?: Calibration | false; qtyField? };
type Calibration = { offsetX?; offsetY?; scale? }; // mm, mm, 1 = 100%
type PrintResult = { via: 'agent' | 'browser'; printed; status: 'done' | 'pending_permission' | 'cancelled'; errors: RenderError[]; notice?: 'agent_license_required' };
type RenderError = { element: number; code: 'barcode_invalid' | 'qr_too_long' | 'overflow' | 'image_failed'; message: string };