建立外掛程式

一個外掛程式是一個注入程式碼的套件，讓應用程式呈現的 Cordova 網頁檢視器能與其執行的原生平台通訊。外掛程式提供對網頁應用程式通常無法使用的裝置和平台功能的存取權。所有主要的 Cordova API 功能都實作為外掛程式，還有許多其他外掛程式可用，能啟用條碼掃描器、NFC 通訊或客製化日曆介面等功能。您可以在 Cordova 外掛程式搜尋頁面上搜尋可用的外掛程式。

外掛程式包含一個單一的 JavaScript 介面，以及每個支援平台的對應原生程式碼函式庫。本質上，這將各種原生程式碼實作隱藏在一個通用的 JavaScript 介面之後。

本節逐步說明一個簡單的echo外掛程式，它將字串從 JavaScript 傳遞到原生平台再傳回來，您可以使用它作為建立更複雜功能的模型。本節討論基本的外掛程式結構和外顯的 JavaScript 介面。對於每個對應的原生介面，請參閱本節末尾的清單。

除了這些說明之外，在準備撰寫外掛程式時，最好查看現有的外掛程式以取得指導。

建立外掛程式

應用程式開發人員使用 CLI 的 plugin add 命令將外掛程式新增至專案。該命令會將包含外掛程式程式碼的 git 儲存庫的 URL 作為引數。此範例實作 Cordova 的裝置 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="http://apache.org/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 標籤封裝了一個 feature 標籤，該標籤會注入到平台特定的 config.xml 檔案中，以讓平台知道額外的程式碼函式庫。
  • 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 介面的方法

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 函數的最後三個引數。第一個呼叫 Echo 服務，即類別名稱。第二個要求 echo 動作，即該類別中的方法。第三個是包含 echo 字串的引數陣列，這是 window.echo 函數的第一個參數。

傳遞到 exec 的成功回呼只是 window.echo 的回呼函數的參考。如果原生平台觸發錯誤回呼，則它只會呼叫成功回呼並傳遞預設字串。

原生介面

定義外掛程式的 JavaScript 後，您需要以至少一個原生實作來補充它。下面列出了每個平台的詳細資訊，並且每個平台都以上面的簡單 Echo 外掛程式範例為基礎

在開發期間測試外掛程式

在開發期間手動測試外掛程式的最簡單方法是像往常一樣建立 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 外掛程式搜尋中顯示外掛程式，請在發佈前將 ecosystem:cordova 關鍵字新增至外掛程式的 package.json 檔案。

若要指示支援特定平台，請在 package.json 的關鍵字清單中新增格式為 cordova-<platformName> 的關鍵字。Plugman 的 createpackagejson 命令會為您執行此動作，但如果您未使用它來產生 package.json，則應手動編輯它，如下所示。

例如，對於支援 Android 和 iOS 的外掛程式，package.json 中的關鍵字應包含

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

如需 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 外掛程式："cordova-plugin-camera" 等。
  • SEMVER_RANGE 應該遵循 npm semver 套件定義的範圍語法

注意：Cordova 平台 DEPENDENCY 指的是 Cordova 平台，而不是作業系統，即 cordova-android 而不是 Android OS。

您的 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 版本 (cordova-android 版本小於 3.0.0) 相同的相依性。這讓您可以僅在發生重大變更時更新 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" }
    }
}

這裡我們指定一個外掛程式版本 (0.0.1) 和兩個上限（<1.0.0 和 <2.0.0），這些上限會約束 cordova-ios。這兩個上限不會覆蓋 0.0.1 的約束，它們會在評估時透過 AND 運算組合。當 CLI 檢查專案的 cordova-ios 版本時，針對外掛程式版本 0.0.1 評估的約束將會是這三者的組合。

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

請注意，唯一允許的 PLUGIN_VERSION 值為單一版本或上限；不支援其他 semver 範圍。