@m430/capacitor-label-printer 0.1.0

package/API.md

@@ -0,0 +1,218 @@
+# API
+
+`@m430/capacitor-label-printer` 当前公开的是一组偏底层的打印能力，业务层建议自行封装打印模板、重试策略和任务队列。
+
+## 方法
+
+### `isSupported()`
+
+判断当前运行环境是否支持原生标签打印。
+
+返回：
+
+```ts
+Promise<{ supported: boolean }>
+```
+
+### `checkPermissions()`
+
+查询当前蓝牙权限状态。
+
+返回：
+
+```ts
+Promise<PrinterPermissionResult>
+```
+
+### `ensurePermissions()`
+
+确保蓝牙访问权限已就绪。
+
+- Android：会主动触发“附近设备”权限申请
+- iOS：首版会返回结构化权限状态，真实系统授权仍由蓝牙扫描/连接行为触发
+
+返回：
+
+```ts
+Promise<PrinterPermissionResult>
+```
+
+### `discoverDevices(options?)`
+
+发现可用于连接的打印机列表。
+
+参数：
+
+```ts
+interface DiscoverDevicesOptions {
+  timeout?: number;
+  namePrefixes?: string[];
+}
+```
+
+返回：
+
+```ts
+Promise<{ devices: PrinterDevice[] }>
+```
+
+说明：
+
+- Android 上如果权限不足，插件会在内部先尝试申请权限
+- 权限仍不足时会抛出 `PERMISSION_DENIED`
+
+### `connect(options)`
+
+连接指定打印机。
+
+参数：
+
+```ts
+interface ConnectOptions {
+  deviceId: string;
+}
+```
+
+返回：
+
+```ts
+Promise<void>
+```
+
+### `disconnect()`
+
+断开当前打印机连接。
+
+返回：
+
+```ts
+Promise<void>
+```
+
+### `getConnectionState()`
+
+查询当前连接状态。
+
+返回：
+
+```ts
+Promise<{ state: PrinterConnectionState }>
+```
+
+其中 `PrinterConnectionState` 为：
+
+```ts
+type PrinterConnectionState = 'disconnected' | 'connecting' | 'connected';
+```
+
+### `print(options)`
+
+发送原始打印负载到打印机。
+
+参数：
+
+```ts
+interface PrintOptions {
+  payload: string;
+  language?: PrinterLanguage;
+  copies?: number;
+}
+```
+
+其中 `PrinterLanguage` 为：
+
+```ts
+type PrinterLanguage = 'tspl' | 'cpcl' | 'raw';
+```
+
+返回：
+
+```ts
+Promise<void>
+```
+
+### `getStatus()`
+
+查询当前打印机状态。
+
+返回：
+
+```ts
+Promise<PrinterStatus>
+```
+
+```ts
+interface PrinterStatus {
+  connected: boolean;
+  ready?: boolean;
+  paperOut?: boolean;
+  coverOpen?: boolean;
+  overheating?: boolean;
+  message?: string;
+  raw?: unknown;
+}
+```
+
+### `openAppSettings()`
+
+跳转到应用系统设置页。
+
+返回：
+
+```ts
+Promise<void>
+```
+
+## 主要类型
+
+### `PrinterPermissionResult`
+
+```ts
+interface PrinterPermissionResult {
+  granted: boolean;
+  canPrompt: boolean;
+  shouldOpenSettings: boolean;
+  permissions: {
+    bluetoothConnect?: PermissionState;
+    bluetoothScan?: PermissionState;
+    bluetooth?: PermissionState;
+  };
+}
+```
+
+```ts
+type PermissionState = 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied';
+```
+
+### `PrinterDevice`
+
+```ts
+interface PrinterDevice {
+  id: string;
+  name: string;
+  address?: string;
+  transport: PrinterTransport;
+  bonded?: boolean;
+  rssi?: number;
+}
+```
+
+```ts
+type PrinterTransport = 'classic' | 'ble';
+```
+
+## 导出的 Builder 与 Helper
+
+除了 `LabelPrinter` 插件对象，包里还导出了：
+
+- `CpclBuilder`
+- `TsplBuilder`
+- `mmToDots`
+- `escapeTsplText`
+
+推荐业务层先用 `CpclBuilder` 或 `TsplBuilder` 组装 `payload`，再调用 `print()`。
+
+## 额外说明
+
+- Web 端只有 `isSupported()` 和 `getConnectionState()` / `getStatus()` 的兜底返回，其余方法会抛错
+- 自动生成的结构化 API 元数据位于 `dist/docs.json`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andy Zheng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/M430CapacitorLabelPrinter.podspec

@@ -0,0 +1,21 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+repository_url = package.dig('repository', 'url').to_s.sub(/^git\+/, '')
+homepage_url = repository_url.sub(/\.git$/, '')
+
+Pod::Spec.new do |s|
+  s.name = 'M430CapacitorLabelPrinter'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = homepage_url
+  s.author = package['author']
+  s.source = { git: repository_url, tag: s.version.to_s }
+  s.source_files = 'ios/Plugin/**/*.{swift,h,m,mm}'
+  s.vendored_frameworks = 'ios/VendorFrameworks/*.framework', 'ios/VendorFrameworks/*.xcframework'
+  s.preserve_paths = 'ios/VendorFrameworks/**/*'
+  s.ios.deployment_target = '13.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.9'
+end

package/README.md

@@ -0,0 +1,190 @@
+# @m430/capacitor-label-printer
+
+面向启锐 `QR-365` 及同类标签热敏打印机的 `Capacitor 7` 插件，内置 `CPCL` / `TSPL` 指令发送能力。
+
+这个包的目标不是把业务模板写死在插件里，而是提供一层可复用的原生打印通道，统一暴露设备发现、连接、状态查询和标签打印能力，并随 npm 包分发 Android `jar` 与 iOS `framework`。
+
+## 当前状态
+
+- 已完成独立仓库、npm 包、Capacitor 插件骨架和 `example-app`
+- 已完成 Android `jar` 与 iOS `framework` 的随包分发
+- 已完成统一 JS API、`CPCL` / `TSPL` builder、Android/iOS 编译链路验证
+- 当前 `AndroidPrinterManager` 与 `IOSPrinterManager` 仍是首版骨架，真实厂商 SDK 的会话管理、写入和状态回传逻辑需要继续结合真机联调补齐
+
+## 安装
+
+```bash
+npm install @m430/capacitor-label-printer
+npx cap sync
+```
+
+如果宿主项目还没有添加原生平台，请先执行：
+
+```bash
+npx cap add android
+npx cap add ios
+```
+
+## 宿主项目权限
+
+### Android
+
+Android 蓝牙权限已经随插件一起分发并参与宿主 Manifest 合并，通常不需要宿主项目再手写：
+
+- `BLUETOOTH`、`BLUETOOTH_ADMIN`，并带 `maxSdkVersion=30`
+- `BLUETOOTH_CONNECT`
+- `BLUETOOTH_SCAN`，并带 `neverForLocation`
+
+体验约定：
+
+- 首次调用 `discoverDevices()` 时，插件会自动触发“附近设备”权限申请
+- 也可以先主动调用 `ensurePermissions()`，拿到结构化权限状态后再决定是否继续
+- 如果用户永久拒绝权限，可调用 `openAppSettings()` 引导跳转系统设置页
+
+### iOS
+
+宿主项目需要在自己的 `Info.plist` 中补充蓝牙用途说明：
+
+```xml
+<key>NSBluetoothAlwaysUsageDescription</key>
+<string>App 需要连接蓝牙标签打印机以打印物流面单与条码标签</string>
+<key>NSBluetoothPeripheralUsageDescription</key>
+<string>App 需要访问蓝牙设备以完成标签打印</string>
+```
+
+## 快速使用
+
+```ts
+import { CpclBuilder, LabelPrinter } from '@m430/capacitor-label-printer';
+
+async function printDemoLabel() {
+  const support = await LabelPrinter.isSupported();
+  if (!support.supported) {
+    throw new Error('当前平台不支持原生标签打印');
+  }
+
+  const permissionResult = await LabelPrinter.ensurePermissions();
+  if (!permissionResult.granted) {
+    if (permissionResult.shouldOpenSettings) {
+      await LabelPrinter.openAppSettings();
+    }
+    throw new Error('需要先允许蓝牙附近设备权限');
+  }
+
+  const { devices } = await LabelPrinter.discoverDevices({
+    namePrefixes: ['QR', 'QIRUI', 'BEEPRT']
+  });
+
+  if (!devices.length) {
+    throw new Error('没有找到可用打印机');
+  }
+
+  await LabelPrinter.connect({ deviceId: devices[0].id });
+
+  const payload = new CpclBuilder()
+    .page(640, 1)
+    .pageWidth(576)
+    .text(4, 0, 40, 40, 'YT1234567890')
+    .barcode128(40, 120, 80, 'YT1234567890')
+    .form()
+    .print()
+    .build();
+
+  await LabelPrinter.print({
+    payload,
+    language: 'cpcl',
+    copies: 1
+  });
+
+  const status = await LabelPrinter.getStatus();
+  console.log(status);
+}
+```
+
+## API 概览
+
+插件当前公开这些方法：
+
+- `isSupported`
+- `checkPermissions`
+- `ensurePermissions`
+- `discoverDevices`
+- `connect`
+- `disconnect`
+- `getConnectionState`
+- `print`
+- `getStatus`
+- `openAppSettings`
+
+完整 API 文档见 [API.md](./API.md)。
+
+## Helper
+
+已内置 `CpclBuilder`、`TsplBuilder` 与基础 helper，适合物流面单、条码标签这类“一张一张打”的场景：
+
+- `page`
+- `pageWidth`
+- `sizeMm`
+- `gapMm`
+- `density`
+- `speed`
+- `cls`
+- `text`
+- `barcode128`
+- `qrcode`
+- `printCopies`
+
+## 平台说明
+
+### Android
+
+- 当前集成的是厂商 `TSPL classic bluetooth` 方向的 `jar`
+- 插件包内已带上 `android/libs/fat-generic-tspl-bluetooth-classic-0.1.16-GA.jar`
+- 现阶段 `discoverDevices` 主要基于已配对设备过滤，适合作为 `QR-365` 的首版接入基线
+- `discoverDevices()` 与 `connect()` 会在 Android 12+ 自动兜底附近设备权限
+
+### iOS
+
+- 当前包内已带上 `ios/VendorFrameworks/` 下的厂商 `framework`
+- `CocoaPods` 集成使用的是 `M430CapacitorLabelPrinter.podspec`
+- 已验证 `npx cap sync ios` 与 `xcodebuild` 编译链路可通过
+- iOS 仍需要宿主在 `Info.plist` 中声明蓝牙用途说明
+
+### Web
+
+- 不支持
+- `isSupported()` 返回 `false`
+- 其余原生能力会抛出 `Label printing is not supported on web.`
+
+## 开发与发布校验
+
+```bash
+npm run verify
+npm run verify:ios
+npm run verify:release
+```
+
+其中：
+
+- `verify` 会执行单测、Android Gradle 构建和插件打包
+- `verify:ios` 会执行 `example-app` 的 `cap sync ios` 与 `xcodebuild`
+- `verify:release` 会串起完整发布前检查，并执行 `npm pack --dry-run`
+
+## 已随包分发的原生资源
+
+- Android `jar`
+- iOS `framework`
+- iOS `podspec`
+
+宿主项目安装后不需要再单独下载一份厂商 SDK。
+
+## 已知限制
+
+- 当前版本以“统一 API + 原生依赖分发 + 构建链路打通”为主
+- Android 与 iOS 的真实打印链路还需要按厂商 SDK 文档继续接入
+- 还没有内置打印队列、自动重连、模板编辑器和图片调试工具
+
+## 仓库
+
+- GitHub: `https://github.com/m430/capacitor-label-printer`
+- npm: `@m430/capacitor-label-printer`

package/android/build.gradle

@@ -0,0 +1,46 @@
+ext {
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.0'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.7.3'
+    }
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    namespace "com.m430.capacitor.labelprinter"
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 35
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 35
+        versionCode 1
+        versionName "0.1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    lintOptions {
+        abortOnError false
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    testImplementation fileTree(dir: 'gradle/test-libs', include: ['*.jar'])
+}

package/android/libs/.gitkeep

@@ -0,0 +1 @@
+

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,12 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission
+        android:name="android.permission.BLUETOOTH"
+        android:maxSdkVersion="30" />
+    <uses-permission
+        android:name="android.permission.BLUETOOTH_ADMIN"
+        android:maxSdkVersion="30" />
+    <uses-permission
+        android:name="android.permission.BLUETOOTH_SCAN"
+        android:usesPermissionFlags="neverForLocation" />
+    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+</manifest>

package/android/src/main/java/com/m430/capacitor/labelprinter/.gitkeep

@@ -0,0 +1 @@
+

package/android/src/main/java/com/m430/capacitor/labelprinter/AndroidPrinterManager.java

@@ -0,0 +1,132 @@
+package com.m430.capacitor.labelprinter;
+
+import com.getcapacitor.JSArray;
+import com.getcapacitor.JSObject;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+
+public class AndroidPrinterManager {
+    interface DeviceCatalog {
+        JSArray discover(List<String> prefixes);
+
+        PrinterSession openSession(String deviceId);
+    }
+
+    interface PrinterSession {
+        void connect() throws IOException;
+
+        void disconnect();
+
+        boolean isConnected();
+
+        String getConnectionState();
+
+        String getDeviceName();
+
+        void print(String language, byte[] payload) throws IOException;
+
+        byte[] queryStatus() throws IOException;
+    }
+
+    private final DeviceCatalog deviceCatalog;
+    private final AndroidStatusMapper statusMapper;
+    private PrinterSession session;
+    private String connectedDeviceId;
+
+    public AndroidPrinterManager(DeviceCatalog deviceCatalog, AndroidStatusMapper statusMapper) {
+        this.deviceCatalog = deviceCatalog;
+        this.statusMapper = statusMapper;
+    }
+
+    public JSArray getBondedDevices(List<String> prefixes) {
+        return deviceCatalog.discover(prefixes);
+    }
+
+    public void connect(String deviceId) throws IOException {
+        if (deviceId == null || deviceId.trim().isEmpty()) {
+            throw new IllegalArgumentException("deviceId is required");
+        }
+
+        PrinterSession nextSession = deviceCatalog.openSession(deviceId);
+        if (nextSession == null) {
+            throw new IllegalArgumentException("printer device not found: " + deviceId);
+        }
+
+        disconnect();
+        nextSession.connect();
+        session = nextSession;
+        connectedDeviceId = deviceId;
+    }
+
+    public void disconnect() {
+        if (session != null) {
+            session.disconnect();
+        }
+        session = null;
+        connectedDeviceId = null;
+    }
+
+    public void print(String payload, String language, int copies) throws IOException {
+        if (payload == null || payload.isEmpty()) {
+            throw new IllegalArgumentException("payload is empty");
+        }
+        PrinterSession activeSession = requireSession();
+        activeSession.print(language, payload.repeat(Math.max(copies, 1)).getBytes(StandardCharsets.UTF_8));
+    }
+
+    public JSObject getConnectionState() {
+        JSObject state = new JSObject();
+        state.put("state", session == null ? "disconnected" : session.getConnectionState());
+        return state;
+    }
+
+    public JSObject getStatus() {
+        if (session == null || !session.isConnected()) {
+            return statusMapper.disconnected("disconnected");
+        }
+
+        JSObject status = statusMapper.toPluginStatus(true, AndroidStatusMapper.STATE_READY, "ready");
+        status.put("deviceId", connectedDeviceId);
+        status.put("deviceName", session.getDeviceName());
+
+        try {
+            byte[] response = session.queryStatus();
+            if (response != null && response.length > 0) {
+                String rawText = new String(response, StandardCharsets.UTF_8).trim();
+                if (!rawText.isEmpty()) {
+                    status.put("raw", rawText);
+                    status.put("message", rawText);
+                    applyStatusHints(status, rawText);
+                }
+            }
+        } catch (IOException exception) {
+            status.put("message", exception.getMessage());
+        }
+
+        return status;
+    }
+
+    private PrinterSession requireSession() {
+        if (session == null || !session.isConnected()) {
+            throw new IllegalStateException("printer is not connected");
+        }
+        return session;
+    }
+
+    private void applyStatusHints(JSObject status, String rawText) {
+        String normalized = rawText.toUpperCase();
+        if (normalized.contains("PAPER")) {
+            status.put("ready", false);
+            status.put("paperOut", true);
+        }
+        if (normalized.contains("COVER") || normalized.contains("OPEN")) {
+            status.put("ready", false);
+            status.put("coverOpen", true);
+        }
+        if (normalized.contains("HEAT")) {
+            status.put("ready", false);
+            status.put("overheating", true);
+        }
+    }
+}

package/android/src/main/java/com/m430/capacitor/labelprinter/AndroidStatusMapper.java

@@ -0,0 +1,54 @@
+package com.m430.capacitor.labelprinter;
+
+import com.getcapacitor.JSObject;
+import org.json.JSONException;
+
+public class AndroidStatusMapper {
+    public static final int STATE_UNKNOWN = -1;
+    public static final int STATE_READY = 0;
+    public static final int STATE_PAPER_OUT = 1;
+    public static final int STATE_COVER_OPEN = 2;
+    public static final int STATE_OVERHEATING = 3;
+
+    public JSObject toPluginStatus(boolean connected, int stateCode, String message) {
+        String messageValue = message == null
+            ? "null"
+            : "\"" + message.replace("\\", "\\\\").replace("\"", "\\\"") + "\"";
+        String payload = "{"
+            + "\"connected\":" + connected + ","
+            + "\"ready\":" + (stateCode == STATE_READY) + ","
+            + "\"paperOut\":" + (stateCode == STATE_PAPER_OUT) + ","
+            + "\"coverOpen\":" + (stateCode == STATE_COVER_OPEN) + ","
+            + "\"overheating\":" + (stateCode == STATE_OVERHEATING) + ","
+            + "\"message\":" + messageValue + ","
+            + "\"raw\":" + stateCode
+            + "}";
+
+        try {
+            return new JSObject(payload);
+        } catch (JSONException exception) {
+            throw new IllegalStateException("Failed to map printer status", exception);
+        }
+    }
+
+    public JSObject disconnected(String message) {
+        String messageValue = message == null
+            ? "null"
+            : "\"" + message.replace("\\", "\\\\").replace("\"", "\\\"") + "\"";
+        String payload = "{"
+            + "\"connected\":false,"
+            + "\"ready\":false,"
+            + "\"paperOut\":false,"
+            + "\"coverOpen\":false,"
+            + "\"overheating\":false,"
+            + "\"message\":" + messageValue + ","
+            + "\"raw\":null"
+            + "}";
+
+        try {
+            return new JSObject(payload);
+        } catch (JSONException exception) {
+            throw new IllegalStateException("Failed to map disconnected printer status", exception);
+        }
+    }
+}