@nitra/zebra

Capacitor-плагін для друку ZPL на принтерах Zebra з підтримкою веб (Web Serial API), iOS та Android.

Вимоги

• Capacitor 7.0.0 або новіший
• Веб: браузер з підтримкою Web Serial API (Chrome, Edge, Opera)
• Android: minSdk 23, targetSdk 35
• iOS: 14.0+

Встановлення

npm install @nitra/zebra
npx cap sync

API

print(zpl: string | PrintOptions): Promise<{ sent?: boolean }>

Відправляє ZPL-команду на принтер Zebra.

| Платформа | Поведінка | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Web | Запитує порт через Web Serial API, відкриває з'єднання (9600 baud) і відправляє рядок ZPL на вибраний пристрій. | | iOS | Друк по Bluetooth (MFi). Принтер спочатку спарюють у Налаштування → Bluetooth; далі getPairedDevices() та print({ zpl, address }). | | Android | Відправка ZPL по Bluetooth Classic (SPP). Потрібно спочатку викликати setPrinterAddress({ address: "MAC" }) або передати address (Bluetooth MAC) у виклику. |

Параметри (об'єкт для Android):

• zpl — рядок ZPL-команд (наприклад, ^XA^FO50,50^A0N,28,28^FDHello^FS^XZ).
• address — (Android, опційно) Bluetooth MAC-адреса принтера (наприклад 00:11:22:33:44:55); якщо не передано, використовується збережена через setPrinterAddress().
• port — ігнорується (для сумісності API).

Приклад:

import { Zebra } from '@nitra/zebra'

const zpl = '^XA^FO50,50^A0N,28,28^FDHello World^FS^XZ'
await Zebra.print(zpl)

setPrinterAddress(options: { address: string, port?: number }): Promise<{ address }> (Android / iOS)

Зберігає Bluetooth MAC-адресу принтера Zebra для подальших викликів print(zpl) без передачі адреси.

Параметри:

• address — на Android: Bluetooth MAC (наприклад 00:11:22:33:44:55); на iOS: серійний номер або ім'я з getPairedDevices().
• port — ігнорується (для сумісності API).

Приклад (Android):

await Zebra.setPrinterAddress({ address: '00:11:22:33:44:55' })
await Zebra.print(zpl)

Приклад (iOS): використовуйте address з getPairedDevices() (серійний номер або ім'я принтера).

getPairedDevices(): Promise<{ devices: { address: string, name: string }[] }> (Android / iOS)

Повертає список пристроїв: на Android — спарені Bluetooth-пристрої; на iOS — підключені MFi-аксесуари (Bluetooth). Корисно для вибору принтера. На Android 12+ потрібен дозвіл BLUETOOTH_CONNECT (запитати до виклику).

Приклад (Android):

const { devices } = await Zebra.getPairedDevices()
// devices: [{ address: "00:11:22:33:44:55", name: "Zebra ZD420" }, ...]

Приклад (iOS): той самий API; address — серійний номер або ім'я MFi-пристрою.

Веб (Web Serial API)

На веб-платформі плагін використовує Web Serial API:

1. При виклику print() користувачу показується діалог вибору послідовного порту (принтер, підключений через USB).
2. Відкривається з'єднання з параметрами: 9600 baud, 8 data bits, no parity, 1 stop bit.
3. ZPL-рядок відправляється на пристрій.

Обмеження: Web Serial API працює лише в підтримуваних браузерах (Chrome, Edge, Opera) і зазвичай лише через HTTPS або localhost.

Android (Bluetooth Classic)

На Android плагін відправляє ZPL на принтер Zebra по Bluetooth Classic (профіль SPP):

1. Спаріть принтер у налаштуваннях Bluetooth пристрою.
2. Викличте getPairedDevices() щоб отримати список пристроїв (опційно) або введіть MAC-адресу вручну.
3. Викличте setPrinterAddress({ address: "MAC_ПРИНТЕРА" }) один раз (наприклад, з налаштувань) або передайте address у виклику print({ zpl, address }).
4. Викличте print(zpl) або print({ zpl }) — ZPL буде відправлено на принтер по Bluetooth.

Потрібні дозволи BLUETOOTH, BLUETOOTH_ADMIN (до API 30), BLUETOOTH_CONNECT (API 31+). На Android 12+ дозвіл BLUETOOTH_CONNECT потрібно запитати під час виконання (наприклад перед getPairedDevices() або print()).

iOS (Bluetooth MFi)

На iOS друк працює лише по Bluetooth через ExternalAccessory (MFi). Підключення по Lightning/USB не підтримується Apple для Zebra в цьому режимі.

1. Спаріть принтер: Налаштування → Bluetooth → увімкніть принтер і підключіть його.
2. У додатку: викличте getPairedDevices() — повернуться підключені Zebra-пристрої (address та name).
3. Викличте setPrinterAddress({ address }) або передайте address у print({ zpl, address }) (адреса — це address з getPairedDevices(): серійний номер або ім'я).
4. print({ zpl, address }) відправляє ZPL на принтер по Bluetooth.

Обов'язково: У проєкті додатку в ios/App/App/Info.plist мають бути протоколи Zebra в UISupportedExternalAccessoryProtocols, інакше iOS не покаже принтер:

<key>UISupportedExternalAccessoryProtocols</key>
<array>
  <string>com.zebra.rawport</string>
  <string>com.zebra.print</string>
</array>

Структура пакету

• dist/ — зібраний JS-плагін (rolldown)
• src/ — вихідний код: index.js, definitions.js, web.js (Web Serial реалізація)
• ios/ — нативний iOS-плагін (Swift)
• android/ — нативний Android-плагін (Java)

Скрипти

| Команда | Опис | | ---------------- | ----------------------------------------------- | | npm run build | Збірка плагіну (rolldown) | | npm run verify | Перевірка iOS, Android та веб-збірки | | npm run fmt | Форматування коду (ESLint, Prettier, SwiftLint) | | npm run lint | Перевірка стилю коду |

Ліцензія

MIT