@goodboy008/labelize-wasm

中文文档
1.12.0发布于 2026/11/12MIT AND BSD-3-ClauseTypeScriptES Module零依赖近 30 天下载 4680

Labelize ZPL/EPL/TSPL/CPCL/DPL label renderer compiled to WebAssembly — render label data to PNG/PDF in browsers, Node.js, and bundlers

原始使用文档
文档目录6 节
  1. Usage
  2. Bundlers (webpack 5, Vite with vite-plugin-wasm )
  3. Node.js (≥ 20)
  4. API
  5. Release assets
  6. License

Labelize logo

@goodboy008/labelize-wasm

The Labelize ZPL/EPL/TSPL/CPCL/DPL label engine compiled to WebAssembly. Parse and render ZPL, EPL, TSPL/TSC, CPCL or DPL label data to PNG (or PDF) entirely in the browser, Node.js, or your bundler — no server needed.

Usage

Bundlers (webpack 5, Vite with vite-plugin-wasm)

import { lz_render } from "@goodboy008/labelize-wasm";

const zpl = new TextEncoder().encode("^XA^FO50,50^A0N,40,40^FDHELLO WORLD^FS^XZ");
const png = lz_render(zpl, 102.0, 152.0, 8, false, false, false);
// png is a Uint8Array — pass it to an <img> via URL.createObjectURL

The package is the standard wasm-bindgen bundler output: labelize_wasm.js initializes the engine at module top level and exports lz_render / lz_render_lang / lz_playground_html.

Node.js (≥ 20)

import { lz_render } from "@goodboy008/labelize-wasm/init";

const zpl = Buffer.from("^XA^FO50,50^A0N,40,40^FDHELLO WORLD^FS^XZ", "ascii");
const png = lz_render(zpl, 102.0, 152.0, 8, false, false, false);

The /init subpath instantiates the engine from the packaged .wasm directly, without bundler support or Node flags.

API

lz_render(src, width_mm, height_mm, dpmm, antialias, want_pdf, is_epl) -> Uint8Array

parammeaning
srcraw label bytes (ZPL, or EPL when is_epl = true)
width_mm / height_mmlabel canvas size in millimetres (defaults: 102 × 152)
dpmmdots per millimetre (default 8)
antialiaskeep renderer greys instead of thresholding to 1-bit
want_pdfreturn a PDF instead of PNG
is_eplparse input as EPL instead of ZPL

lz_render_lang(src, width_mm, height_mm, dpmm, antialias, want_pdf, lang) -> Uint8Array is the language-explicit variant: lang is "zpl", "epl", "tspl", "cpcl", or "dpl" (TSPL/TSC and CPCL labels; the label's own SIZE in TSPL does not override the width_mm/height_mm you pass — size the canvas like any other input). Unknown lang values fall back to ZPL.

import { lz_render_lang } from "@goodboy008/labelize-wasm/init";

const tspl = Buffer.from('SIZE 101.6 mm,152.4 mm\nCLS\nTEXT 40,40,"4",0,1,1,"HELLO WORLD"\nPRINT 1', "ascii");
const png = lz_render_lang(tspl, 101.6, 152.4, 8, false, false, "tspl");

Errors throw a string prefixed with the failure stage: 1: parse error, 2: rendering error.

lz_validate(src, dpmm, lang) -> string syntax-checks without rendering and never throws — the JSON report carries the outcome, so SDK callers get the exact parser error instead of a bare thrown string:

import { lz_validate } from "@goodboy008/labelize-wasm/init";

const report = JSON.parse(lz_validate(src, 8, "")); // "" = auto-detect the language
// { language: "zpl", ok: true,  labels: 1 }
// { language: "epl", ok: false, labels: 0, error: "Parse error: EPL X command requires 5 parameters, got 2" }

if (!report.ok) console.error(`[${report.language}] ${report.error}`);

lz_format(src, lang) -> Uint8Array pretty-prints the source: one command per line, ^XA blocks indented, CRLF normalized. Binary payloads (^FD data, GW/BITMAP graphics) pass through byte-for-byte, so formatted source renders pixel-identically:

import { lz_format } from "@goodboy008/labelize-wasm/init";

const pretty = new TextDecoder().decode(lz_format(src, "")); // "" = auto-detect

lz_encode(src, dpmm, threshold, lang) -> Uint8Array converts an encoded image (PNG/JPEG/GIF/BMP) to printer code. lang must be "zpl" or "tspl" (case-insensitive); unsupported targets, invalid images and invalid options throw a 1: input error. One image pixel becomes one printer dot. Threshold defaults are supplied by the caller: 128 makes composited luminance below 128 print black; transparent pixels print white. Encoded inputs honor EXIF orientation. Images are limited to 16 Mi pixels, 32000 dots per dimension and 128 MiB of decoded data.

import { readFileSync, writeFileSync } from "node:fs";
import { lz_encode } from "@goodboy008/labelize-wasm/init";

const source = readFileSync("logo.png");
writeFileSync("logo.zpl", lz_encode(source, 8, 128, "zpl"));
writeFileSync("logo.tspl", lz_encode(source, 8, 128, "tspl")); // binary BITMAP payload

Generated ZPL uses multiple graphic fields when needed to stay within Zebra's 99999-byte field limit. For a matching ZPL preview, set the canvas to the image width/height divided by dpmm in millimetres. TSPL declares that size itself.

lz_playground_html() -> string returns the Labelize playground page (identical to the HTTP server's /).

Release assets

GitHub releases also attach labelize-wasm-wasm32.zip with the raw glue + .wasm files, for direct use without npm. See wasm/build.sh to rebuild the engine:

cd wasm && ./build.sh   # requires Rust wasm32 target + wasm-bindgen-cli

License

MIT AND BSD-3-Clause

版本与发布记录

@goodboy008/labelize-wasm 共发布 12 个版本,首次发布于 2026/08/23;过去 12 个月发布了 12 个版本。

版本发布日期距今
1.12.0latest2026/11/124 天前
1.11.02026/11/115 天前
1.10.02026/10/2819 天前
1.9.02026/10/2126 天前
1.8.12026/10/161 个月前
1.8.02026/10/131 个月前

关于 @goodboy008/labelize-wasm 的常见问题

@goodboy008/labelize-wasm 是什么?

Labelize ZPL/EPL/TSPL/CPCL/DPL label renderer compiled to WebAssembly — render label data to PNG/PDF in browsers, Node.js, and bundlers

如何安装 @goodboy008/labelize-wasm?

在项目目录运行 npm install @goodboy008/labelize-wasm,或使用 pnpm add / yarn add / bun add。

@goodboy008/labelize-wasm 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@goodboy008/labelize-wasm 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@goodboy008/labelize-wasm 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@goodboy008/labelize-wasm 可以商用吗?

@goodboy008/labelize-wasm 使用 MIT AND BSD-3-Clause 许可。声明的许可为 MIT AND BSD-3-Clause,请阅读许可原文确认使用条件。以上为概括,不构成法律意见,请以许可原文为准。

@goodboy008/labelize-wasm 的下载量有多少?

根据 npm 官方下载统计,@goodboy008/labelize-wasm 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,680 次,日均约 156 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@goodboy008/labelize-wasm 还在维护吗?

最新版本 1.12.0 发布于 2026/11/12(4 天前);至今共发布 12 个版本,其中过去 12 个月发布了 12 个;首次发布于 2026/08/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。