capacitor-plugin-development

Capacitor 插件开发

创建和维护 Capacitor 插件——包括脚手架搭建、原生 API 桥接（iOS/Android）、类型定义、测试和发布。

前提条件

要求	版本
Node.js	LTS (18+)
npm	6+
Xcode	15+（适用于 iOS）
Android Studio	Hedgehog 2023.1.1+（适用于 Android）
Capacitor	6+

Agent 行为

• 先自动检测，再提问。 读取 package.json、检查目录结构，并在提示用户前推断插件当前状态。
• 逐步引导。 每次引导用户完成一个阶段。不要同时呈现多个无关任务。
• 跳过已完成的部分。 如果插件已搭建好脚手架，则跳过脚手架搭建。如果 iOS 实现已存在，则跳到下一个平台。
• 询问目标平台。 如果用户未指定，则实现全部三个平台（iOS、Android、Web）。

流程

第 1 步：确定任务

询问用户想要做什么。常见任务：

1. 从头创建新插件 — 继续第 2 步。
2. 为现有插件添加新方法 — 跳到第 5 步。
3. 添加新的平台实现 — 跳到对应的平台步骤（第 6、7 或 8 步）。
4. 设置插件配置 — 阅读 references/plugin-configuration.md 并应用。
5. 设置插件钩子 — 阅读 references/testing-and-workflow.md（Plugin Hooks 部分）并应用。
6. 发布插件 — 跳到第 10 步。

如果根据上下文可以明确用户意图，则跳过此问题并直接继续。

第 2 步：搭建插件脚手架

阅读 references/scaffolding.md，并引导用户使用 Capacitor 插件生成器创建新的插件项目。

向用户收集以下信息（或根据上下文推断）：

• 插件 npm 包名称
• Android 包 ID
• 插件类名称
• 仓库 URL
• 许可证
• 描述

运行生成器，并使用 npm run verify 验证脚手架。

第 3 步：设计 TypeScript API

阅读 references/designing-api.md，并引导用户定义插件接口。

1. 询问用户插件应公开哪些方法，以及每个方法接受和返回哪些数据。
2. 在 src/definitions.ts 中定义插件接口及所有支持类型。
3. 使用 registerPlugin() 在 src/index.ts 中注册插件。

确保：

• 每个方法和属性都有带 @since 标签的 JSDoc 注释。
• 选项类型和结果类型分别定义为独立接口。
• 使用字符串联合类型，而不是 TypeScript 枚举。

第 4 步：实现 Web 层

阅读 references/web-guide.md，并在 src/web.ts 中实现 Web 层。

1. 扩展 WebPlugin 并实现插件接口。
2. 对于使用 Web API 的方法，实现基于浏览器的逻辑。
3. 对于没有 Web 对应实现的方法，抛出 this.unimplemented()。
4. 对于需要在所有浏览器中并非都可用的 Web API 的方法，检查该 API 是否存在；若不存在，则抛出 this.unavailable()。

实现后，构建并验证：

npm run build
npm run verify:web

第 5 步：定义各平台的方法签名

实现原生代码之前，先确定每个插件方法的类型：

类型	TypeScript	iOS	Android
返回值	Promise<T>	CAPPluginReturnPromise	@PluginMethod()
无返回值	Promise<void>	CAPPluginReturnNone	@PluginMethod(returnType = PluginMethod.RETURN_NONE)
回调（重复）	Promise<string>	CAPPluginReturnCallback	@PluginMethod(returnType = PluginMethod.RETURN_CALLBACK)

大多数方法使用“返回值”类型。仅对连续数据流（例如地理位置监视）使用“回调”。

步骤 6：实现 iOS 插件

阅读 references/ios-guide.md 并实现 iOS 层。

1. 创建或更新实现类（例如，ios/Sources/<ClassName>Plugin/Example.swift），实现平台逻辑。继承 NSObject，并使用 @objc 标记方法。
2. 创建或更新插件类（例如，ios/Sources/<ClassName>Plugin/ExamplePlugin.swift）：
   • 继承 CAPPlugin 并遵循 CAPBridgedPlugin。
   • 设置 identifier、jsName 和 pluginMethods 属性。
   • 实现每个 @objc func 方法，从 CAPPluginCall 读取数据，并调用 resolve()、reject()、unavailable() 或 unimplemented()。
3. 如果插件需要第三方 iOS 依赖项，请将其添加到 .podspec 文件中。
4. 如果插件需要权限，请实现 checkPermissions() 和 requestPermissions()，并说明所需的 Info.plist 键。

实现后，进行验证：

npm run verify:ios

步骤 7：实现 Android 插件

阅读 references/android-guide.md 并实现 Android 层。

1. 创建或更新实现类（例如，android/src/main/java/<package-path>/Example.java），实现平台逻辑。
2. 创建或更新插件类（例如，android/src/main/java/<package-path>/ExamplePlugin.java）：
   • 继承 Plugin 并添加 @CapacitorPlugin(name = "<JSName>")。
   • 实现每个 @PluginMethod 方法，从 PluginCall 读取数据，并调用 resolve()、reject()、unavailable() 或 unimplemented()。
3. 如果插件需要第三方 Android 依赖项，请将其添加到 android/build.gradle。
4. 如果插件需要权限：
   • 在 @CapacitorPlugin 注解中定义权限别名。
   • 实现 checkPermissions() 和 requestPermissions()。
   • 说明应用开发者必须添加到 AndroidManifest.xml 的权限。

实现后，进行验证：

npm run verify:android

步骤 8：添加事件（如有需要）

如果插件向 JavaScript 发送事件：

1. TypeScript：在 src/definitions.ts 的插件接口中添加 addListener() 和 removeAllListeners() 方法。为每种事件类型定义一个事件接口。
2. Web：在事件发生时调用 this.notifyListeners('eventName', data)。
3. iOS：在事件发生时调用 self.notifyListeners("eventName", data: [...])。如果要监听系统通知，请在 load() 中注册观察者。
4. Android：在事件发生时调用 notifyListeners("eventName", jsObject)。根据需要重写 handleOnConfigurationChanged() 或注册广播接收器。

确保所有平台上的事件名称字符串完全一致，并与 addListener() 中的 eventName 参数匹配。

步骤 9：生成文档并验证

1. 如果 src/definitions.ts 中的方法和接口尚无 JSDoc 注释，请为其添加。
2. 生成文档：

npm run docgen

3. 运行完整验证：

npm run verify

4. 执行代码检查和格式化：

npm run lint
npm run fmt

步骤 10：发布

阅读 references/publishing.md 并指导用户完成发布流程。

1. 确认 package.json 字段正确（name、version、description、files、capacitor）。
2. 运行发布前检查清单。
3. 发布到 npm：

npm publish --access public

错误处理

• npm init @capacitor/plugin@latest 失败：确保已安装 Node.js LTS 和 npm 6+。运行 node -v 和 npm -v 进行检查。
• npm run verify:ios 因“module not found”失败：运行 cd ios && pod install --repo-update && cd .. 安装 CocoaPods 依赖项。
• npm run verify:android 因构建错误失败：在 Android Studio 中打开 android/，同步 Gradle，并检查是否缺少依赖项或 SDK 版本不匹配。
• npm run build 因 TypeScript 错误失败：检查 src/definitions.ts 中的类型是否匹配。确保 src/web.ts 中的 Web 实现正确实现了插件接口。
• registerPlugin() 名称不匹配：src/index.ts 中 registerPlugin() 的第一个参数必须与 iOS 上的 jsName 属性以及 Android 上的 @CapacitorPlugin(name = "...") 值完全一致。名称不匹配会导致插件无法加载。
• iOS：无法从 JavaScript 调用方法：确保所有插件方法都标记了 @objc，并列在 CAPBridgedPlugin 的 pluginMethods 数组中。
• Android：无法从 JavaScript 调用方法：确保所有插件方法都带有 @PluginMethod() 注解，且为 public。
• JavaScript 未收到事件：确认原生 notifyListeners() 调用中的事件名称字符串与 TypeScript addListener() 定义完全相同。确认在事件触发前已调用 addListener()。
• 无法读取插件配置值：确认 getConfig().getString("key") 中的键名与 Capacitor 配置文件中 plugins.<PluginJSName> 下的键名一致。
• npm run docgen 生成空输出：确保插件接口方法的 JSDoc 注释位于 src/definitions.ts 中，而不是实现类中。

相关技能

• capacitor-plugin-spm-support — 为 Capacitor 插件添加 Swift Package Manager 支持。
• capacitor-plugin-upgrades — 将 Capacitor 插件升级到较新的 Capacitor 主版本。
• capacitor-plugins — 在应用项目中安装并配置现有的 Capacitor 插件。