开发Capacitor插件
Capacitor插件能让JavaScript直接调用原生平台API。
本指南将帮助你开始开发可发布的Capacitor插件(可发布至npm)。你也可以创建仅限当前应用使用的本地插件,具体请参考iOS和Android的自定义原生代码指南。
设计理念
如果你的插件计划公开分享,在开始前请了解我们关于Capacitor插件的核心设计理念。
协同开发
我们相信协作开发比单打独斗更能产出高质量的插件。为此我们创建了Capacitor社区GitHub组织,相比个人仓库,这里更便于开发者协作。
如果Capacitor社区中已存在某个功能的插件,请考虑参与贡献!若某个插件缺少主要维护者,Capacitor团队很乐意邀请你加入GitHub组织。
小而专注
Capacitor插件应当保持适度的功能范围。插件添加的原生代码可能会被用户使用也可能不会。通过控制插件规模,可以确保应用只包含必要的原生代码。这能避免应用体积膨胀,以及因未使用的API描述导致应用商店审核警告/拒绝等问题。
小而专注的插件还具有部署更快、协作更容易、更易维护等优势。
统一且符合习惯
Capacitor插件应当提供跨平台的统一API,并符合JavaScript开发者的使用习惯。这意味着可能需要转换原生平台的返回值格式。
以下是一些创建统一体验的指导原则及示例:
- 优先使用
undefined
而非null
等特殊值。例如:若Android API返回0.0
表示"无值",则应转换为JavaScript层的undefined
- 保持计量单位一致。例如:若iOS API使用摄氏度而Android API使用华氏度,应在返回值到达JavaScript前统一转换为同种单位
- 日期时间优先使用带时区的ISO 8601格式。例如:从
"2020-12-13T20:21:58.415Z"
这样的字符串可以准确生成JavaScript的Date
对象,而Unix时间戳(JavaScript使用毫秒)则容易造成混淆。请始终包含时区信息,否则不同地区可能对日期时间产生不同解析结果
插件生成器
准备开始了?Capacitor提供了插件生成工具帮助你快速搭建插件项目。
开始前请确保你使用的是最新的Node LTS版本和npm 6+
在新终端中运行以下命令:
npm init @capacitor/plugin@latest
生成器会提示你输入信息。你也可以使用命令行参数(参见GitHub仓库)。