9、插件开发指南（基础知识）

最新推荐文章于 2018-07-05 11:15:10 发布

Android打虎将

最新推荐文章于 2018-07-05 11:15:10 发布

阅读量1.7k

点赞数 2

分类专栏： Cordova 文章标签： cordova 插件开发

Cordova 专栏收录该内容

19 篇文章 0 订阅

订阅专栏

翻译自cordova官方文档（如果需要链接，请自行对照原文链接进行查看）：
https://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html

插件开发指南

插件是一种可以帮助app在其运行的原生平台上通过cordova webview与注入的代码进行交流的包。插件打破了本身web架构的app和设备以及平台元素交互的壁垒。所有的主要的cordova的接口都是以插件形式实现的，另外还有好多像条码扫描，NFC或者设计日历界面等其他的插件。目前我们已经有了一系列的可获取的插件列表。

插件提供了一个JavaScript接口可以支持与多个平台相应的代码进行交互的方式。本质上，这通过一个普通的JavaScript接口隐藏了背后的各种原生代码实现。

本节介绍一个简单地echo插件，通过JavaScript传递了一个字符串到平台的后端，然后我们就可以通过这个字符串实现复杂的功能。本节讨论了基本插件的结构和对外的JavaScript接口。对于每个该插件对应的原生接口，请参阅本节末的列表。

另外，如果想写插件，最好的方式就是研究已有插件的实现。

构建插件

应用开发者可以通过命令行:plugin add命令（请参阅命令行文档）来为工程添加一个插件。该命令的参数是包含插件代码一个Git仓库的URL。以下是一个扩展了cordova设备信息的API的实例:

$ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git

本插件库必须配置一个顶级的plugin.xml配置文件。在插件配置说明中详细介绍了多种方式来对该文件进行配置。以下Device插件的缩略版提供了关于配置文件的一个简单的例子：

<?xml version="1.0" encoding="UTF-8"?><pluginxmlns="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-modulesrc="www/device.js"name="device"><clobberstarget="device" /></js-module><platformname="ios"><config-filetarget="config.xml"parent="/*"><featurename="Device"><paramname="ios-package"value="CDVDevice"/></feature></config-file><header-filesrc="src/ios/CDVDevice.h" /><source-filesrc="src/ios/CDVDevice.m" /></platform></plugin>

顶层插件标签元素id使用了一种反向域的方式来确认是用户添加的插件。js-module标签标示JavaScript接口的路径。platform标签标示对应的原生代码，本例中是IOS平台。config-file标签标示能够使平台能够感知额外的代码库的config.xml文件。head-file和source-file标签标示了库的组件文件的位置。

验证插件

你可以用plugman工具来检测插件是否已经完成针对每个平台的安装。安装plugman使用下面的node命令：

$ npm install -g plugman

你需要一个有效的app的源目录，比如在命令行文档中介绍的默认使用CLI生成的顶级www目录。确保应用程序的index.html主页引用插件的JavaScript接口的名称在相同的源路径中：
然后运行下面的命令来测试iOS的依赖关系是否正确加载：（示例）

$plugmaninstall--platformios--project/path/to/my/project/www--plugin/path/to/my/plugin

有关plugman的详细说明，请参见使用Plugman管理插件。有关如何实际调试插件的信息，请参阅本页面底部列出的每个平台的原生接口介绍。

JavaScript接口

JavaScript提供了一个前置接口，使得他成为插件的最重要的部分。你可以以你喜欢的方式构建你的JavaScript插件，但是你必须调用cordova.exec来进行和原生的交互，使用下面的语法：

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

下面是每个参数如何工作的说明：
function(winParam) {}：一个成功回调函数。假设你的调用成功完成，该功能与您传递给它的任何参数一起执行。
function(error) {}: 错误回调方法。如果操作没有成功执行，这个方法会带着错误参数一起执行。
“service”: 原生调用的服务名。会关联到原生类，更多信息在下面的原生指导列表中。
“action”: 这个是调用原生的行为明。会关联到原生的方法。请参阅下面的原生指导列表。

JavaScript例子

这个例子展示了一种扩展Javascript接口的方式：

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

在这个例子中，插件关联了一个窗口对象作为新的echo方法。这样的话插件用户的调用方式为：

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

然后看cordova.exec方法的最后三个参数。首先调用Echo服务，一个类名。第二个是请求echo方法，即类中的方法。第三个是包含echo字符串的一个数组，它是window.echo函数的所传递的第一个参数。

传递到EXEC的成功回调仅仅是使用window.echo成功回调函数一个参考（如上面例子中就是执行alert(echoValue == “echome”);来判断是否成功回调）。如果本机平台触发错误回调，这样也只是调用成功回调并传递一个默认的字符串’Nothing to echo.’。

原生接口

一旦你定义好插件的JavaScript方法，你需要至少一个原生接口来完成整个流程。每个平台的详细内容，每个建立在简单的Echo插件上面的例子如下：
Amazon Fire OS Plugins
Android Plugins
iOS Plugins
BlackBerry 10 Plugins
Windows Phone 8 Plugins
Windows Plugins

发布插件

一旦你开发了一个插件，并且你想发布分享到社区。你可以发布你的插件到任意的基于npmjs-的注册表。但是推荐的方式是NPM注册表。请阅读我们的发布到NPM的说明：
注意：Cordova插件注册表正在变动为只读状态。publish/unpublish的命令已经从plugman中移除，所以你需要使用相关的npm命令。
其他开发者可以使用plugman或者Cordova CLI来自动安装你的插件。（每一个开发过程的详细信息，请参阅 Using Plugman to Manage Plugins和The Command-Line Interface.)
发布插件到NPM注册表，你需要使用以下步骤：
安装plugman CLI工具

$ npm install -g plugman

为你的插件创建package.json文件

$ plugman createpackagejson /path/to/your/plugin

发布：

$ npm adduser # 这是个你没有账号的示例写法$ npm publish /path/to/your/plugin

更多的内容请参考NPM文档站点的关于如何发布一个npm包

与搜索插件集成

为了能在插件搜索中找到你的插件，请再发布插件之前在package.json文件中加入ecosystem:cordova关键词
为了表明插件支持特定的平台，需要在package.json文件中的关键字列表中加入特定的平台中加入关键字如：cordova-.Plugman的createpackagejson命令已经完成上面的功能，但是如果你没有使用plugman，那么你就需要按照下面示例中显示的方式进行修改.
例如：一个插件支持android,IOS以及windows.那么package.json中的关键字书写如下：

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

更多关于package.json文件的内容，可以参考 package.json file of cordova-plugin-device.

指定Cordova的依赖

Cordova 6.1.0提供了插件通过package.json添加特定Cordova-related依赖的支持。插件将提供多个版本的依赖列表，从而为了能够在通过Cordova CLI从npm选择插件版本时提供引导。CLI将选择支持本地平台和插件的最新版本作为本地版本。如果未获取到合适的已发布版本，CLI将提示用户请求失败然后重新请求获取新版本。
这种方式将代替原来的再plugin.xml中的engineselement中声明依赖的方式，并且这种添加依赖的方式将有助于用户从npm下载插件之后不会出现崩溃或者出现编译错误。如果当前最新版本的插件不适合用户的当前项目，CLI将给开发者插件未满足他的项目需求的列表，从而让开发者明白为什么不支持插件，然后升级项目来支持插件。这将允许你的插件在发生重大变更时不必担心开发者还在使用老版本平台和插件。
为你的插件指定依赖，再package.json文件中替换engines元素中的cordovaDependencies中的内容，用下面的结构：

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

PLUGIN_VERSION 指定一个插件版本. 这应该提供一个经过npm的语义版本包定义的单一的版本或者一个版本上线(示例如下)
DEPENDENCY 将可以是下面中的一个:
The Cordova CLI, “cordova”(cordova版本)
平台 (如： “cordova-android”, “cordova-ios”, “cordova-windows”等)
另一个插件(如： “cordova-plugin-camera”等)
SEMVER_RANGE 应该是一个经过npm的语义版本包定义的范围
注意：一个平台的依赖是cordova对应的平台，不是系统（就如：是cordova-android而不是Android OS）
你的cordovaDependencies可以列出PLUGIN_VERSION的任意数目的列表和任意数目的DEPENDENCY。你的插件版本如果没有他们自己的依赖则会被认为是低于当前版本的最高版本的依赖。示例如下：考虑下面的情况：

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还可以指定你的插件老版本的上限。这将在一个重大更新出现所有老版本插件不支持的新的约束和依赖时很有用处。这将写成：一个<跟在一个明确的版本后面（不是一个随意的范围!）。这样使得所有低于当前版本的插件都是用当前的依赖。例如：考虑下面的情况：

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版本，他们在升级时合并添加的。当CLI检查项目的cordova-ios版本，将会对于0.0.1版本进行重新约束，他们三个组合如下：

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

请注意唯一允许的插件版本是单独的版本或者更高的版本。其他的版本并没有这些版本范围支持。