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+

エージェントの動作

• 質問する前に自動検出します。 package.json を読み込み、ディレクトリ構造を調べ、ユーザーに尋ねる前にプラグインの現在の状態を推測します。
• 手順を追って案内します。 一度に1つのフェーズを進めます。関連のない複数のタスクを同時に提示しないでください。
• 既存の作業は省略します。 プラグインのスキャフォールディングがすでに済んでいる場合は省略します。iOS 実装がすでにある場合は、次のプラットフォームに進みます。
• 対象プラットフォームを確認します。 ユーザーが指定しない場合は、3つすべて（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 の enum ではなく、文字列のユニオン型を使用していること。

ステップ 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()
void を返す	Promise<void>	CAPPluginReturnNone	@PluginMethod(returnType = PluginMethod.RETURN_NONE)
コールバック（繰り返し）	Promise<string>	CAPPluginReturnCallback	@PluginMethod(returnType = PluginMethod.RETURN_CALLBACK)

ほとんどのメソッドでは「値を返す」型を使用します。「コールバック」は、継続的なデータストリーム（位置情報の監視など）に限って使用します。

Step 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

Step 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

Step 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 パラメーターと一致することを確認します。

Step 9: ドキュメントを生成して検証する

1. src/definitions.ts のすべてのメソッドとインターフェースに、まだ追加されていない場合は JSDoc コメントを追加します。
2. ドキュメントを生成します。

npm run docgen

3. 全項目を検証します。

npm run verify

4. リントとフォーマットを実行します。

npm run lint
npm run fmt

Step 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 のウェブ実装がプラグインインターフェースを正しく実装していることを確認してください。
• 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 の出力が空になる場合：実装クラスではなく、src/definitions.ts のプラグインインターフェースメソッドに JSDoc コメントがあることを確認してください。

関連スキル

• capacitor-plugin-spm-support — Capacitor プラグインに Swift Package Manager のサポートを追加します。
• capacitor-plugin-upgrades — Capacitor プラグインを新しい Capacitor メジャーバージョンにアップグレードします。
• capacitor-plugins — アプリプロジェクトに既存の Capacitor プラグインをインストールして設定します。