@ddc-123/print-service-client

打印服务客户端 SDK，支持服务器打印（云打印）和浏览器打印（Web 打印）。

安装

npm install @ddc-123/print-service-client

如需浏览器打印功能，还需安装：

npm install vue-plugin-hiprint@^0.0.60

快速开始

初始化

import { createPrintClient } from '@ddc-123/print-service-client'

const printClient = createPrintClient({
  baseURL: '/dy',                    // 打印服务代理路径，默认 '/dy'
  editAddress: 'http://editor:port', // 模板编辑器地址
  onLoading: (loading) => {          // Loading 回调（可选）
    // 显示/隐藏加载状态
  },
  onError: (msg) => {                // 错误回调（可选）
    // 显示错误提示
  },
})

服务器打印

import { PrintTask } from '@ddc-123/print-service-client'

// 获取打印机列表
const printers = await printClient.getPrinterList()

// 获取模板列表
const templates = await printClient.getPrintTemplateList()

// 单条打印
const task = new PrintTask()
task.uuid = '模板ID'
task.printer = '打印机名称'
task.title = '出库单'
task.data = { orderNo: 'WMS-2024-001', productName: '物料A', quantity: 100 }
await printClient.printSingle(task)

// 批量打印
const mulTask = new PrintTask()
mulTask.uuid = '模板ID'
mulTask.printer = '打印机名称'
mulTask.title = '库存标签'
mulTask.data = [
  { code: 'A001', name: '物料A' },
  { code: 'A002', name: '物料B' },
]
await printClient.printMul(mulTask as PrintTask & { data: any[] })

浏览器打印

import { webPrint, disAutoConnect } from '@ddc-123/print-service-client/web'

// 应用启动时调用一次
disAutoConnect()

// 获取模板内容后调用
const res = await printClient.getPrintTemplate({ uuid: '模板ID' })
webPrint(res.data.templateContent, { orderNo: 'WMS-2024-001' })

模板编辑

// 跳转到 hiprint 编辑器
printClient.goPrintTemplateEditPage('模板ID')

自定义拦截器

// 通过暴露的 axios 实例添加自定义拦截器
printClient.axiosInstance.interceptors.request.use((config) => {
  config.headers.Authorization = `Bearer ${getToken()}`
  return config
})

纯 HTML+JS 项目

提供全打包版本（所有依赖内置，零外部依赖）：

<script type="module">
  // 主功能（含 axios）
  import { createPrintClient, PrintTask } from './node_modules/@ddc-123/print-service-client/dist/raw.js'

  const client = createPrintClient({ baseURL: '/dy' })

  const task = new PrintTask()
  task.uuid = '模板ID'
  task.printer = '打印机名称'
  task.data = { orderNo: 'WMS-2024-001' }
  await client.printSingle(task)
</script>

浏览器打印全打包版：

<script type="module">
  import { webPrint, disAutoConnect } from './node_modules/@ddc-123/print-service-client/dist/web-raw.js'

  disAutoConnect()
  // ...
</script>

代理配置

前端所有请求通过 baseURL（默认 /dy）发出，需配置代理转发到打印服务。

Vite 开发环境

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      '^/dy': {
        changeOrigin: true,
        target: 'http://打印服务IP:端口',
        rewrite: (path) => path.replace(/^\/dy/, ''),
      },
    },
  },
})

Nginx 生产环境

location /dy/ {
    proxy_pass http://打印服务IP:端口/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

导出路径

| 路径 | 用途 | 外部依赖 | |------|------|---------| | @ddc-123/print-service-client | 主入口（服务器打印 + 模板管理） | axios | | @ddc-123/print-service-client/web | 浏览器打印 | vue-plugin-hiprint | | @ddc-123/print-service-client/raw | 主入口全打包版 | 无 | | @ddc-123/print-service-client/web-raw | 浏览器打印全打包版 | 无 |

API

createPrintClient(config?)

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | baseURL | string | '/dy' | 打印服务代理路径 | | editAddress | string | — | 模板编辑器地址 | | timeout | number | 0 | 请求超时（毫秒） | | withCredentials | boolean | true | 是否携带凭证 | | onLoading | (loading: boolean) => void | — | Loading 状态回调 | | onError | (msg: string) => void | — | 错误消息回调 |

返回的 PrintClient 实例方法

| 方法 | 说明 | |------|------| | getPrinterList(params?) | 获取打印机列表 | | getPrintTemplateList(params?) | 获取所有打印模板 | | getPrintTemplate({ uuid }) | 根据 uuid 获取模板 | | removePrintTemplate({ uuid }) | 删除模板 | | printSingle(task) | 单条打印（自动获取模板） | | printMul(task) | 批量打印（自动获取模板） | | goPrintTemplateEditPage(uuid) | 跳转模板编辑器 | | axiosInstance | 底层 axios 实例 |