更新记录

1.1.0（2026-07-14）

• 初始版本，基于 HP print-core 2.1.5 + common-lib 1.0.0.4（方案 1 - API）封装。
• 支持打印机搜索（局域网 / USB）、按 IP 添加打印机、刷新打印机状态。
• 支持系统文件选择器选择 PDF / Word 文件并打印。
• 支持传入 content Uri 或本地文件绝对路径打印（用于网络文件下载后打印）。
• 支持打印任务状态监听与取消打印任务。

平台兼容性

uni-app(4.81)

uni-app x(4.82)

hl-hp-print

惠普打印机 UniApp 原生插件（UTS）。把惠普官方 Android SDK 封装成前端可直接调用的接口，用来搜索打印机、选文件、发起打印。

目录

1. 写在前面：你需要知道的 3 件事
2. 能做什么
3. 运行前准备
4. 5 分钟跑通 Demo
5. 业务接入：最短代码
6. 常见业务示例
7. API 说明
8. 数据类型
9. 常见问题
10. 依赖说明

1. 写在前面：你需要知道的 3 件事

第一：只能用自定义基座

正确做法：HBuilderX → 运行 → 运行到手机或模拟器 → 制作自定义调试基座 → 再用「运行到自定义基座」。

第二：必须先选中打印机，才能打印

流程固定为：

初始化 → 搜索/添加打印机 → 选中一台 → 选文件 → 打印

少任何一步都不行。

第三：优先用 PDF

惠普 SDK 官方明确支持 PDF、JPEG。Word（.doc / .docx）可以选，但不保证一定能打。业务上建议先转成 PDF。

2. 能做什么

• 搜索局域网 / USB 打印机
• 按 IP 手动添加打印机
• 查看并刷新打印机状态（空闲、打印中、停止、离线等）
• 用系统文件选择器选本地 PDF / Word
• 支持网络文件：下载后打印，结束后删临时文件
• 自定义打印参数（颜色、纸张、方向、单双面、DPI、页码范围等）
• 文件预览（按页生成图片）
• 打印任务状态监听与取消
• 打印历史查询与清理
• 唤醒打印机、USB 重检、导出 SDK 日志

3. 运行前准备

环境要求

• HBuilderX 3.6.8 及以上
• Android 真机（建议 Android 7.0+）
• 手机与惠普打印机在同一 Wi‑Fi，或 USB / OTG 直连

插件位置

插件已在工程 uni_modules/hl-hp-print 中，页面里这样引入：

import * as HpPrint from '@/uni_modules/hl-hp-print'

制作自定义基座（必做）

1. 用 HBuilderX 打开本工程
2. 菜单：运行 → 运行到手机或模拟器 → 制作自定义调试基座
3. 等待云端/本地打包完成，并安装到手机
4. 之后一律选择：运行到自定义基座

改了插件原生代码、换了 AAR、或首次接入本插件，都需要重新打基座。

4. 5 分钟跑通 Demo

工程里已有 Demo 页面：pages/hp-print-demo/index.vue。

推荐操作顺序

进入 Demo（自动初始化）
  → 点「开始搜索」，或输入 IP 点「添加」
  → 在列表里点选一台打印机
  → 选「本地文件」→ 选一份 PDF
  →（可选）点「获取可用参数」再调参数
  → 点「打印本地文件」
  → 在「打印任务」看状态，完成后到「打印历史」点「刷新」

5. 业务接入：最短代码

下面这段是最小可跑通逻辑，适合理解调用顺序：

import * as HpPrint from '@/uni_modules/hl-hp-print'
import { onMounted, onUnmounted } from 'vue'

onMounted(() => {
  // 1. 必须先初始化
  HpPrint.initSDK()
  HpPrint.setLog(true, true)

  // 2. 搜索打印机
  HpPrint.startDiscovery((list) => {
    if (list.length == 0) return

    const printerId = list[0].id

    // 3. 选文件
    HpPrint.pickFile((file) => {
      if (file == null) return

      // 4. 打印（第 4 个参数是对象，不是数字）
      HpPrint.print(printerId, file.uri, file.name, { copies: 1 }, (job) => {
        console.log('状态:', job.state, job.reasons)
      })
    })
  })
})

onUnmounted(() => {
  HpPrint.stopDiscovery()
  HpPrint.stopPreview()
  HpPrint.release()
})

6. 常见业务示例

6.1 本地文件打印（可带参数）

HpPrint.pickFile((file) => {
  if (file == null) return

  // 可选：先查这台打印机对这个文件支持哪些参数
  HpPrint.getSupportedOptions(printerId, file.uri, (opts) => {
    const options = {
      copies: 1,
      color: opts != null ? opts.defaults.color : undefined,
      mediaSize: opts != null ? opts.defaults.mediaSize : undefined,
      pageRanges: '1-2' // 仅 PDF 有效，例如打印第 1-2 页
    }

    HpPrint.print(printerId, file.uri, file.name, options, (job) => {
      console.log('打印状态', job.state, job.reasons)
    })
  })
})

说明：

• color、mediaSize 等字符串，请从 getSupportedOptions 返回列表里选，不要随意手写
• 不调用 getSupportedOptions 也可以打印，插件会用 SDK 默认值

6.2 网络文件下载后打印

uni.downloadFile({
  url: 'https://example.com/demo.pdf',
  success: (res) => {
    if (res.statusCode != 200) return

    // 转成原生能读的绝对路径
    const absPath = plus.io.convertLocalFileSystemURL(res.tempFilePath)

    HpPrint.print(printerId, absPath, 'demo.pdf', { copies: 1 }, (job) => {
      console.log('打印状态', job.state)

      // 任务结束后删除临时文件，避免占空间
      const endStates = ['Completed', 'Aborted', 'Canceled', 'Error']
      if (endStates.indexOf(job.state) >= 0) {
        plus.io.resolveLocalFileSystemURL(res.tempFilePath, (entry) => {
          entry.remove(() => {
            console.log('临时文件已删除')
          })
        })
      }
    })
  }
})

6.3 按 IP 添加打印机

适合搜不到、但你知道打印机 IP 的情况：

HpPrint.addPrinterByIp('192.168.1.100', (printer) => {
  if (printer == null) {
    console.log('未找到该 IP 的打印机')
    return
  }
  console.log('已添加', printer.name, printer.id)
})

7. API 说明

调用规则：

1. 任何能力之前先调 initSDK()
2. 打印前先拿到并保存 printerId
3. 页面销毁时调用 release()（建议同时 stopDiscovery / stopPreview）

7.1 初始化与日志

HpPrint.initSDK()
HpPrint.setLog(true, true)
HpPrint.exportLog((path) => {
  console.log('日志路径', path)
})

7.2 打印机发现与状态

HpPrint.startDiscovery((printers) => {
  printers.forEach((p) => {
    console.log(p.name, p.ip, p.statusName, '可打印:', p.isReady)
  })
})

HpPrint.refreshPrinter(printerId, (printer) => {
  if (printer != null && printer.isReady) {
    console.log('打印机就绪')
  }
})

7.3 选文件与打印

print 的第 4 个参数是 对象 HpPrintOptions，不是数字。

HpPrint.print(printerId, fileUri, fileName, {
  copies: 1,
  color: 'Color',
  mediaSize: 'A4',
  sides: 'OneSided',
  pageRanges: '1-3,5',
  pdfEnhancement: false
}, (job) => {
  console.log(job.jobId, job.state, job.reasons)
})

任务状态常见值：

7.4 打印历史

插件在 initSDK 时已默认开启历史记录。

7.5 文件预览

HpPrint.startPreview(printerId, fileUri, (info) => {
  if (info == null) return
  for (let i = 0; i < info.pageCount; i++) {
    HpPrint.getPreviewPage(i, (path) => {
      console.log('第' + (i + 1) + '页', path)
    })
  }
})

8. 数据类型

打印机 HpPrinterInfo

打印任务 HpPrintJobInfo

选中的文件 HpPickedFile

打印参数 HpPrintOptions

均为可选。未传的项由 SDK 按支持列表取默认值。

可用参数 HpSupportedOptions

由 getSupportedOptions 返回，包含各字段候选数组，以及 defaults（默认值）和 maxCopies。

历史任务 HpHistoryJob

含 jobId、jobName、printerId、printerName、state、createTime、isDone 等字段。

预览信息 HpPreviewInfo

9. 常见问题

一进页面就报 CoreManager 找不到？

没有用包含本插件的自定义基座。重新制作自定义调试基座后再运行。

搜索不到打印机？

1. 确认手机与打印机同一 Wi‑Fi（不要用访客网络）
2. 路由器是否开启了 AP 隔离
3. 改用「按 IP 添加」

SDK 常用端口：631/TCP、8080/TCP、80/TCP、443/TCP、5353/UDP。

点打印提示请先选择打印机？

必须先在列表中点选一台，顶部「当前打印机」有内容后才能打印。

Word 文件打印失败？

SDK 稳定支持 PDF / JPEG。Word 不保证成功，建议转 PDF 再打。

获取可用参数失败？

需要同时满足：已选打印机 + 已有本地文件 Uri。网络打印可先下载到本地再取参数，或直接用默认参数打印。

打印历史一直是空的？

先成功打过至少一单。initSDK 已默认开启历史记录。

打印机显示未就绪？

点该打印机刷新状态。仅 Idle / Processing 允许打印。休眠时可先点「唤醒」。