创建插件

插件是注入代码包，允许 Cordova webview（应用程序在其中呈现）与运行它的原生平台进行通信。插件提供对设备和平台功能的访问，这些功能通常对基于 Web 的应用程序不可用。所有主要的 Cordova API 功能都作为插件实现，还有许多其他插件可用于启用诸如条形码扫描仪、NFC 通信或定制日历界面等功能。您可以在 Cordova 插件搜索页面 上搜索可用的插件。

插件包含单个 JavaScript 接口以及每个支持平台的相应原生代码库。本质上，这隐藏了各种原生代码实现，使其位于一个通用的 JavaScript 接口后面。

本节将逐步介绍一个简单的echo插件，该插件将字符串从 JavaScript 传递到原生平台并返回，您可以将其用作构建更复杂功能的模型。本节讨论了基本插件结构和面向外部的 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="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操作，该类中的一个方法。第三个是一个包含回声字符串的参数数组，它是window.echo函数的第一个参数。

传递到exec中的成功回调只是window.echo的回调函数的引用。如果原生平台触发错误回调，它只会调用成功回调并将默认字符串传递给它。

原生接口

定义插件的 JavaScript 后，您需要用至少一个原生实现来补充它。每个平台的详细信息列在下面，每个平台都基于上面简单的 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 插件搜索 中显示插件，请在发布之前将ecosystem:cordova关键字添加到插件的package.json文件中。

要指示对特定平台的支持，请在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文件的一部分。插件可以列出多个版本的依赖项，以在 Cordova CLI 选择要从 npm 获取的插件版本时提供指导。CLI 将选择与本地项目的已安装平台和插件以及本地 Cordova CLI 版本兼容的最新版本插件。如果插件的任何版本都不兼容，CLI 将警告用户有关失败的要求，并回退到从 npm 获取最新版本的旧行为。

此功能旨在最终替换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指的是 Cordova 平台，而不是操作系统，即cordova-android而不是 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" }
    }
}

这里我们指定了一个插件版本（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 范围。