printer-command-generator
Version:
A universal printer command generator for ZPL and TSPL printers
381 lines (303 loc) • 8.23 kB
Markdown
# 🖨️ Printer Command Generator
一个通用的打印机指令生成库，支持 ZPL 和 TSPL 两种主流打印机协议。
## ✨ 特性
- 🎯 **零依赖**: 纯 JavaScript 实现，无外部依赖
- 🔧 **多格式支持**: 支持 ES Module、CommonJS 和 UMD 格式
- 🖨️ **双协议**: 同时支持 ZPL (Zebra) 和 TSPL (TSC) 打印机
- 📱 **跨平台**: 支持 Node.js 和浏览器环境
- 🎨 **丰富组件**: 支持文本、二维码、图片等多种打印元素
## 📦 安装
### NPM 安装
```bash
npm install printer-command-generator
```
### CDN 引入
```html
<!-- 通过 unpkg -->
<script src="https://unpkg.com/printer-command-generator/dist/printer-command-generator.min.js"></script>
<!-- 通过 jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/printer-command-generator/dist/printer-command-generator.min.js"></script>
```
## 🚀 快速开始
### Node.js 环境
```javascript
// ES Module
import { convertToCmd, PrinterCommandGenerator } from 'printer-command-generator';
// CommonJS
const { convertToCmd, PrinterCommandGenerator } = require('printer-command-generator');
// 定义打印模板
const template = {
width: 100,
height: 60,
dpi: 203,
widgets: [
{
type: 'text',
x: 10,
y: 10,
content: 'Hello World',
fontSize: 12
},
{
type: 'qrcode',
x: 10,
y: 30,
content: 'https://example.com',
size: 20
}
]
};
// 生成 ZPL 指令
const zplCommand = convertToCmd(template, 'ZPL');
console.log(zplCommand);
// 生成 TSPL 指令
const tsplCommand = convertToCmd(template, 'TSPL');
console.log(tsplCommand);
```
### 浏览器环境
```html
<!DOCTYPE html>
<html>
<head>
<title>打印机指令生成器</title>
</head>
<body>
<script src="https://unpkg.com/printer-command-generator/dist/printer-command-generator.min.js"></script>
<script>
const template = {
width: 100,
height: 60,
dpi: 203,
widgets: [
{
type: 'text',
x: 10,
y: 10,
content: 'Hello World',
fontSize: 12
}
]
};
// 使用全局变量 PrinterCommandGenerator
const zplCommand = PrinterCommandGenerator.convertToCmd(template, 'ZPL');
console.log(zplCommand);
</script>
</body>
</html>
```
## 📖 API 文档
本库提供两种使用方式：**函数式调用**和**面向对象编程**。
### 方式一：函数式调用（推荐用于简单场景）
直接使用 `convertToCmd` 函数将打印模板转换为打印机指令。
#### `convertToCmd(template, printerType, options, fontPath)`
**参数:**
- `template` (Object): 打印模板对象
- `printerType` (String): 打印机类型，'ZPL' 或 'TSPL'
- `options` (Object): 可选配置参数
- `fontPath` (String): 可选字体文件路径
**返回值:**
- (String): 生成的打印机指令
**示例:**
```javascript
import { convertToCmd } from 'printer-command-generator';
const template = {
page: {
width: 100,
height: 60,
dpiType: '203'
},
widgets: [
{
type: 'text',
x: 10,
y: 10,
content: 'Hello World',
fontSize: 12
},
{
type: 'qrcode',
x: 10,
y: 30,
content: 'https://example.com',
size: 20
}
]
};
// 生成 ZPL 指令
const zplCommand = await convertToCmd(template, 'ZPL');
console.log(zplCommand);
// 生成 TSPL 指令
const tsplCommand = await convertToCmd(template, 'TSPL');
console.log(tsplCommand);
// 使用自定义字体
const zplWithFont = await convertToCmd(template, 'ZPL', {}, 'E:CUSTOM.TTF');
```
### 方式二：面向对象编程（推荐用于复杂场景）
通过创建页面和组件对象，灵活构建打印内容。
#### 基本流程
1. 创建打印页面 (`PrintPage`)
2. 创建各种组件 (`TextWidget`, `QRCodeWidget`, `ImageWidget`)
3. 将组件添加到页面
4. 生成打印指令
**示例:**
```javascript
import { PrintPage, TextWidget, QRCodeWidget, ImageWidget } from 'printer-command-generator';
// 1. 创建打印页面
const page = new PrintPage({
width: 100, // 宽度 (mm)
height: 60, // 高度 (mm)
dpiType: '203', // DPI
fontPath: 'E:CUSTOM.TTF' // 可选：自定义字体路径
});
// 2. 创建文本组件
const titleText = new TextWidget({
x: 10,
y: 5,
content: '产品标签',
fontSize: 16,
fontWeight: 'bold',
fontPath: 'E:TITLE.TTF' // 可选：组件级字体路径
});
const productName = new TextWidget({
x: 10,
y: 20,
content: 'iPhone 15 Pro',
fontSize: 12
});
// 3. 创建二维码组件
const qrCode = new QRCodeWidget({
x: 60,
y: 10,
content: 'https://apple.com/iphone-15-pro',
size: 25,
errorCorrection: 'M'
});
// 4. 创建图片组件
const logo = new ImageWidget({
x: 10,
y: 40,
width: 20,
height: 10,
data: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...' // Base64 图片数据
});
// 5. 将组件添加到页面
page.addWidget(titleText);
page.addWidget(productName);
page.addWidget(qrCode);
page.addWidget(logo);
// 或者批量添加
// page.addWidgets([titleText, productName, qrCode, logo]);
// 6. 生成打印指令
const zplCommand = page.toZPL();
const tsplCommand = page.toTSPL();
console.log('ZPL指令:', zplCommand);
console.log('TSPL指令:', tsplCommand);
```
## 📋 模板格式
### 基本结构
```javascript
const template = {
width: 100, // 标签宽度 (mm)
height: 60, // 标签高度 (mm)
dpi: 203, // 打印分辨率 (可选，默认 203)
widgets: [ // 打印元素数组
// 打印元素...
]
};
```
### 支持的打印元素
#### 文本元素
```javascript
{
type: 'text',
x: 10, // X 坐标 (mm)
y: 10, // Y 坐标 (mm)
content: 'Hello', // 文本内容
fontSize: 12, // 字体大小 (可选)
fontWeight: 'bold', // 字体粗细 (可选)
rotation: 0 // 旋转角度 (可选)
}
```
#### 二维码元素
```javascript
{
type: 'qrcode',
x: 10, // X 坐标 (mm)
y: 10, // Y 坐标 (mm)
content: 'QR content', // 二维码内容
size: 20, // 二维码大小 (mm)
errorCorrection: 'M' // 纠错级别 (可选)
}
```
#### 条码元素
```javascript
{
type: 'barcode',
x: 10, // X 坐标 (mm)
y: 10, // Y 坐标 (mm)
content: '123456789', // 条码内容
width: 40, // 条码宽度 (mm)
height: 10, // 条码高度 (mm)
codeType: 'CODE128' // 条码类型 (可选)
}
```
#### 图片元素
```javascript
{
type: 'image',
x: 10, // X 坐标 (mm)
y: 10, // Y 坐标 (mm)
width: 30, // 图片宽度 (mm)
height: 20, // 图片高度 (mm)
data: 'base64...' // Base64 图片数据
}
```
## 🧪 本地测试
1. 克隆项目并安装依赖:
```bash
git clone <repository-url>
cd printer-cmd-generator
npm install
```
2. 构建项目:
```bash
npm run build
```
3. 启动测试服务器:
```bash
npm run test
```
4. 在浏览器中打开 `http://localhost:8080` 查看测试页面。
## 🔧 开发
### 项目结构
```
printer-cmd-generator/
├── src/ # 源代码
│ ├── index.js # 主入口文件
│ ├── PrinterCommandGenerator.js
│ ├── generators/ # 指令生成器
│ ├── widgets/ # 打印元素
│ └── utils/ # 工具函数
├── test/ # 测试文件
│ ├── index.html # 测试页面
│ └── templateSample.js # 测试数据
├── dist/ # 构建输出
├── package.json
├── rollup.config.js # 构建配置
└── README.md
```
### 构建命令
```bash
# 开发模式 (监听文件变化)
npm run dev
# 生产构建
npm run build
# 清理构建文件
npm run clean
```
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
## 📄 许可证
MIT License
---
**Made with ❤️ by Cloudred Team**