プラグインの作成

プラグインとは、アプリがレンダリングされる Cordova Webview が、それが実行されるネイティブプラットフォームと通信できるようにする、注入されたコードのパッケージです。プラグインは、通常は Web ベースのアプリでは利用できないデバイスとプラットフォームの機能へのアクセスを提供します。Cordova API のすべての主要機能はプラグインとして実装されており、バーコードスキャナー、NFC 通信、カレンダーインターフェースの調整などの機能を有効にする多くのプラグインも利用できます。利用可能なプラグインは、Cordova プラグイン検索ページで検索できます。

プラグインは、単一の JavaScript インターフェースと、サポートされる各プラットフォームに対応するネイティブコードライブラリで構成されています。本質的に、これはさまざまなネイティブコードの実装を共通の JavaScript インターフェースの背後に隠します。

このセクションでは、文字列を JavaScript からネイティブプラットフォームに渡し、戻すシンプルな echo プラグインについて説明します。これは、より複雑な機能を構築するためのモデルとして使用できます。このセクションでは、基本的なプラグイン構造と、外部に公開される JavaScript インターフェースについて説明します。対応する各ネイティブインターフェースについては、このセクションの最後にあるリストを参照してください。

これらの手順に加えて、プラグインの作成を準備する際は、既存のプラグインを参考にするとよいでしょう。

プラグインの構築

アプリケーション開発者は、CLI の plugin add コマンドを使用して、プラグインをプロジェクトに追加します。このコマンドは、引数としてプラグインコードを含む git リポジトリの URL を取ります。この例では、Cordova の Device API を実装しています。

cordova plugin add https://github.com/apache/cordova-plugin-device

プラグインが npm に公開されている場合、コマンドはパッケージ名を引数として受け取ることもできます。

cordova plugin add cordova-plugin-device

プラグインリポジトリには、トップレベルの plugin.xml マニフェストファイルが必要です。このファイルを構成する方法はたくさんあり、その詳細は プラグイン仕様で入手できます。

Device プラグインのこの省略版は、モデルとして使用する簡単な例を提供します。

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="https://apache.dokyumento.jp/cordova/ns/plugins/1.0"
        id="cordova-plugin-device" version="0.2.3">
    <name>Device</name>
    <description>Cordova Device Plugin</description>
    <license>Apache 2.0</license>
    <keywords>cordova,device</keywords>
    <js-module src="www/device.js" name="device">
        <clobbers target="device" />
    </js-module>
    <platform name="ios">
        <config-file target="config.xml" parent="/*">
            <feature name="Device">
                <param name="ios-package" value="CDVDevice"/>
            </feature>
        </config-file>
        <header-file src="src/ios/CDVDevice.h" />
        <source-file src="src/ios/CDVDevice.m" />
    </platform>
</plugin>

• トップレベルの plugin タグの id 属性は、通常、cordova-plugin-{plugin name} スキーマに従い、プラグインの npm パッケージ名と一致します。
• js-module タグは、共通の JavaScript インターフェースへのパスを指定します。
• platform タグは、この場合 ios プラットフォームに対応するネイティブコードのセットを指定します。
• config-file タグは、プラットフォーム固有の config.xml ファイルに挿入され、プラットフォームが追加のコードライブラリを認識するようにする feature タグをカプセル化します。
• header-file タグと source-file タグは、ライブラリのコンポーネントファイルへのパスを指定します。

JavaScript インターフェース

JavaScript インターフェースは、前面インターフェースを提供し、プラグインの最も重要な部分である可能性があります。プラグインの JavaScript をどのように構成しても構いませんが、次の構文を使用して、ネイティブプラットフォームと通信するために cordova.exec を呼び出す必要があります。

cordova.exec(function(winParam) {},
             function(error) {},
             "service",
             "action",
             ["firstArgument", "secondArgument", 42, false]);

各パラメーターの動作は次のとおりです。

• function(winParam) {}: 成功コールバック関数。exec 呼び出しが正常に完了すると、この関数は渡したパラメーターとともに実行されます。

• function(error) {}: エラーコールバック関数。操作が正常に完了しない場合、この関数はオプションのエラーパラメーターとともに実行されます。

• "service": ネイティブ側で呼び出すサービス名。これはネイティブクラスに対応し、詳細については、以下に示すネイティブガイドで入手できます。

• "action": ネイティブ側で呼び出すアクション名。これは通常、ネイティブクラスのメソッドに対応します。以下に示すネイティブガイドを参照してください。

• [/* arguments */]: ネイティブ環境に渡す引数の配列。

サンプル JavaScript

この例は、プラグインの JavaScript インターフェースを実装する 1 つの方法を示しています。

window.echo = function(str, callback) {
    cordova.exec(callback, function(err) {
        callback('Nothing to echo.');
    }, "Echo", "echo", [str]);
};

この例では、プラグインは window オブジェクトに echo 関数としてアタッチします。プラグインユーザーは次のように呼び出します。

window.echo("echome", function(echoValue) {
    alert(echoValue == "echome"); // should alert true.
});

cordova.exec 関数に渡された最後の 3 つの引数を見てください。最初は、クラス名である Echo サービスを呼び出します。2 番目は、そのクラス内のメソッドである echo アクションを要求します。3 番目は、window.echo 関数の最初のパラメーターであるエコー文字列を含む引数の配列です。

exec に渡された成功コールバックは、単純に window.echo のコールバック関数への参照です。ネイティブプラットフォームがエラーコールバックを発生させた場合、単に成功コールバックを呼び出して、デフォルトの文字列を渡します。

ネイティブインターフェース

プラグインの JavaScript を定義したら、少なくとも 1 つのネイティブ実装で補完する必要があります。各プラットフォームの詳細を以下に示します。それぞれが上記の簡単な Echo プラグインの例に基づいて構築されています。

• Android プラグイン
• iOS プラグイン
• Windows プラグイン

開発中のプラグインのテスト

開発中にプラグインを手動でテストする最も簡単な方法は、通常どおりに Cordova アプリを作成し、--link オプションを使用してプラグインを追加することです。

cordova plugin add ../path/to/my/plugin/relative/to/project --link

これにより、プラグインファイルをコピーする代わりにシンボリックリンクが作成されるため、プラグインを操作してからアプリを再構築するだけで変更を使用できます。

Plugman を使用したプラグインの検証

plugman ユーティリティを使用して、プラグインが各プラットフォームに正しくインストールされるかどうかを確認できます。次の node コマンドを使用して plugman をインストールします。

npm install -g plugman

初めてのアプリの作成ガイドで説明されているように、デフォルトの CLI で生成されたプロジェクトに含まれるトップレベルの www ディレクトリなど、有効なアプリソースディレクトリが必要です。

次に、次のコマンドを実行して、iOS の依存関係が正しくロードされるかどうかをテストします。

plugman install --platform ios --project /path/to/my/project/www --plugin /path/to/my/plugin

plugman オプションの詳細については、Plugman を使用したプラグインの管理を参照してください。プラグインを実際に デバッグする方法については、上記にリストされている各プラットフォームのネイティブインターフェースを参照してください。

プラグインの公開

プラグインは任意の npmjs ベースのレジストリに公開できますが、推奨されるレジストリは npm レジストリです。他の開発者は、plugman または Cordova CLI のいずれかを使用してプラグインを自動的にインストールできます。

npm にプラグインを公開するには、次の手順に従う必要があります。

• plugman CLI をインストールします

  $ npm install -g plugman
  

• プラグインの package.json ファイルを作成します。

  $ plugman createpackagejson /path/to/your/plugin
  

• 公開します

  $ npm adduser # that is if you don't have an account yet
  $ npm publish /path/to/your/plugin
  

npm の使用方法の詳細については、npm ドキュメントサイトの npm パッケージの公開を参照してください。

プラグイン検索との統合

Cordova プラグイン検索にプラグインを表示するには、公開する前にプラグインの package.json ファイルに ecosystem:cordova キーワードを追加します。

特定のプラットフォームのサポートを示すには、package.json のキーワードリストに cordova-<platformName> 形式のキーワードを追加します。Plugman の createpackagejson コマンドはこれを実行しますが、package.json を生成するために使用しなかった場合は、以下に示すように手動で編集する必要があります。

たとえば、Android、iOS、Windows をサポートするプラグインの場合、package.json のキーワードには次が含まれている必要があります。

"keywords": [
    "ecosystem:cordova",
    "cordova-android",
    "cordova-ios",
    "cordova-windows"
]

package.json のより詳細な例については、cordova-plugin-device の package.json ファイルを参照してください。

Cordova の依存関係の指定

Cordova 6.1.0 では、プラグインの Cordova 関連の依存関係をプラグインの package.json ファイルの一部として指定するためのサポートが追加されました。プラグインは、npm からプラグインをフェッチするバージョンを選択する際に Cordova CLI にガイダンスを提供するために、複数のリリースの依存関係をリストできます。CLI は、ローカルプロジェクトにインストールされているプラットフォームとプラグイン、およびローカルの Cordova CLI バージョンと互換性のある最新のプラグインリリースを選択します。プラグインのリリースが互換性がない場合、CLI は失敗した要件についてユーザーに警告し、最新のリリースをフェッチするという古い動作に戻ります。

この機能は、最終的に plugin.xml の engines 要素を置き換えることを目的としています。依存関係をリストすることは、プラグインが npm からフェッチされたときに壊れて表示されたり、ビルドエラーを引き起こしたりしないようにするための良い方法です。プラグインの最新リリースがプロジェクトと互換性がない場合、CLI はアプリ開発者に満たされていないプロジェクト要件のリストを提供し、非互換性を認識してプロジェクトを更新してプラグインをサポートできるようにします。これにより、古いプラットフォームとプラグインに対してビルドを行っている開発者を混乱させることなく、プラグインが破壊的な変更に対応できるようになります。

プラグインの Cordova 関連の依存関係を指定するには、package.json の engines 要素を、次の構造の cordovaDependencies オブジェクトを含めるように変更します。

"engines": {
    "cordovaDependencies": {
        PLUGIN_VERSION: {
            DEPENDENCY: SEMVER_RANGE,
            DEPENDENCY: SEMVER_RANGE,
            ...
        },
        ...
    }
}

• PLUGIN_VERSION は、プラグインのバージョンを指定します。npm の semver パッケージで定義されている単一のバージョンの構文、または上限 (以下を参照) に従う必要があります。
• DEPENDENCY は次のいずれかです。
  • Cordova CLI: "cordova"
  • Cordova プラットフォーム: "cordova-android"、"cordova-ios"、"cordova-windows" など。
  • 別の Cordova プラグイン: "cordova-plugin-camera" など。
• SEMVER_RANGE は、npm の semver パッケージで定義されている範囲の構文に従う必要があります。

注: Cordova プラットフォームの DEPENDENCY は、OS ではなく Cordova プラットフォームを指します。つまり、Android OS ではなく cordova-android です。

cordovaDependencies には、任意の数の PLUGIN_VERSION 要件と任意の数の DEPENDENCY 制約をリストできます。依存関係がリストされていないプラグインのバージョンは、その下にある最大の PLUGIN_VERSION と同じ依存関係情報を持つと想定されます。たとえば、次のエントリを考えてみましょう。

"engines": {
    "cordovaDependencies": {
        "1.0.0": { "cordova-android": "<3.0.0"},
        "2.1.0": { "cordova-android": ">4.0.0"}
    }
}

最小のエントリ (この例では 1.0.0) より下のすべてのプラグインバージョンは、依存関係がないと想定されます。1.0.0 から 2.1.0 までのプラグインのバージョンは、バージョン 1.0.0 (3.0.0 より小さい cordova-android バージョン) と同じ依存関係を持つと想定されます。これにより、破壊的な変更がある場合にのみ cordovaDependencies 情報を更新できます。

上限

単一のバージョンに加えて、cordovaDependencies 内の PLUGIN_VERSION は、プラグインの古いリリースに対するエントリを修正するために上限を指定することもできます。これは、DEPENDENCY で破壊的な変更が発生し、それをサポートしないプラグインのすべての古いバージョンに対して新しい制約を追加する必要がある場合に役立ちます。これらの上限は、< の後に単一の semver バージョン (任意の範囲ではありません!) を記述する必要があります。これにより、指定されたバージョンよりも低いプラグインのすべてのバージョンに、指定された DEPENDENCY 値が適用されます。たとえば、次のエントリを検討してください。

"engines": {
    "cordovaDependencies": {
        "0.0.1":  { "cordova-ios": ">1.0.0" },
        "<1.0.0": { "cordova-ios": "<2.0.0" },
        "<2.0.0": { "cordova-ios": "<5.0.0" }
    }
}

ここでは、1つのプラグインバージョン (0.0.1) と、cordova-iosを制約する2つの上限 (<1.0.0 と <2.0.0) を指定しています。2つの上限は、0.0.1の制約を上書きするのではなく、評価時に AND で結合されます。CLIがプロジェクトの cordova-ios のバージョンをチェックすると、プラグインバージョン 0.0.1 に対して評価される制約は、これら3つの組み合わせになります。

    cordova-ios >1.0.0 AND cordova-ios <2.0.0 AND cordova-ios <5.0.0

許可される PLUGIN_VERSION の値は、単一のバージョンまたは上限のみであり、他の semver 範囲はサポートされていないことに注意してください。