更新记录

1.0.1（2026-08-25）

初版

平台兼容性

uni-app(4.73)

jiakp-bleprint 组件使用说明 & 标签样式修改指南

适用范围：HM-A300 蓝牙标签打印（uni-app / Vue3 项目） 核心文件：

• components/jiakp-bleprint/jiakp-bleprint.vue —— 打印功能组件（搜索/列表/连接/打印）
• pages/index/index.vue —— 页面壳，仅负责标签生成（buildLabel）
• utils/cpcl.js —— CPCL 指令生成器（text/qrcode/line/box 等）
• utils/ble.js / utils/printer.js —— 蓝牙封装与打印写入通道

一、组件设计说明

功能已被拆分为「打印功能组件 + 页面标签生成」两层，解耦后便于复用：

pages/index/index.vue                components/jiakp-bleprint/jiakp-bleprint.vue
┌────────────────────────────┐        ┌──────────────────────────────────────┐
│  buildLabel() 标签生成      │  ────▶ │  props.buildLabel（打印时调用）        │
│  LABEL_WIDTH/HEIGHT 尺寸    │  prop  │  startScan / onPrint / 设备列表等     │
│  onShow 通过 ref 刷新       │        │  mounted / beforeUnmount 生命周期     │
└────────────────────────────┘        └──────────────────────────────────────┘

• 组件负责：蓝牙搜索、设备过滤、倒计时、自动/手动打印、上次使用记忆、连接流程、状态展示。这些与"标签长什么样"无关，任何页面都能直接复用。
• 页面负责：标签内容与样式（buildLabel 方法 + 标签纸尺寸常量）。每个页面可以用不同标签，互不影响。

二、组件使用方法

1. 引入组件

组件路径 components/jiakp-bleprint/jiakp-bleprint.vue 符合 uni-app easycom 约定，理论上可直接使用；为稳妥起见页面手动注册（如下）。

2. 在页面中使用（以 index.vue 为例）

<template>
    <jiakp-bleprint ref="bleprint" :build-label="buildLabel"></jiakp-bleprint>
</template>

<script>
    import Cpcl from '../../utils/cpcl.js'
    import JiakpBleprint from '../../components/jiakp-bleprint/jiakp-bleprint.vue'

    // ===== 标签尺寸配置（单位：点，200dpi 下 1mm ≈ 8 点）=====
    const LABEL_WIDTH = 630   // 标签纸宽度（点），80mm ≈ 630 点
    const LABEL_HEIGHT = 460  // 标签纸高度（点），必须接近实际标签，否则跳纸/底边打不出

    export default {
        components: { JiakpBleprint },
        // 页面每次显示时刷新"上次使用"设备（组件 mounted 时已加载并触发首次搜索）
        onShow() {
            if (this.$refs.bleprint) {
                this.$refs.bleprint.loadLastPrinter()
            }
        },
        methods: {
            buildLabel() {
                // ...返回 CPCL 字节数组（见下文"标签样式修改"）
                return new Cpcl.Cpcl().start(LABEL_HEIGHT) /* ... */ .build()
            }
        }
    }
</script>

3. Props

⚠️ 必传：组件在搜索到恰好 1 台设备时会自动触发 onPrint，此时会调用 buildLabel；不传会报错。

4. 组件对外方法（页面可通过 ref 调用）

5. 组件内部配置常量（改机型/搜索参数时用）

位于 jiakp-bleprint.vue 的 <script> 顶部：

三、生命周期说明（重要）

普通组件中 uni-app 的页面生命周期 onLoad/onShow/onUnload 不生效（官方文档明确），组件已做等价替换：

在页面中新增 <jiakp-bleprint> 后，首次进入：页面 onLoad → 组件 mounted（开始搜索）→ 页面 onShow（刷新上次设备），与原页面行为一致。

四、标签样式修改指南（改的是页面里的 buildLabel）

1. 核心结论

• 标签上所有文字、位置、字号、表格线、二维码都在 pages/index/index.vue 的 buildLabel() 方法里，用链式 Cpcl 指令拼装。
• 标签纸尺寸由页面顶部的 LABEL_WIDTH / LABEL_HEIGHT 常量控制。
• 改样式基本不动组件，只改 buildLabel() 里的参数 + 必要时调尺寸常量；utils/cpcl.js 是底层指令封装，一般也不要动。

2. buildLabel() 指令块解析

3. 坐标系与属性速查

• 坐标系：单位是点，原点在左上角，x 向右、y 向下；当前为 200dpi，1mm ≈ 8 点。
• V = 315（buildLabel 内局部常量）：贯穿竖线 x 坐标，右侧内容（第二字段 / 二维码）都相对它定位（V + 15），改竖线位置要同步改所有 V + 15 引用。
• 行高规律：当前每行约 48 点（如第一行 84→132、第二行 132→180…），文字 y ≈ 行顶 + 14 垂直居中；增删行时同步调整各 .line() 分隔线和各 .text() 的 y。
• text() 属性：font（CPCL 字号，数字越小越小，正文用 3、标题默认 4）、bold、underline、x/y。
• qrcode() 属性：size（模块大小，当前 9，范围约 4~10）、errorCorrection（纠错 1~4，4 最高，当前 3）。
• line()/box() 属性：起止坐标 + 线宽（最后一个数字）。

4. 常见修改场景速查

5. 修改注意事项

1. 改完先小批量打样：坐标、字号改动后务必先用一张标签纸试打，重点看文字是否裁切/错位、底边是否完整。
2. LABEL_HEIGHT 别乱改：不匹配会跳纸、漏打底边，是最常见的坑。
3. 保持 .align() 对称：用了 CENTER/RIGHT 后必须切回 LEFT，否则后续文本 x 坐标失效。
4. 中文依赖 GBK 编码（utils/cpcl.js）：仅在 App-Android 真机 100% 准确，H5/小程序会回退 UTF-8 可能乱码——验证请在真机 App 上进行。
5. 坐标是写死的：改一处通常要连带重排后续行，建议按"行高=48、文字 y=行顶+14"的规律统一推算。
6. 组件与页面分工别混淆：搜索/打印参数（DEVICE_PREFIX、SCAN_TIMEOUT）在组件里；标签内容/尺寸（LABEL_WIDTH/HEIGHT、buildLabel）在页面里。

五、文件结构参考

hmprint/
├─ components/jiakp-bleprint/jiakp-bleprint.vue  ← 打印功能组件（本说明对象）
├─ pages/index/index.vue                       ← 页面壳 + buildLabel 标签生成
├─ utils/cpcl.js                               ← CPCL 指令生成器
├─ utils/ble.js                                ← 蓝牙封装
├─ utils/printer.js                            ← 打印写入通道（ble 模式）
├─ pages.json                                  ← 页面注册与导航栏标题
└─ App.vue / main.js / manifest.json / uni.scss