更新记录

1.0.5（2026-01-16）

文档更新：补充平台与版本说明、示例代码、路径说明、错误码与常见问题，统一 README 结构。

1.0.4（2025-11-21）

-

1.0.3（2025-09-05）

Android 修复：打印预览切换纸张（大小/方向）后“无法工作”问题。

• 调整 WebView 生命周期管理：由“任务创建后 2 秒清理”改为在 PrintDocumentAdapter.onFinish() 中清理，确保系统在切换纸张时可重复调用 onLayout/onWrite 完成重排。
• 提升 HTML 片段与网页打印在 Android 上的稳定性。

平台兼容性

uni-app(4.75)

uni-app x(4.75)

hens-print

当前版本：v1.0.5

插件简介

hens-print 是一个 uni-app / uni-app X 通用的打印插件，使用 UTS (UniType Script) 开发，支持 Android 与 iOS。可打印 PDF、图片、网页 URL 以及 HTML 字符串，并提供多图片排版、调试日志与错误码。

功能特性

• 📄 PDF文档打印 - 支持直接打印 PDF 文件
• 🖼️ 图片打印 - 支持 PNG / JPEG / GIF / BMP / TIFF
• 🖼️ 多图片打印 - 支持一次性打印多张图片，可配置布局与排版
• 🌐 网页打印 - 支持通过 URL 打印网页，支持超时与渲染延迟
• 📝 HTML内容打印 - 支持直接打印 HTML 字符串，可指定 baseUrl
• 🔍 文件检查 - 提供同步文件格式支持检查功能
• 🐛 调试支持 - 可启用/禁用调试日志
• ✅ 错误处理 - 明确的错误码体系便于排查

支持平台与版本

• ✅ uni-app（App 端：Android / iOS）
• ✅ uni-app X（App 端：Android / iOS）
• ❌ H5 / 小程序 / 快应用

版本要求：

• HBuilderX >= 3.6.8
• uni-app >= 4.75
• uni-app X >= 4.75

安装方式

1. 将 hens-print 插件文件夹复制到项目的 uni_modules 目录下
2. 在页面中按需导入即可使用

Demo 关键代码片段（节选）

uni-app X 片段（UTS）

选择文件 + 打印：

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

const selectAndPrint = () => {
  uni.chooseFile({
    count: 1,
    extension: ['pdf', 'png', 'jpg', 'jpeg', 'gif', 'bmp', 'tiff'],
    success: (res) => {
      const file = res.tempFiles[0]
      const canPrint = isPrintableSync(file.path)
      if (!canPrint) {
        uni.showToast({ title: '文件格式不支持', icon: 'none' })
        return
      }
      print({
        filePath: file.path,
        jobName: `打印任务 - ${file.name}`,
        success: () => uni.showToast({ title: '打印成功', icon: 'success' }),
        fail: (err) => uni.showToast({ title: err.errMsg, icon: 'none' })
      })
    }
  })
}

网页 / HTML 打印：

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

printWebPage({
  url: 'https://www.baidu.com',
  timeout: 30_000,
  renderDelay: 0, // 0 表示使用默认智能延迟
  success: () => console.log('网页打印成功'),
  fail: (err) => console.log(err)
})

printHtmlContent({
  htmlContent: '<h1>Hello World</h1><p>HTML 打印</p>',
  baseUrl: '',
  success: () => console.log('HTML 打印成功'),
  fail: (err) => console.log(err)
})

多图片打印：

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

const imagePaths = ['/path/a.jpg', '/path/b.jpg']
printMultipleImages({
  imagePaths,
  layoutMode: 'single',
  orientation: 'portrait',
  imageMode: 'fit',
  autoRotateLandscapeImage: true
})

uni-app 片段（Vue）

打印测试 PDF（App 端）：

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 下载后打印（App 端需转换路径）：

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
  }
})

选择文件（uni.chooseFile + 回退）：

const selectFile = () => {
  if (uni.chooseFile) {
    uni.chooseFile({
      count: 1,
      extension: ['pdf', 'png', 'jpg', 'jpeg', 'gif', 'bmp', 'tiff'],
      success: (res) => {
        const file = res.tempFiles[0]
        console.log('文件路径:', file.path)
      },
      fail: () => fallbackChooseImage()
    })
  } else {
    fallbackChooseImage()
  }
}

const fallbackChooseImage = () => {
  uni.chooseImage({
    count: 1,
    sizeType: ['original'],
    sourceType: ['album', 'camera'],
    success: (res) => {
      console.log('图片路径:', res.tempFilePaths[0])
    }
  })
}

快速开始

uni-app X（App）

导入：

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

打印 PDF / 图片：

print({
  filePath: '/path/to/your/file.pdf',
  jobName: '我的打印任务',
  autoRotateLandscapeImage: true,
  success: (res) => {
    console.log('打印成功', res)
  },
  fail: (err) => {
    console.log('打印失败', err)
  }
})

网页打印：

printWebPage({
  url: 'https://www.example.com',
  jobName: '网页打印',
  timeout: 30000,
  // renderDelay: 2000, // 指定渲染延迟（毫秒），不传则智能处理
  success: (res) => {
    console.log('网页打印成功', res)
  },
  fail: (err) => {
    console.log('网页打印失败', err)
  }
})

HTML 字符串打印：

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

多图片打印：

printMultipleImages({
  imagePaths: ['/path/to/image1.jpg', '/path/to/image2.png'],
  jobName: '多图片打印',
  layoutMode: 'double', // single / double / quad
  orientation: 'portrait', // portrait / landscape
  imageMode: 'fit', // fit / fill
  autoRotateLandscapeImage: true,
  success: (res) => {
    console.log('多图片打印成功', res)
  },
  fail: (err) => {
    console.log('多图片打印失败', err)
  }
})

uni-app（App）

导入：

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

打印静态 PDF（App 端）：

// #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

网页 / HTML / 多图 与 uni-app X 的调用方式一致（可直接参考上面的示例）。

路径与文件说明

• 选择文件：
  • uni.chooseFile 返回 tempFiles[0].path
  • uni.chooseImage 返回 tempFilePaths
• 静态资源：
  • App 端可用 plus.io.convertLocalFileSystemURL('_www/static/xxx.pdf')
• 在线 PDF：
  • 需要先下载到本地（临时或持久目录）再传入 filePath 打印
  • uni-app（App）环境建议再做一次路径转换：plus.io.convertLocalFileSystemURL(tempFilePath)，避免虚拟路径导致找不到文件
• 注意：
  • 插件仅支持 App 端，建议使用条件编译 #ifdef APP-PLUS 保护调用

API 详细说明

print(options: PrintOptions)

打印 PDF 文档或图片文件。

printWebPage(options: WebPrintOptions)

打印指定 URL 的网页内容。

renderDelay 默认策略：页面完全加载时约 1000ms，未完全加载时约 3000ms。如页面有复杂渲染，可手动加大。

printHtmlContent(options: HtmlPrintOptions)

打印 HTML 内容字符串。

printMultipleImages(options: MultipleImagesPrintOptions)

打印多张图片，支持多种布局模式和排版选项。

isPrintableSync(filePath: string): boolean

同步检查文件是否支持打印。

setDebugLog(options: DebugLogOptions)

启用 / 禁用调试日志。

getDebugLogStatus(): boolean

获取当前调试日志状态。

错误码

• 9080001 文件不存在
• 9080002 文件格式不支持
• 9080003 打印机不可用
• 9080004 打印参数无效
• 9080005 打印失败
• 9080006 系统权限不足
• 9080007 打印服务不可用
• 9080009 URL格式无效
• 9080010 网络连接失败
• 9080011 网页加载超时
• 9080012 HTML内容解析失败
• 9080013 用户取消打印
• 9080014 图片列表为空
• 9080015 部分图片文件无效

常见问题

• 打印失败 / 文件不存在：确认 filePath 指向真实可访问路径（App 端静态资源需转换路径）。
• 网页打印空白：可适当增大 renderDelay，或确认页面未被重定向/拦截。
• 多图片失败：确保 imagePaths 非空且路径有效，图片格式支持。
• 只在 App 可用：H5/小程序不支持，请使用条件编译保护调用。