Skip to main content

Capacitor 插件文档总览

本章节从整体视角介绍润典技术架构平台在 CapacitorJS 客户端插件层 的定位与设计思路，帮助你在阅读各插件文档前，先在脑中建立一张「原生能力底座」的全景图。

平台愿景：让跨端应用有统一的“原生能力底座”​

在终端侧（门店一体机、收银机、Android Pad、Electron 客户端等），我们希望做到：

  • 原生能力统一封装：MQTT 通信、打印、存储、日志、热修复、扫码等能力，通过一套稳定的 CapacitorJS 插件对外暴露；
  • 跨平台一致体验：Android / iOS / Web / Electron 在语义上尽量一致，用同一套 TypeScript API 调用；
  • 可治理、可观测：配合 logger、hotfix 等能力，对终端进行版本管理、故障排查与运行监控。

本目录下的文档，正是围绕这套 CapacitorJS 插件体系展开。

核心设计原则​

  • 统一 API 形态

    • 所有插件都采用 Promise 风格的异步方法 + addListener 事件模型；
    • 所有方法、事件、类型都通过 definitions.ts 明确定义，并在文档中完整展开。

  • 平台差异显式

    • 每个插件文档都有「平台能力矩阵」表，清楚标出 Android / iOS / Web / Electron 的支持与限制；
    • 对于“可实现但暂未实现”的能力，也会明确标注，避免误解。

  • 对齐原生 SDK 思维

    • MQTT 插件与 Android/iOS 原生客户端能力对齐（弱网不断连、心跳、网络质量等）；
    • Printer 插件与各厂商 SDK 对齐，统一抽象、多驱动适配；
    • Storage 插件以 SQLite 为核心，提供接近后端 ORM 的表达力。

  • 文档优先于源码

    • 目标是「只看文档就能正确开发」：每个插件文档都包含设计思想、使用示例、完整 API、参数说明与平台差异；
    • 不需要再回到 JSDoc 或源码里“抠细节”。

文档阅读路线建议​

如果你第一次接触这套 CapacitorJS 插件体系，推荐按照下面的顺序阅读：

  1. MQTT 通信：mqtt.md
    了解如何在终端中通过 MQTT 与后端实时通信（连接、订阅、心跳、网络质量、平台差异）。
  2. 配置与数据库存储：preferences.md、database.md
    掌握终端本地配置与业务数据的持久化方式（KV 存储、表结构存储、离线缓存）。
  3. 日志与热修复：logger.md、hotfix.md
    了解如何对终端进行日志采集与热更新管理，为生产环境运维打基础。
  4. 外设能力：printer.md、qrcode.md
    学会如何在一体机/收银机中使用网络打印机、内置打印机以及扫码组件。

你也可以直接跳到自己关心的插件文档，每一篇都力求“自洽”：只看本页即可完成开发与排查。

适用场景与边界​

这套 CapacitorJS 插件尤其适合：

  • 需要 长期演进、多人协作 的中大型客户端项目；
  • 涉及 门店终端、收银机、移动 POS、一体机、Electron 客户端 等多端形态；
  • 希望在 通信、打印、存储、日志、热修复 等方面与后端保持统一治理。

对于极小型 Demo 或纯 Web 项目，你仍然可以不引入这套插件体系；
当项目进入「需要可治理、可演进」阶段时，再逐步迁移会有更大收益。

插件一览表​

插件包名主要能力典型场景文档
MQTT 通信@capacitor-rydeen/mqttMQTT 连接、订阅/发布、心跳、网络质量监控门店终端在线状态、远程指令下发./mqtt.md
本地配置@capacitor-rydeen/preferences终端偏好设置与配置项 KV 存储用户设置、默认门店、默认打印机等./preferences.md
本地数据库@rydeen/databaseSQLite 访问、迁移管理、Schema 扫描、Kysely 集成订单/菜单/用户等业务数据持久化与结构演进./database.md
日志采集@rydeen/loggerConsole / SLS / CLS / LTS / CloudWatch 多驱动日志生产环境错误日志、业务埋点./logger.md
热修复@rydeen/hotfix基于 Capgo 的资源增量更新、定时检查与回滚紧急修复前端 Bug、渐进发布补丁./hotfix.md
打印能力@capacitor-rydeen/network-printer 等网络打印、多驱动适配小票打印、标签打印./printer.md
扫码能力@rydeen/qrcode摄像头扫码 UI 封装、权限管理二维码/条码扫描、登录/支付码识别./qrcode.md

接下来建议从 mqtt.md 开始，逐个阅读并结合实际项目场景选用合适的插件。