Ionic Meetup
#19 Tokyo

最新の情報を手に入れよう。2022/05/29(日)、東京開催。

DocsプラグインCLI

プラグイン開発のワークフロー

新しいプラグインを作成したら、様々なプラットフォームへの機能実装を開始します。

新しいメソッドを実装する

プラグインに新しい機能を実装するには、まず src/definitions.ts にあるプラグイン用にエクスポートされた TypeScript インターフェースで、メソッドのシグネチャを定義します。

以下の例では、 latitudelongitude を受け取る openMap() メソッドを追加しています。アプリにインポートして使用できるメソッドのパラメータのインターフェースを定義するのは重要な習慣です。

 export interface EchoPlugin {
   echo(options: { value: string }): Promise<{ value: string }>;
+  openMap(options: OpenMapOptions): Promise<void>;
 }

+export interface OpenMapOptions {
+  latitude: number;
+  longitude: number;
+}

web の実装を src/web.ts で行います:

 import type {
   EchoPlugin,
+  OpenMapOptions,
 } from './definitions';

 export class EchoWeb extends WebPlugin implements EchoPlugin {
   // other methods

+  async openMap(location: OpenMapOptions): Promise<void> {
+    // logic here
+  }
 }

プラグインをコンパイルするには、plugin ディレクトリに移動して、実行します:

npm run build

Android の機能android/src/main/[nested folders]/EchoPlugin.java で実装します:

@PluginMethod()
public void openMap(PluginCall call) {
  Double latitude = call.getDouble("latitude");
  Double longitude = call.getDouble("longitude");

  // more logic

  call.resolve();
}

iOS の機能ios/Plugin/EchoPlugin.swift に実装します:

@objc func openMap(_ call: CAPPluginCall) {
  let latitude = call.getString("latitude")
  let longitude = call.getNumber("longitude")

  // more logic

  call.resolve()
}

.m ファイルに プラグインメソッドの登録 を忘れずに行ってください。

この例はプラグインで最も一般的なタイプのメソッドを含んでいますが、サポートされているすべてのタイプの詳細は ここで見つけることができます

ローカルでのテスト

プラグインを開発しながらローカルでテストするには、プラグインのパスを指定して npm install でプラグインフォルダをアプリにリンクしてください。

npm install ../path/to/echo

プロジェクトの package.json ファイルに、依存関係のリストにプラグインパッケージのリンクが表示されるようになりました:

"echo": "file:../path/to/echo",

最後に、npx cap sync を実行して、ネイティブプロジェクトがあなたのプラグインを認識するようにします。正しく検出された場合は、次のようなメッセージが表示されます:

[info] Found 1 Capacitorプラグイン for android:
    - echo (0.0.1)

プラグインのリンク解除

アプリからローカルプラグインをアンインストールするには、プラグインのパッケージ名と一緒に npm uninstall を実行します。

npm uninstall echo

Package Scripts

プラグインテンプレートは、 package.json に様々なスクリプトを同梱しています。

  • verify: ウェブとネイティブのコードをビルドしてテストします。
  • lint: ウェブとネイティブのコードを lint します。
  • fmt: ウェブとネイティブのコードを自動整形する
  • docgen: プラグインインターフェースからドキュメントを生成します (参照 Documentation)
  • build: ウェブコードを ESM とバンドル配布物にビルドします。

ドキュメンテーション

プラグインの機能を文書化するために、メソッドとプロパティに JSDoc のコメントブロックを追加します。

TypeScript ファイルの @param@returns の JSDoc タグに型情報を含めることは、通常必要ではありません。

openMap() メソッドを例に、 src/definitions.ts を開いて、ドキュメントを書き始めてください。

 export interface EchoPlugin {
   echo(options: { value: string }): Promise<{ value: string }>;

+  /**
+   * Opens the map at a given location.
+   *
+   * @since 1.1.0
+   */
   openMap(options: OpenMapOptions): Promise<void>;
 }

 export interface OpenMapOptions {
+  /**
+   * The latitude at which to open the map.
+   */
   latitude: number;

+  /**
+   * The longitude at which to open the map.
+   */
   longitude: number;
 }

プラグインテンプレートには @capacitor/docgen が同梱されており、生成されたドキュメントを README.md に書き込むことができます。ドキュメントは npm run build の実行中に生成される。また、手動で実行することもできます。

npm run docgen

公開

プラグインを公開する準備ができたら、いつでも実行ください:

npm publish

これにより、プラグインの JS 部分がビルドされ、残りのプラグインファイルが npm に公開されます。

これで、Capacitor アプリで npm install echo を使ってパッケージをインストールできるようになります。

Previous
<- 概要
Next
iOS ガイド ->
Contribute ->