taro-bluetooth-print 2.8.1 → 2.8.4

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.8.4] - 2026-04-05
+
+### 修复
+
+- image.ts: 添加 TypeScript strict mode non-null assertions，解决 noUncheckedIndexedAccess 警告
+
+### 性能优化
+
+- image.ts: 移除 TypedArray 访问上的冗余 `?? 0` / `?? 255` 操作符
+
+## [2.8.3] - 2026-04-04
+
+### 性能优化
+
+- image.ts: 移除 TypedArray 访问上的冗余 `?? 0` / `?? 255` 操作符（Uint8Array/Float32Array 元素访问永不返回 undefined）
+- 影响函数：toGrayscale、adjustContrastBrightness、所有 dithering 算法、applyBilinearInterpolation、applyGammaCorrection、applyMedianFilter、applyConvolution、applyPixelate
+- gzip 体积：225.96 KB → 225.79 KB（-0.17 KB），代码净减 1 行
+
 ## [2.8.1] - 2026-04-02
 
 ### 修复

package/README.md

@@ -1,75 +1,53 @@
 # Taro Bluetooth Print
 
 <p align="center">
-  <img src="https://img.shields.io/npm/v/taro-bluetooth-print?style=flat-square&color=00d8ff" alt="npm version">
-  <img src="https://img.shields.io/npm/dm/taro-bluetooth-print?style=flat-square&color=00d8ff" alt="downloads">
-  <img src="https://img.shields.io/npm/l/taro-bluetooth-print?style=flat-square&color=00d8ff" alt="license">
-  <img src="https://img.shields.io/github/stars/agions/taro-bluetooth-print?style=flat-square" alt="stars">
-  <img src="https://img.shields.io/github/forks/agions/taro-bluetooth-print?style=flat-square" alt="forks">
-  <img src="https://img.shields.io/bundlephobia/minzip/taro-bluetooth-print?style=flat-square" alt="bundle size">
+  <a href="https://www.npmjs.com/package/taro-bluetooth-print" target="_blank"><img src="https://img.shields.io/npm/v/taro-bluetooth-print?style=flat-square&color=4338ca" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/taro-bluetooth-print" target="_blank"><img src="https://img.shields.io/npm/dm/taro-bluetooth-print?style=flat-square&color=4338ca" alt="downloads"></a>
+  <a href="https://github.com/agions/taro-bluetooth-print/blob/main/LICENSE" target="_blank"><img src="https://img.shields.io/npm/l/taro-bluetooth-print?style=flat-square&color=4338ca" alt="license"></a>
+  <a href="https://github.com/agions/taro-bluetooth-print" target="_blank"><img src="https://img.shields.io/github/stars/agions/taro-bluetooth-print?style=flat-square" alt="stars"></a>
+  <a href="https://github.com/agions/taro-bluetooth-print" target="_blank"><img src="https://img.shields.io/github/forks/agions/taro-bluetooth-print?style=flat-square" alt="forks"></a>
+  <a href="https://bundlephobia.com/package/taro-bluetooth-print" target="_blank"><img src="https://img.shields.io/bundlephobia/minzip/taro-bluetooth-print?style=flat-square" alt="bundle size"></a>
 </p>
 
 <p align="center">
-  <strong>轻量级、高性能的 Taro 蓝牙打印库</strong><br>
-  支持热敏票据打印机、标签打印机，覆盖 8+ 平台
+  轻量级、高性能的 Taro 蓝牙打印库 · 支持热敏票据、标签打印，覆盖 8+ 平台
 </p>
 
 ---
 
-## 特性
+## 特性亮点
 
-### 核心能力
+### 基础能力
 
-| 特性 | 说明 |
+| 能力 | 说明 |
 |------|------|
-| 高性能打印 | 直接操作字节缓冲区，服务端缓存优化 |
 | 多平台适配 | 微信/支付宝/百度/字节跳动/QQ 小程序，H5 WebBluetooth，鸿蒙，React Native |
 | 多协议驱动 | ESC/POS（热敏）、TSPL/ZPL/CPCL（标签）、STAR 系列 |
-| TypeScript | 完整类型定义，IDE 智能提示 |
+| 链式调用 | `printer.text(...).feed().qr(...).cut().print()`，IDE 自动补全 |
+| TypeScript | 完整类型定义，无任何 `any` 暴露，无外部依赖 |
+| 编码支持 | GBK / GB2312 / Big5 / UTF-8 / EUC-KR / Shift-JIS / ISO-2022-JP |
 
 ### 高级打印
 
-| 特性 | 说明 |
+| 能力 | 说明 |
 |------|------|
-| 图片打印 | Floyd-Steinberg 抖动算法，6 种抖动模式 |
-| 二维码/条码 | 原生指令支持，多种格式，格式校验 |
-| 暂停/恢复/取消 | 完整的打印任务控制 |
-| 离线缓存 | 断网自动缓存，来网自动同步 |
-| 打印队列 | 优先级排序，失败自动重试 |
-| 模板引擎 | 支持循环、条件、边框、表格等语法 |
-| 打印预览 | ESC/POS 命令渲染为图像预览 |
-| 插件系统 | 可扩展架构，支持自定义钩子 |
+| 图片打印 | Floyd-Steinberg 抖动算法，6 种抖动模式，RGBA → 黑白位图 |
+| 二维码/条码 | 原生指令支持 Code128/EAN/UPC/QR/PDF417 等 10+ 格式 |
+| 模板引擎 | loop 循环 / condition 条件 / border 边框 / table 表格，小票标签一键渲染 |
+| 暂停/恢复/取消 | 完整的打印任务生命周期控制 |
+| 打印预览 | ESC/POS 命令实时渲染为 Canvas 图像，调试所见即所得 |
 
 ### 运维管理
 
-| 特性 | 说明 |
+| 能力 | 说明 |
 |------|------|
-| 多打印机管理 | MultiPrinterManager 支持多设备并发 |
-| 打印历史 | PrintHistory 追踪打印记录和统计 |
-| 定时重试 | ScheduledRetryManager 指数退避，重启恢复 |
-| 状态检测 | PrinterStatus 检测纸张/电量状态 |
-| 批量优化 | BatchPrintManager 合并小任务减少开销 |
-| 定时调度 | PrintScheduler 支持 cron/一次性/重复间隔任务 |
-| 设备发现 | DiscoveryService 增强型过滤排序和设备缓存 |
-
-### 编码支持
-
-GBK / GB2312 / Big5 / UTF-8 / EUC-KR（韩文）/ Shift-JIS / ISO-2022-JP（日文）
-
----
-
-## 安装
-
-```bash
-# npm
-npm install taro-bluetooth-print
-
-# yarn
-yarn add taro-bluetooth-print
-
-# pnpm
-pnpm add taro-bluetooth-print
-```
+| 离线缓存 | 断网自动缓存，来网自动同步，零任务丢失 |
+| 打印队列 | 优先级排序，失败自动重试，死链自动剔除 |
+| 多打印机管理 | MultiPrinterManager 多设备并发，支持负载均衡 |
+| 打印历史 | PrintHistory 完整记录，含耗时/字节数/成功率统计 |
+| 定时重试 | ScheduledRetryManager 指数退避，进程重启后自动恢复调度 |
+| 定时调度 | PrintScheduler 支持 cron 表达式/一次性/间隔重复任务 |
+| 设备发现 | DiscoveryService 增强型过滤、排序、RSSI 缓存 |
 
 ---
 
@@ -77,14 +55,19 @@ pnpm add taro-bluetooth-print
 
 | 指标 | 值 |
 |------|-----|
-| 包体积 | **26 KB**（gzip） |
-| Tree-shaking | 支持 |
-| 按需加载 | 编码表懒加载 |
+| 包体积（gzip） | **~226 KB**（含全部驱动，无外部依赖） |
+| Tree-shaking | ✅ 支持，import { BluetoothPrinter } 即用 |
+| 按需加载 | ✅ 编码表懒加载，未用到的字符集不进入产物 |
+| 测试覆盖 | ✅ 648 个用例，CI 全链路通过 |
 
 ---
 
 ## 快速开始
 
+```bash
+pnpm add taro-bluetooth-print
+```
+
 ```typescript
 import { BluetoothPrinter, DeviceManager } from 'taro-bluetooth-print';
 
@@ -103,7 +86,7 @@ async function print() {
   const printer = new BluetoothPrinter();
   await printer.connect(devices[0].deviceId);
 
-  // 3. 打印
+  // 3. 链式调用打印
   await printer
     .text('=== 欢迎光临 ===', 'GBK')
     .feed()
@@ -113,57 +96,57 @@ async function print() {
     .text('------------------------')
     .text('合计：            ¥30.00', 'GBK')
     .feed(2)
-    .qr('https://example.com')
+    .qr('https://example.com', { size: 6 })
     .feed(2)
     .cut()
     .print();
 
-  // 4. 断开
   await printer.disconnect();
-
-  console.log('打印完成！');
 }
 ```
 
 ---
 
-## 支持的平台
+## 平台与驱动
+
+### 支持的平台
 
 | 平台 | 适配器 | 状态 |
 |------|--------|------|
-| 微信小程序 | `TaroAdapter` | [x] |
-| H5 (Web Bluetooth) | `WebBluetoothAdapter` | [x] |
-| 支付宝小程序 | `AlipayAdapter` | [x] |
-| 百度小程序 | `BaiduAdapter` | [x] |
-| 字节跳动小程序 | `ByteDanceAdapter` | [x] |
-| QQ 小程序 | `QQAdapter` | [x] |
-| 鸿蒙 HarmonyOS | `HarmonyOSAdapter` | [x] |
-| React Native | `ReactNativeAdapter` | [x] |
-
----
-
-## 支持的驱动
-
-| 驱动 | 协议 | 适用打印机 |
-|------|------|-----------|
-| `EscPos` | ESC/POS | 热敏票据打印机（58/80mm） |
-| `TsplDriver` | TSPL | TSC 标签打印机 |
-| `ZplDriver` | ZPL | Zebra 斑马标签打印机 |
-| `CpclDriver` | CPCL | HP/霍尼韦尔移动打印机 |
-| `StarPrinter` | STAR | STAR TSP/SP700 系列票据打印机 |
+| 微信小程序 | `TaroAdapter` | ✅ |
+| H5 (Web Bluetooth) | `WebBluetoothAdapter` | ✅ |
+| 支付宝小程序 | `AlipayAdapter` | ✅ |
+| 百度小程序 | `BaiduAdapter` | ✅ |
+| 字节跳动小程序 | `ByteDanceAdapter` | ✅ |
+| QQ 小程序 | `QQAdapter` | ✅ |
+| 鸿蒙 HarmonyOS | `TaroAdapter` | ✅ |
+| React Native | `ReactNativeAdapter` | ✅ |
+
+### 支持的驱动
+
+| 驱动 | 协议 | 典型品牌 |
+|------|------|---------|
+| `EscPos` | ESC/POS | 佳博、芯烨、商米、汉印 |
+| `TsplDriver` | TSPL | TSC ME240、TA210、TTP-244 |
+| `ZplDriver` | ZPL | Zebra ZD420、GT800、ZM400 |
+| `CpclDriver` | CPCL | HP IR3222、霍尼韦尔移动机 |
+| `StarPrinter` | STAR | STAR TSP100、TSP700、TSP800 |
+| `GPrinterDriver` | 自定义 | 佳博 GP-5890X 系列 |
+| `XprinterDriver` | ESC/POS | 芯烨 XP-58 系列 |
+| `SprtDriver` | ESC/POS | 思普瑞特系列 |
 
 ---
 
-## 配置
+## 配置与事件
 
 ```typescript
 const printer = new BluetoothPrinter();
 
-// 适配器参数
+// 传输参数
 printer.setOptions({
-  chunkSize: 20,   // 分片大小（默认 20）
+  chunkSize: 20,  // 分片大小 byte（默认 20）
   delay: 20,       // 分片间隔 ms（默认 20）
-  retries: 3,     // 重试次数（默认 3）
+  retries: 3,     // 写入失败重试次数（默认 3）
 });
 
 // 事件监听
@@ -185,80 +168,68 @@ printer.on('print-complete', () => {
 ## 架构
 
 ```
-  +----------------------+
-  |  BluetoothPrinter     |
-  |  (Core)              |
-  +----------+-----------+
-             |
-       +-----+-----+
-       |           |
-  +----v---+   +---v----+
-  | Driver |   | Adapter |
-  | Layer  |   | Layer   |
-  +---+----+   +----+----+
-      |             |
-      +------+------+
-             |
-       +-----v-----+
-       | Services  |
-       | (PrintJob, |
-       |  Cache,    |
-       |  Queue...) |
-       +-----------+
+  ┌─────────────────────────────────────────┐
+  │           BluetoothPrinter (Core)        │
+  │  text() feed() qr() cut() image() print()│
+  └──────────────┬──────────────────────────┘
+                 │
+       ┌─────────┼─────────┐
+       ▼                     ▼
+  ┌─────────┐          ┌──────────┐
+  │ Drivers │          │ Adapters │
+  │ EscPos  │          │ TaroAdapter│
+  │ Tspl    │          │ WebBluetooth│
+  │ Zpl     │          │ ReactNative │
+  └────┬────┘          └─────┬────┘
+       └──────────┬──────────┘
+                  ▼
+  ┌──────────────────────────────────────┐
+  │              Services                  │
+  │ PrintJob · Cache · Queue · History   │
+  │ Statistics · Scheduler · Batch        │
+  └──────────────────────────────────────┘
 ```
 
 ---
 
 ## 示例项目
 
-- [微信小程序示例](https://github.com/Agions/taro-bluetooth-print/tree/main/examples/weapp)
-- [H5 示例](https://github.com/Agions/taro-bluetooth-print/tree/main/examples/h5)
-- [鸿蒙示例](https://github.com/Agions/taro-bluetooth-print/tree/main/examples/harmonyos)
-- [React Native 示例](https://github.com/Agions/taro-bluetooth-print/tree/main/examples/react-native)
+| 示例 | 路径 |
+|------|------|
+| 微信小程序 | [examples/weapp](./examples/weapp) |
+| H5 | [examples/h5](./examples/h5) |
+| 鸿蒙 | [examples/harmonyos](./examples/harmonyos) |
+| React Native | [examples/react-native](./examples/react-native) |
 
 ---
 
 ## 文档
 
-- [快速开始](https://agions.github.io/taro-bluetooth-print/guide/getting-started) - 5 分钟入门
-- [功能特性](https://agions.github.io/taro-bluetooth-print/guide/features) - 全部功能介绍
-- [驱动支持](https://agions.github.io/taro-bluetooth-print/guide/drivers) - ESC/POS、TSPL、ZPL、CPCL
-- [核心概念](https://agions.github.io/taro-bluetooth-print/guide/core-concepts) - 架构设计与原理
-- [API 参考](https://agions.github.io/taro-bluetooth-print/api) - 完整的 API 文档
-- [常见问题](https://agions.github.io/taro-bluetooth-print/guide/faq) - FAQ
+- [快速开始](https://agions.github.io/taro-bluetooth-print/guide/getting-started) · 5 分钟入门
+- [功能特性](https://agions.github.io/taro-bluetooth-print/guide/features) · 全部功能
+- [驱动支持](https://agions.github.io/taro-bluetooth-print/guide/drivers) · ESC/POS、TSPL、ZPL
+- [核心概念](https://agions.github.io/taro-bluetooth-print/guide/core-concepts) · 架构设计
+- [API 参考](https://agions.github.io/taro-bluetooth-print/api) · 完整 API
+- [常见问题](https://agions.github.io/taro-bluetooth-print/guide/faq) · FAQ
 
 ---
 
-## 贡献
-
-欢迎贡献代码！
+## 开发
 
 ```bash
-# 克隆仓库
 git clone https://github.com/Agions/taro-bluetooth-print.git
 cd taro-bluetooth-print
-
-# 安装依赖
 pnpm install
 
-# 运行测试
-pnpm test
-
-# 构建
-pnpm build
-
-# 本地文档
-pnpm docs:dev
+pnpm test       # 测试（648 用例）
+pnpm lint       # ESLint + Prettier
+pnpm type-check # TypeScript 检查
+pnpm build      # 构建产物
+pnpm docs:dev   # 本地文档
 ```
 
 ---
 
 ## 许可证
 
-[MIT](./LICENSE) © Agions
-
----
-
-<p align="center">
-  Made with ❤️ by <a href="https://github.com/agions">Agions</a>
-</p>
+[MIT](./LICENSE) · Copyright © 2024-present Agions