更新记录

1.0.3（2026-06-01）

优化已知问题和增加ios 版本

1.0.2（2025-11-18）

优化

1.0.1（2025-03-26）

优化

平台兼容性

uni-app(4.13)

uni-app x(4.11)

xtf-printer

系统打印插件，支持在 uni-app / uni-app x 的 App 端调起系统打印能力，打印本地图片或本地 PDF。

功能说明

• 打印本地图片
• 打印本地 PDF
• 支持设置打印名称
• 支持颜色模式
• 支持纸张尺寸
• 支持打印方向
• 支持图片缩放模式
• 支持自定义页边距

适用范围

平台支持矩阵

支持平台

• uni-app Android App
• uni-app x Android App
• uni-app iOS App
• uni-app x iOS App

不支持平台

• Web
• 微信小程序等小程序平台
• Harmony

使用前提

1. 这是 App 原生打印能力插件，必须在 Android 或 iOS 真机环境下使用。
2. Android 端需要使用自定义基座测试，标准基座下原生依赖无法完整生效。
3. 设备本身需要支持系统打印服务，并已经配置可用打印机或 AirPrint 设备。
4. Android 原生编译时，HBuilderX 运行配置中需要正确配置 JDK 路径。

安装后检查

• 确认插件已安装到 uni_modules/xtf-printer
• 确认 Android 端运行到自定义基座
• 确认待打印文件真实存在
• 确认图片或 PDF 路径可被当前 App 读取

引入方式

import { xtf, PrintPara } from "@/uni_modules/xtf-printer"

API

xtf.isPrinterEnable()

检测当前设备是否可以获取系统打印服务。

const enabled = xtf.isPrinterEnable()
console.log("printer enabled:", enabled)

xtf.printerImage(para)

打印图片。

xtf.printerPdf(para)

打印 PDF。

iOS 参数说明

iOS 端当前优先保证图片和 PDF 的系统打印能力可用，name 会作为打印任务名生效。

以下参数在 iOS 端当前已支持或部分支持：

• name
• orientation

以下参数在 Android 端有实现，但 iOS 端暂未逐项映射到系统打印面板：

• colorMode
• mediaSize
• margins
• scalType

PrintPara 参数说明

export type PrintPara = {
  name?: string
  path: string
  colorMode?: number
  mediaSize?: number
  margins?: number[]
  scalType?: number
  orientation?: number
}

参数说明：

• name：打印任务名称，可选，默认值为 print
• path：待打印文件路径，必填
• colorMode：颜色模式，0 为黑白，1 为彩色
• mediaSize：纸张大小，默认 4，即 A4
• margins：页边距数组，长度必须为 4
• scalType：图片缩放模式，0 为适应，1 为填充
• orientation：打印方向，0 为竖向，1 为横向

mediaSize 对照

• 0：A0
• 1：A1
• 2：A2
• 3：A3
• 4：A4
• 5：A5
• 6：A6
• 7：A7
• 8：A8
• 9：A9
• 10：A10
• 11：B0
• 12：B1
• 13：B2
• 14：B3
• 15 及之后的部分 B 系列值：当前实现仍按插件内部映射处理

路径说明

打印项目内静态资源

支持直接传入 /static/ 开头的路径，例如：

path: "/static/logo.png"

path: "/static/a.pdf"

打印本地绝对路径文件

如果文件不是项目静态资源，也可以传入 Android 可访问的本地绝对路径。

uni-app x 示例

import { xtf, PrintPara } from "@/uni_modules/xtf-printer"

xtf.printerImage({
  name: "image-demo",
  path: "/static/logo.png",
  colorMode: 1,
  orientation: 0,
  scalType: 0
} as PrintPara)

xtf.printerPdf({
  name: "pdf-demo",
  path: "/static/a.pdf",
  colorMode: 1,
  mediaSize: 4,
  orientation: 0
} as PrintPara)

uni-app 示例

import { xtf } from "@/uni_modules/xtf-printer"

xtf.printerImage({
  name: "image-demo",
  path: "/static/logo.png",
  colorMode: 1,
  orientation: 0,
  scalType: 0
})

xtf.printerPdf({
  name: "pdf-demo",
  path: "/static/a.pdf",
  colorMode: 1,
  mediaSize: 4,
  orientation: 0
})

页面按钮示例

<template>
  <view>
    <button @click="printImage">打印图片</button>
    <button @click="printPdf">打印 PDF</button>
  </view>
</template>

<script>
import { xtf, PrintPara } from "@/uni_modules/xtf-printer"

export default {
  methods: {
    printImage() {
      xtf.printerImage({
        name: "test-image",
        path: "/static/logo.png"
      } as PrintPara)
    },
    printPdf() {
      xtf.printerPdf({
        name: "test-pdf",
        path: "/static/a.pdf"
      } as PrintPara)
    }
  }
}
</script>

常见问题

1. 出现 Can print only from an activity

这是 Android 系统打印要求必须从页面 Activity 发起。请使用插件最新版本，并在页面点击事件中调用打印方法，不要在应用未完成页面绑定时提前调用。

2. 为什么标准基座下无法正常打印

因为 Android 端依赖原生能力和三方依赖，标准基座下不能完整生效。请改用自定义基座。

3. 为什么编译时提示需要配置 JDK

因为 Android 原生插件编译依赖本地 JDK。请在 HBuilderX 的运行配置中填写正确的 JDK 根目录，注意不要填写到 bin 目录。iOS 端不依赖这个配置。

4. 为什么点了打印没有反应

请依次检查：

• 是否使用 Android 真机
• Android 端是否使用自定义基座
• 是否已配置系统打印服务
• 文件路径是否正确
• 文件是否真实存在

注意事项

1. 推荐在用户点击按钮后再调用打印。
2. PDF 打印请确保传入的是本地可读文件路径。
3. 图片打印请确保图片文件可正常解码。
4. iOS 端当前已支持 name、orientation，其余部分 Android 参数暂不保证完全对齐。
5. 如果是插件市场购买版，使用前请先在自己的设备和业务场景中完整测试。

更新说明

• 1.0.2：新增 iOS 图片与 PDF 打印支持，并完善文档说明

开发参考

• UTS 语法：https://uniapp.dcloud.net.cn/tutorial/syntax-uts.html
• UTS 插件开发：https://uniapp.dcloud.net.cn/plugin/uts-plugin.html
• UTS 组件开发：https://uniapp.dcloud.net.cn/plugin/uts-component.html