菜鸟打印组件 JavaScript SDK

一个用于连接菜鸟打印组件的 JavaScript 库，支持通过 WebSocket 与菜鸟打印组件通信，实现打印功能。

特性

• ✅ 支持菜鸟打印组件 WebSocket 通信
• ✅ 支持获取打印机列表
• ✅ 支持使用自定义 XML 模板打印
• ✅ 支持本地模板服务器
• ✅ TypeScript 支持
• ✅ 完整的错误处理和日志

安装

npm install
npm run build

快速开始

1. 确保菜鸟打印组件已安装并运行

菜鸟打印组件需要：

• 安装菜鸟打印组件客户端
• 组件服务正在运行（WebSocket 端口：13528/13529）

2. 基本使用

import { print, getPrinters } from './dist/index.esm.js';

// 获取打印机列表
const printers = await getPrinters();
console.log('可用打印机:', printers);

// 打印（使用模板）
await print({
  content: '', // HTML内容（可选，主要用于数据提取）
  cainiaoTemplateURL: 'http://localhost:8000/template/waybill.xml',
  cainiaoData: {
    expressCompany: '顺丰速运',
    trackingNumber: 'SF1234567890',
    sender: {
      name: '张三',
      phone: '13800138000',
      address: '北京市朝阳区测试街道123号'
    },
    receiver: {
      name: '李四',
      phone: '13900139000',
      address: '上海市浦东新区测试路456号'
    },
    remark: '易碎品，请轻拿轻放',
    printTime: new Date().toLocaleString('zh-CN')
  },
  paperSize: '75mm×130mm',
  onSuccess: () => {
    console.log('打印成功！');
  },
  onError: (error) => {
    console.error('打印失败:', error);
  }
});

模板服务器

项目包含一个本地模板服务器，用于提供 XML 模板文件：

npm run template-server

或者使用 Python HTTP 服务器：

cd template
python3 -m http.server 8000

模板格式

菜鸟打印组件使用 XML 格式的模板，参考 template/waybill.xml 和 template/waybill-simple.xml。

详细说明请参考：

• 菜鸟打印使用说明.md
• 菜鸟打印自定义模板说明.md
• 菜鸟打印本地模板说明.md
• 模板格式说明.md

API 文档

print(options: PrintOptions): Promise<void>

执行打印任务。

参数：

• options.content: HTML 内容（可选）
• options.cainiaoTemplateURL: 模板 URL（必需）
• options.cainiaoData: 模板数据（如果使用模板）
• options.paperSize: 纸张大小，如 '75mm×130mm'
• options.onSuccess: 成功回调
• options.onError: 失败回调

getPrinters(): Promise<string[]>

获取可用打印机列表。

isSupported(): boolean

检测当前环境是否支持菜鸟打印。

示例

查看 examples/cainiao-example.html 获取完整示例。

文档

• 菜鸟打印使用说明
• 菜鸟打印自定义模板说明
• 菜鸟打印本地模板说明
• 模板格式说明
• 使用Python服务器提供模板
• README-模板服务器

许可证

MIT