更新记录

1.0.14（2026-04-27）

文档更新：补充 HarmonyOS 加密试用版手动补充 module.har 的临时兼容说明，便于试用用户在 HBuilderX 未自动复制 HAR 时继续完成构建验证。

1.0.13（2026-04-27）

• 新增 HarmonyOS 平台支持
• 优化 HarmonyOS 网页/HTML 打印方案
• 更新 HarmonyOS 使用说明
• 补充 HarmonyOS module.har，用于插件市场试用/加密包导入后本地构建依赖

1.0.12（2026-04-26）

• 新增 HarmonyOS 平台支持
• 优化 HarmonyOS 网页/HTML 打印方案
• 更新 HarmonyOS 使用说明

平台兼容性

uni-app(5.07)

uni-app x(5.07)

hens-print

当前版本：v1.0.14

插件简介

hens-print 是一个 uni-app / uni-app X App 端打印插件，提供 PDF、图片、网页 URL、HTML 字符串、多图片打印、文件可打印性检查、调试日志和统一错误码。

注意：success 回调表示系统打印任务已创建、提交或打印面板流程完成，不等同于纸张已经真实打印完成。实际打印结果仍受系统打印服务、打印机状态和用户操作影响。

功能特性

• PDF 文档打印：支持本地 PDF 文件打印。
• 图片打印：支持常见图片格式，具体格式按平台略有差异。
• 多图片打印：Android / iOS 支持按每页 1、2、4 张排版；HarmonyOS 当前不应用布局参数。
• 网页打印：支持通过 URL 加载网页后调用系统打印，可配置超时时间和渲染等待。
• HTML 内容打印：支持直接打印 HTML 字符串，Android / iOS 可通过 baseUrl 解析相对资源。
• 图表页辅助：Android 支持通过选择器控制图表页的打印时机。
• 文件检查与错误码：提供 isPrintableSync 初筛能力和统一错误回调。
• 调试日志：可动态开启或关闭打印调试日志。

支持平台与版本

• 支持：uni-app App 端 Android / iOS / HarmonyOS。
• 支持：uni-app X App 端 Android / iOS / HarmonyOS。
• 不支持：H5、小程序、快应用。

版本要求：

• HBuilderX >= 3.6.8
• uni-app >= 4.75
• uni-app X >= 4.75
• Android minSdkVersion >= 21
• iOS deploymentTarget >= 12
• HarmonyOS apiLevel >= 9

平台能力矩阵

安装方式

请通过 DCloud 插件市场安装：

1. 在 HBuilderX 中打开项目，进入插件市场搜索 hens-print。
2. 选择“导入插件”/“下载插件”，将插件安装到当前项目的 uni_modules/hens-print。
3. 在页面中按需导入插件方法。

HarmonyOS 使用配置

HarmonyOS 使用打印能力时，需要在应用 entry 模块声明 ohos.permission.PRINT。

如果项目已经有 entry 的 module.json5，只需要把下面权限合并到 module.requestPermissions 中，避免覆盖 abilities、pages、deviceTypes 等原有内容：

"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET"
  },
  {
    "name": "ohos.permission.PRINT"
  }
]

如果需要通过 harmony-configs 覆盖 entry 配置，可以在项目根目录创建 harmony-configs/entry/src/main/module.json5，内容参考：

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "phone",
      "tablet",
      "2in1"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.PRINT"
      }
    ]
  }
}

HarmonyOS 网页 / HTML 打印不需要额外复制页面，也不需要在 pages.json 中注册打印宿主页。

HarmonyOS 加密试用版手动补充 module.har

部分 HBuilderX 版本在普通 uni-app 的 HarmonyOS 工程中使用加密试用插件时，可能会出现插件市场已下载 module.har，但生成的 HarmonyOS 工程没有把它复制到 ohpm 依赖路径的问题。典型报错如下：

ohpm ERROR: Run install command failed
Error: 00617202 Fetch Local Package Failed
Error Message: Fetch local file package error, .../unpackage/dist/dev/app-harmony/uni_modules/hens-print/utssdk/app-harmony/module.har does not exist.

如果遇到该问题，可以向插件作者获取 module.har，并手动放到插件目录：

uni_modules/hens-print/utssdk/app-harmony/module.har

当 HBuilderX 已经创建 HarmonyOS 工程或停在 Install dependencies 步骤时，再把同一个文件复制到生成工程的 ohpm 本地依赖路径：

unpackage/dist/dev/app-harmony/uni_modules/hens-print/utssdk/app-harmony/module.har

本地命令示例：

mkdir -p unpackage/dist/dev/app-harmony/uni_modules/hens-print/utssdk/app-harmony
cp -X uni_modules/hens-print/utssdk/app-harmony/module.har \
  unpackage/dist/dev/app-harmony/uni_modules/hens-print/utssdk/app-harmony/module.har

如果是发行构建，把路径中的 dist/dev 改为 dist/build。HBuilderX 清理或重新生成 app-harmony 工程后，这个文件可能会被删除，需要重新复制一次。该步骤只用于加密试用版的临时兼容；源码版或 HBuilderX 后续修复后不需要手动处理。

快速开始

uni-app X（UTS）

导入：

import {
  print,
  printWebPage,
  printHtmlContent,
  printMultipleImages,
  isPrintableSync,
  setDebugLog,
  getDebugLogStatus
} from '@/uni_modules/hens-print'
import type { PrintOptions } from '@/uni_modules/hens-print'

选择文件并打印：

import { print, isPrintableSync } from '@/uni_modules/hens-print'
import type { PrintOptions } from '@/uni_modules/hens-print'

const selectAndPrint = () => {
  uni.chooseFile({
    count: 1,
    extension: ['pdf', 'png', 'jpg', 'jpeg', 'bmp'],
    success: (res) => {
      const file = res.tempFiles[0]
      if (!isPrintableSync(file.path)) {
        uni.showToast({ title: '文件格式不支持', icon: 'none' })
        return
      }

      const options: PrintOptions = {
        filePath: file.path,
        jobName: `打印任务 - ${file.name}`,
        autoRotateLandscapeImage: true,
        success: (result) => {
          console.log('打印任务已提交', result)
          uni.showToast({ title: '已提交打印', icon: 'success' })
        },
        fail: (err) => {
          console.log('打印失败', err)
          uni.showToast({ title: err.errMsg, icon: 'none' })
        }
      }
      print(options)
    }
  })
}

网页打印：

import { printWebPage } from '@/uni_modules/hens-print'

printWebPage({
  url: 'https://www.example.com',
  jobName: '网页打印',
  timeout: 30, // 单位：秒
  renderDelay: 2000, // 单位：毫秒
  // printReadySelector: '.chartRef-content', // 可选：等待指定节点出现且可见
  // chartContainerSelector: '.chartRef-content', // Android 可选：指定图表容器
  success: (res) => console.log('网页打印任务已提交', res),
  fail: (err) => console.log('网页打印失败', err)
})

HTML 字符串打印：

import { printHtmlContent } from '@/uni_modules/hens-print'

printHtmlContent({
  htmlContent: '<html><body><h1>Hello World</h1><p>HTML 打印</p></body></html>',
  baseUrl: 'https://www.example.com',
  jobName: 'HTML 打印',
  success: (res) => console.log('HTML 打印任务已提交', res),
  fail: (err) => console.log('HTML 打印失败', err)
})

多图片打印：

import { printMultipleImages } from '@/uni_modules/hens-print'

printMultipleImages({
  imagePaths: ['/path/to/image1.jpg', '/path/to/image2.png'],
  jobName: '多图片打印',
  layoutMode: 'double', // single / double / quad；HarmonyOS 当前忽略
  orientation: 'portrait', // portrait / landscape；HarmonyOS 当前忽略
  imageMode: 'fit', // fit / fill；HarmonyOS 当前忽略
  autoRotateLandscapeImage: true, // HarmonyOS 当前忽略
  success: (res) => console.log('多图片打印任务已提交', res),
  fail: (err) => console.log('多图片打印失败', err)
})

调试日志：

import { setDebugLog, getDebugLogStatus } from '@/uni_modules/hens-print'

setDebugLog({
  enabled: true,
  success: () => console.log('已开启打印调试日志')
})

const enabled = getDebugLogStatus()
console.log('打印调试日志状态', enabled)

uni-app（Vue / App 端）

导入：

import {
  print,
  printWebPage,
  printHtmlContent,
  printMultipleImages,
  isPrintableSync,
  setDebugLog,
  getDebugLogStatus
} from '@/uni_modules/hens-print'

打印静态 PDF：

import { print } from '@/uni_modules/hens-print'

// #ifdef APP-PLUS
const filePath = plus.io.convertLocalFileSystemURL('_www/static/dummy.pdf')
print({
  filePath,
  jobName: '测试 PDF 打印',
  success: (res) => console.log('打印任务已提交', res),
  fail: (err) => console.log('打印失败', err)
})
// #endif

在线 PDF 下载后打印：

import { print } from '@/uni_modules/hens-print'

uni.downloadFile({
  url: 'https://example.com/demo.pdf',
  success: (res) => {
    // #ifdef APP-PLUS
    const localPath = plus.io.convertLocalFileSystemURL(res.tempFilePath)
    print({ filePath: localPath, jobName: '在线 PDF 打印' })
    // #endif
  }
})

网页、HTML 和多图片打印的调用方式与 uni-app X 示例一致。

路径与文件说明

• print / printMultipleImages 需要传入 App 端可访问的本地文件路径。
• uni.chooseFile 通常使用 res.tempFiles[0].path。
• uni.chooseImage 通常使用 res.tempFilePaths。
• App 静态资源可通过 plus.io.convertLocalFileSystemURL('_www/static/xxx.pdf') 转换后传入。
• 在线 PDF 或图片需要先通过 uni.downloadFile 下载到本地，再传入本地路径。
• uni-app App 环境建议对临时路径再执行 plus.io.convertLocalFileSystemURL(tempFilePath)，避免虚拟路径导致找不到文件。
• Android 支持 content:// / file:// / 本地路径，插件会尽量转换为可读取文件。
• HarmonyOS 会将以 / 开头的本地路径转换为 file:// 再调用系统打印服务。
• isPrintableSync 主要用于格式和路径初筛，不保证文件内容一定可被系统打印；最终结果以 fail 回调为准。

API 详细说明

print(options: PrintOptions)

打印本地 PDF 文档或单个图片文件。

printWebPage(options: WebPrintOptions)

加载指定 URL 的网页并提交系统打印。

renderDelay 默认策略：

• Android：不传或传 <= 0 时使用智能延迟，页面完全加载约 1000ms，未完全加载约 3000ms。
• iOS：不传时默认 1000ms；传 <= 0 时约 500ms。
• HarmonyOS：网页打印不传时默认 1000ms。

图表页建议：

• 对 ECharts、canvas 等异步渲染页面，建议显式传入 printReadySelector。
• Android 如需提升图表打印稳定性，可传入 chartContainerSelector 精确锁定图表容器。
• iOS / HarmonyOS 当前不会使用 chartContainerSelector。

printHtmlContent(options: HtmlPrintOptions)

打印 HTML 内容字符串。

printMultipleImages(options: MultipleImagesPrintOptions)

打印多张图片。Android / iOS 支持排版参数；HarmonyOS 当前暂不应用布局参数。

isPrintableSync(filePath: string): boolean

同步检查文件是否可被插件识别为支持格式。

const canPrint = isPrintableSync('/path/to/file.pdf')

平台差异：

• Android 会尝试解析路径并检查文件是否存在，再判断扩展名。
• iOS / HarmonyOS 主要根据扩展名判断。
• 返回 true 不代表文件内容一定有效，损坏文件仍可能在打印时失败。

setDebugLog(options: DebugLogOptions)

启用或禁用调试日志。

getDebugLogStatus(): boolean

同步获取当前调试日志开关状态。

回调数据结构

PrintResult

PrintFail

PrintFail 继承 IUniError，常用字段如下：

错误码

常见问题

• success 回调执行了，但打印机没有出纸：success 只表示系统打印任务已创建、提交或打印面板流程成功，不保证物理打印完成，请继续检查系统打印队列和打印机状态。
• 网页打印超时时间异常长：timeout 的单位是秒，不是毫秒；例如 30 秒应传 timeout: 30。
• Android 选择 GIF / TIFF 后不可打印：Android 当前仅支持 PDF、PNG、JPG、JPEG、BMP；如需跨平台一致，建议业务侧限制选择这些格式。
• HarmonyOS 网页 / HTML 打印后仍显示“准备打印”：请确认已升级到当前版本；如仍复现请打开调试日志提供运行日志。
• HarmonyOS 加密试用版构建时报 module.har does not exist：确认 uni_modules/hens-print/utssdk/app-harmony/module.har 存在后，将该文件复制到 unpackage/dist/dev/app-harmony/uni_modules/hens-print/utssdk/app-harmony/module.har，再重新执行 HarmonyOS 构建；发行构建使用 dist/build 路径。
• 网页或图表打印空白：适当增大 renderDelay；图表页建议传 printReadySelector，Android 可额外传 chartContainerSelector。
• 多图片失败：确认 imagePaths 非空、路径可访问、图片格式受当前平台支持；Android / iOS 最多建议 50 张。
• 文件不存在：确认传入的是 App 可访问路径，静态资源或下载文件建议先转换成本地真实路径。
• uni-app X 试用 / 加密模式卡在“准备打印中”：调用 print 时建议显式使用 PrintOptions 类型对象，例如 const options: PrintOptions = {...}; print(options)，避免匿名对象字面量参数推断异常。