plugin development guide（翻译）cordova插件开发指导

最新推荐文章于 2023-05-02 11:49:24 发布

robert_cysy

最新推荐文章于 2023-05-02 11:49:24 发布

阅读量647

点赞数

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

Cordova 专栏收录该内容

9 篇文章 0 订阅

订阅专栏

http://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html

翻译文本

一个插件是一个可以注入的代码包。代码包使得cordova 的webview对硬件平台的交流就和原生APP和硬件交流一样。插件提供了基于网页的app访问设备和平台的功能，原本这是不可能的。所有主要的Cordova API特色功能都是实现为插件形式，这样的例子有很多，比如条形码扫描、NFC通信，定制的日历界面。你可以在这个连接找到可用的插件Cordova Plugin Search page.

插件是由一个单独的JavaSctipt 接口和相应的本地支持的平台上的编码语言所提供的库组成。在本质上这个普通的JavaSctipt接口下隐藏了各种平台下的本地代码实现。本节通过一个回声插件（echoplugin）来演示插件的原理与结构。回声插件的功能是通过JavaScript接口传递一个字符串到本地平台，然后在反向传回去。你可以通过这个模型建立更加复杂的特色功能。这一节讨论插件的基本结构和JavaSctript对外提供接口的方式。对于相关联的本地代码接口请参考本节结尾。

为了看懂本篇说明，并准备编写一个插件，最好浏览一般已经存在的插件，已经存在的插件列表连接为existing plugins。

建立一个插件

应用程序开发者使用命令行的命令来给项目添加插件，插件的命令行命令有pluginadd command。这个命令的参数是一个URL。指向一个git库。库里放着一个插件的代码。这个例子实现了Cordova设备 API。

cordova plugin addhttps://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git

这个插件创库必须有一个顶层的plugin.xml配置文件。有很多方法去配置这个文件。可用的配置方法详细内容在PluginSpecification.。这个小型的设备插件是一个示例模型。

<?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>

最上层的插件标签是id。Id属性使用了域名的格式定义了插件的名字。Js-module标签执行了一般JavaScript 接口的路径。Platform标签指明了相关的本地代码，这个例子是对于ios平台来说的。Config-file标签封装了feature标签。注入到config.xml的Feature标签让项目平台知道了有一个附加的插件插入。Header-file和source-file标签指明了到库组成文件的路径。

使用plugman来验证一个插件的正确性

你可以使用plugman命令来检查一个插件是否为每个平台正确安装。使用如下命令安装plugman：

npm install -g plugman

你需要一个有效的项目目录，比如在www的上层目录。目录包括命令行产生的工程文件。相关描述可以在Create your first app找到。

然后运行以下命令去测试ios的依赖项是否安装正确。

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

plugman的详细参数选项可以参考这个连接：Using Plugman to Manage Plugins.关于怎样真正测试一个插件。去看本文底部每一个平台下的本地接口说明。

JavaScript 接口说明

Javascript接口提供了用于界面的调用接口。使得它成为插件最重要的部分。你可以自己构造你JavaScript的插件接口。但是你得调用cordova.exec函数去和本地平台交流数据。请使用一下格式。

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

这里是每个参数的作用：

function(winParam){}:是成功的回调函数。假设你的exec函数调用成功，这个函数就会执行你传递了任何参数。

function(error){}:是错误回调函数。如果操作没有成功完成。这个函数就会执行并传递出可选的错误参数。

"service":调用本地服务的服务名称。这个是相关到本地的class（类）。对于这个参数在之后的文章会提供详细说明。

"action":要调用的本地动作的名称。这个一般是指本地的类里面的方法。详细看本文后面的介绍。

[/*arguments */]:传递到本地环境中的一个数组参数。

JavaSctipt示例

这个例子展示了怎样实现一个插件的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动作（action），是这个类里面的一个函数。第三个是包含echo字符串的数组。是函数window.echo的第一个参数。

成功的回调函数传递进了exec，只是对window.exec函数的一个简单引用。如果本地平台触发了错误回调函数。只是简单的调用失败函数即传回一个默认的字符串。

本地接口

一旦你为你的插件定义了javaScript文件。你就至少需要实现一个本地平台部件。下面是每个平台的详细连接，每个都是关于建立回声插件的例子代码。

发表插件

你可以发表你的插件到任意基于npmjs的创库。但是推荐的是npm registry。其他开发者可以通过plugman后者cordova命令行自动的安装你的插件。

在npm上发表你的插件你需要如下步骤：

安装plugman命令

npm install -g plugman

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

plugman createpackagejson /path/to/your/plugin

发表：

$ npm adduser # 如果你还没有账户，执行此命令

$ npm publish /path/to/your/plugin

关于跟多的npm的使用方法，请参考：Publishingnpm Packages。

与插件搜索交互

为了能在Cordova Plugin Search被搜索到，需要增加ecosystem:cordova关键字到package.json文件里在你发布插件之前。

为了说明你的插件可以运行的指定平台，以**cordova-<platformName>**的格式增加关键字。Plugman的createpackagejson命令为你做这个工作，但是如果你没有用createpackagejson，那么你的手工添加关键字，添加方式如下：

例如，一个支持Android，iOS，Windows的插件应该包括一下部分：

"keywords": [

"ecosystem:cordova",

"cordova-android",

"cordova-ios",

"cordova-windows"

]

关于更加详细的package.json文件例子，请参考：package.jsonfile of cordova-plugin-device.。

设定cordova依赖项

Cordova6.1.0增加了支持cordova的增加相关依赖相的功能。这个功能被放置在package.json文件里。当从npm挑选一个版本的插件时，插件为cordova 命令行提供多个版本的依赖项来提供指导。命令行会选择最新发布的且与项目工程兼容的插件来安装。并且会更新本地的cordova命令行版本。如果发布的插件都不兼容。命令行就会警告用户有关失败的请求并且返回到之前的命令行版本来配合新的版本。

这个特色功能是为了最终替换掉plugin.xml里的引擎元素。列出依赖项是一个很好的方法去避免插件错误或引起编译错误当从npm获取插件的时候。如果最新的插件与工程不兼容，命令行会给开发者列出一个需求列表，因此开发者可以意识到不兼容问题，并且升级自己的项目来支持你的插件。这使得你的插件来应对断链的改变而不至于让在使用旧平台或旧插件的开发者困惑。

为一个插件指出与cordova相关的依赖插件。使用一下方法使得package.json里的engines元素去包含cordovaDependencies对象

"engines": {

"cordovaDependencies": {

PLUGIN_VERSION: {

DEPENDENCY: SEMVER_RANGE,

...

}

PLUGIN_VERSION 说明了插件的版本，每个版本都应该按照格式增加此项，就像在npm's semver package里面的定义或具有一个上线（看下面）

DEPENDENCY 选项可以是以下几项：

Cordova命令行“cordova”

Cordova平台：“cordova-android”，“cordova-ios”，“cordova-windows”，等

另一个cordova插件：“cordova-plugin-camera”

SEMVER_RANGE 应该遵循 npm's semver package指定的语法。

注意：cordova平台的DEPENDENCY是相对于cordova平台来说的而不是系统。比如：是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一样的依赖项。这个特性是你只有在大量的改变才需要更新你的cordovaDependencies。

上线

除了一个单独的版本。cordovaDependencies里的一个PLUGIN_VERSION可以给插件指定一个可以达到的最高上线。当DEPENDENCY有很大的更新是这个特性是非常有用的。并且给所有旧的插件增加一个不支持的约束。这些上线应该以如下格式编写，

。。。剩下的部分实在翻译不了了，就我的水平估计翻译了也不成文了。看原文。

In addition to a single version, a PLUGIN_VERSION in cordovaDependencies may also specify an upperbound to amend entries for older releases of your plugin. This is useful when abreaking change occurs in a DEPENDENCY and a new constraint must beadded for all older versions of a plugin that do not support it. These boundsshould be written as a < followed by a single semver version (Notan arbitrary range!). This will apply whatever DEPENDENCY values are given to all versions of the plugin below thespecified version. For example, consider the following entry:

"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"}

Here we specify one plugin version (0.0.1) and two upper bounds(<1.0.0 and <2.0.0) that constrain cordova-ios. The two upper bounds donot override the constraint of 0.0.1, they are combined via AND at evaluationtime. When the CLI checks the cordova-ios version of the project, theconstraint that will be evaluated for plugin version 0.0.1 will be thecombination of these three:

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

Please note that the only PLUGIN_VERSION values allowed are singleversions or upper bounds; no other semver ranges are supported.

robert_cysy

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
plugin development guide（翻译）cordova插件开发指导

http://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html翻译文本一个插件是一个可以注入的代码包。代码包使得cordova 的webview对硬件平台的交流就和原生APP和硬件交流一样。插件提供了基于网页的app访问设备和平台的功能，原本这是不可能的。所有主要的Cordova API特色功能都是实现
复制链接

扫一扫

专栏目录