更新记录
1.0.0(2025-08-19)
hens-print
是一个功能完整的 uni-app X 打印插件,使用 UTS (UniType Script) 开发,支持 Android 和 iOS 双平台。插件提供了丰富的打印功能,可以打印 PDF 文档、图片文件、网页内容和 HTML 字符串。
平台兼容性
uni-app(4.76)
Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
---|---|---|---|---|---|---|---|---|
√ | √ | - | - | √ | - | √ | √ | - |
微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 快应用-华为 | 快应用-联盟 |
---|---|---|---|---|---|---|---|---|---|---|
- | - | - | - | - | - | - | - | - | - | - |
uni-app x(4.76)
Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
---|---|---|---|---|---|
- | - | √ | √ | - | - |
hens-print
插件简介
hens-print
是一个功能完整的 uni-app X 打印插件,使用 UTS (UniType Script) 开发,支持 Android 和 iOS 双平台。插件提供了丰富的打印功能,可以打印 PDF 文档、图片文件、网页内容和 HTML 字符串。
功能特性
- 📄 PDF文档打印 - 支持直接打印PDF文件
- 🖼️ 图片打印 - 支持PNG、JPEG、GIF、BMP、TIFF格式
- 🌐 网页打印 - 支持通过URL打印网页,包含渲染控制
- 📝 HTML内容打印 - 支持直接打印HTML字符串,可指定基础URL
- 🔍 文件检查 - 提供同步文件格式支持检查功能
- 🐛 调试支持 - 可启用/禁用调试日志,便于开发调试
- ✅ 错误处理 - 完整的错误码体系,便于调试和处理异常
安装方式
- 将
hens-print
插件文件夹复制到项目的uni_modules
目录下 - 在需要使用的页面中导入插件
快速开始
基础导入
import { print, printWebPage, printHtmlContent, isPrintableSync, setDebugLog, getDebugLogStatus } from '@/uni_modules/hens-print'
打印PDF或图片文件
print({
filePath: '/path/to/your/file.pdf',
jobName: '我的打印任务',
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)
}
})
检查文件是否支持打印
const canPrint = isPrintableSync('/path/to/your/file.pdf')
console.log('文件是否支持打印:', canPrint)
调试日志控制
// 启用调试日志
setDebugLog({
enabled: true,
success: () => {
console.log('调试日志已启用')
},
fail: (err) => {
console.error('调试日志设置失败:', err)
}
})
// 获取当前调试状态
const isDebugEnabled = getDebugLogStatus()
console.log('调试日志状态:', isDebugEnabled)
API 详细说明
print(options: PrintOptions)
打印PDF文档或图片文件。
参数说明:
参数 | 类型 | 必填 | 默认值 | 说明 |
---|---|---|---|---|
filePath | string | 是 | - | 文件路径 |
jobName | string | 否 | - | 打印任务名称 |
success | function | 否 | - | 成功回调 |
fail | function | 否 | - | 失败回调 |
complete | function | 否 | - | 完成回调 |
printWebPage(options: WebPrintOptions)
打印指定URL的网页内容。
参数说明:
参数 | 类型 | 必填 | 默认值 | 说明 |
---|---|---|---|---|
url | string | 是 | - | 网页URL |
timeout | number | 否 | 30000 | 网络超时时间(毫秒) |
renderDelay | number | 否 | 智能检测 | 页面渲染延迟(毫秒) |
jobName | string | 否 | - | 打印任务名称 |
success | function | 否 | - | 成功回调 |
fail | function | 否 | - | 失败回调 |
complete | function | 否 | - | 完成回调 |
printHtmlContent(options: HtmlPrintOptions)
打印HTML内容字符串。
参数说明:
参数 | 类型 | 必填 | 默认值 | 说明 |
---|---|---|---|---|
htmlContent | string | 是 | - | HTML内容 |
baseUrl | string | 否 | - | 基础URL,用于解析相对路径 |
jobName | string | 否 | - | 打印任务名称 |
success | function | 否 | - | 成功回调 |
fail | function | 否 | - | 失败回调 |
complete | function | 否 | - | 完成回调 |
isPrintableSync(filePath: string): boolean
同步检查文件是否支持打印。
参数说明:
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
filePath | string | 是 | 文件路径 |
返回值: boolean - 是否支持打印
setDebugLog(options: DebugLogOptions)
设置调试日志开启或关闭状态。
参数说明:
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
enabled | boolean | 是 | 是否启用调试日志 |
success | function | 否 | 成功回调 |
fail | function | 否 | 失败回调 |
complete | function | 否 | 完成回调 |
getDebugLogStatus(): boolean
获取当前调试日志的开启状态。
返回值: boolean - 调试日志是否已启用
支持的文件格式
图片格式
- PNG
- JPEG/JPG
- GIF
- BMP
- TIFF
文档格式
网页内容
- 任何可访问的HTTP/HTTPS URL
- HTML字符串内容
错误处理
插件提供了完整的错误码体系,便于开发者处理各种异常情况:
错误码 | 说明 |
---|---|
9080001 | 文件不存在 |
9080002 | 文件格式不支持 |
9080003 | 打印机不可用 |
9080004 | 打印参数无效 |
9080005 | 打印失败 |
9080006 | 系统权限不足 |
9080007 | 打印服务不可用 |
9080009 | URL格式无效 |
9080010 | 网络连接失败 |
9080011 | 网页加载超时 |
9080012 | HTML内容解析失败 |
9080013 | 用户取消打印操作 |
平台限制说明
Android 平台
- 支持所有打印功能,打印设置通过系统打印对话框进行配置
iOS 平台
- 支持所有打印功能,打印设置通过系统打印对话框进行配置
功能支持对比
功能 | Android | iOS | 说明 |
---|---|---|---|
PDF 打印 | ✅ | ✅ | 完全支持 |
图片打印 | ✅ | ✅ | 支持多种格式 |
网页打印 | ✅ | ✅ | 支持 URL 打印 |
HTML 内容打印 | ✅ | ✅ | 支持 HTML 字符串 |
调试日志 | ✅ | ✅ | 可动态开启/关闭 |
文件格式检查 | ✅ | ✅ | 同步检查支持 |
使用注意事项
- 文件路径: 确保文件路径正确且文件存在
- 权限要求: 确保应用具有访问存储和打印的权限
- 网络连接: 网页打印需要网络连接
- 渲染延迟: 复杂网页可能需要调整
renderDelay
参数 - 调试日志: 开发时可启用调试日志查看详细执行信息
- 打印设置: 打印方向、纸张大小、份数等设置通过系统打印对话框进行配置