[TOC]
# [Cordova Plugin 开发](http://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html)
从版本3.0开始，Cordova将所有设备API实现为插件，并在默认情况下禁用它们。
首先我们要知道，cordova 这种形式的调用原生功能是需要插件的，那么开发插件也就是cordova的核心！目前开源社区已经有很多的cordova方面的插件！你可以在[cordova plugin搜索](http://cordova.apache.org/plugins/) 插件，或者在Github等其他托管平台搜索相关插件。
官网文档，通过开发一个`echo`的插件，将字符串从JavaScript传递到本机平台并返回，让用户将其作为一个模型来构建更复杂的插件。
## 构建插件
一般我们通过类似：
~~~
cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git
~~~
这样的命令来添加插件！（上面的示例，添加了一个在线的rep上关于设备信息的插件）。
那么首先插件存储库必须具有顶级`plugin.xml`文件。[Plugin Specification](http://cordova.apache.org/docs/en/8.x/plugin_ref/spec.html)提供了详细信息。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>
~~~
1. id：插件的标识，使用相同的反向域格式将插件包标识为它们添加到的应用程序。即发布到 `cordova.apache.org/plugins` 的 ID
2. name：插件的名称
3. js-module：对应我们的 javascript 文件，src 属性指向 `www/device.js`
4. platform：为本例中的 ios 平台指定一组相应的原生代码。
5. config-file：封装了一个特性标记，该标记注入到特定于平台的`config.xml`文件中，以使平台知道其他代码库。
6. header-file 和 source-file 标记指定库的组件文件的路径。
## 使用Plugman验证插件
Cordova plugman是用于安装和管理插件的命令行工具。如果你希望你的应用程序能够在一个特定的平台上运行，应该使用 plugman。如果想创建跨平台应用程序，你应该使用`cordova-cli`，这将在不同平台上修改插件。
您可以使用plugman实用程序来检查插件是否为每个平台正确安装。使用以下命令安装：
~~~
npm install -g plugman
~~~
在测试前，需要你有一个cordova的项目（没有项目，你怎么测试该插件可以正确被安装），然后在使用下面的命令，测试是否正确加载 iOS 依赖项：
~~~
plugman install --platform ios --project /path/to/my/project/www --plugin /path/to/my/plugin
~~~
有关plugman 选项的详细信息，请参见[使用 plugman来管理插件](http://cordova.apache.org/docs/en/latest/plugin_ref/plugman.html)。有关如何实际调试插件的信息，请参见本页面底部列出的每个平台的本机接口。
## JavaScript 接口
接下来就是前端人员关心的 js 接口，这可能是插件最重要的部分。你可以随心所欲地构建你的插件的JavaScript，但您需要使用以下语法调用 `cordova.exec` 与本机平台进行通信：
~~~
cordova.exec(function(winParam) {},
function(error) {},
"service",
"action",
["firstArgument", "secondArgument", 42, false]);
~~~
让我们来看看这些参数：
`function（winParam）{}`：一个成功的回调函数。假设您的`exec`调用成功完成，此函数将与您传递给它的任何参数一起执行。
`function（error）{}`：错误回调函数。如果操作未成功完成，则此函数将使用可选的错误参数执行。
`“service”`：在本机端调用的服务名称。这对应于原生类，下面列出的原生指南中提供了更多信息。
`“action”`：在本机端调用的动作名称。这通常对应于原生类方法。请参阅下面列出的原生指南。
`[/ * arguments * /]`：传递给原生环境的参数数组。
## 示例JavaScript
下面的示例，简单的实现了 插件的js 接口：
~~~
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的 成功回调只是对 `windows.echo回调函数`的引用。如果本机平台触发错误回调，它只需调用 success回调并传递一个默认字符串。
## 本机接口
为插件定义JavaScript后，您需要使用至少一个本机实现来补充它。下面列出了每个平台的详细信息，每个平台都基于上面的简单 Echo 插件示例构建：
* [Android插件开发指南](Android插件开发指南.md)
* [IOS插件开发指南](IOS插件开发指南.md)
## 发布插件
您可以将插件发布到任何基于 npmjs的注册表，但推荐的是npm注册表。其他开发人员可以使用plugman或Cordova CLI自动安装插件。
步骤：
1. 安装 plugman
~~~
$ npm install -g plugman
~~~
2. 为你的插件创建一个`package.json` 文件：
~~~
$ plugman createpackagejson /path/to/your/plugin
~~~
3. 发布
~~~
$ npm adduser # that is if you don't have an account yet
$ npm publish /path/to/your/plugin
~~~
有关npm用法的更多详细信息，请参阅npm文档站点上的[发布npm包](https://docs.npmjs.com/getting-started/publishing-npm-packages)。
## 与插件搜索集成
要在[Cordova插件搜索](http://cordova.apache.org/plugins/)中显示插件，请在发布之前将 `ecosystem:cordova` 关键字添加到插件的 `package.json`文件中。
要表示对特定平台的支持，请以 `**cordova-<platformName>**` 格式将关键字添加到 `package.json`中的关键字列表中。 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 文件](https://github.com/apache/cordova-plugin-device/blob/master/package.json)。
## 指定Cordova依赖项
Cordova 6.1.0增加了对插件的Cordova相关依赖项的支持，作为插件的package.json文件的一部分。当corodva CLI从npm 拉取安装插件时可能会有多个已发布的插件，CLI会安装与本地项目环境相兼容的版本插件，如果插件的任何版本都不兼容，CL I将警告用户该失败的需求，并退回到获取最新版本的旧行为。
此特性打算最终替换 `plugin.xml` 中的 `engine`元素。列出依赖项是确保从npm获取时插件不会出现故障或导致构建错误的好方法
要为插件指定与Cordova相关的依赖项，请更改 `package.json` 中的 `engines`元素以包含具有以下结构的`cordovaDependencies`对象：
~~~
"engines": {
"cordovaDependencies": {
PLUGIN_VERSION: {
DEPENDENCY: SEMVER_RANGE,
DEPENDENCY: SEMVER_RANGE,
...
},
...
}
}
~~~
`PLUGIN_VERSION`：指定插件的版本。
`DEPENDENCY`：可能是以下之一：
* Cordova CLI：“cordova”
* Cordova平台：“cordova-android”，“cordova-ios”，“cordova-windows”等。
* 另一个Cordova插件：“cordova-plugin-camera”等
`SEMVER_RANGE`：应遵循[npm的semver包](https://www.npmjs.com/package/semver)定义的范围的语法
注意：Cordova平台 `DEPENDENCY` 是指 Cordova平台，而不是操作系统，即 cordova-android 而不是 Android OS。
你的`cordovaDependencies` 可能列出来很多的插件版本`PLUGIN_VERSION`。对于未列出依赖项的插件版本，我们将假定它们具有与它们下面列出的最高 `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）和两个约束 `cordova-ios` 的上限（ <1.0.0 和 <2.0.0 ）。两个上限不会覆盖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范围。
# 为插件编写ionic native
ionic native 就是用typescript语法包装了一下 Cordova / PhoneGap插件的接口，更方便地为您的Ionic 移动应用程序添加所需的原生功能。
1. 用plugman生成cordova插件，发布到github上面，这个插件在typescript中还用不了
2. 可以参照 `@ionic-native` 里面的写法自己写 typescript 的用法，也可以参考 [native 在github上的说明](https://github.com/ionic-team/ionic-native/blob/master/DEVELOPER.md)
下载[git项目](https://github.com/ionic-team/ionic-native.git)， npm install安装插件，然后用 `gulp plugin:create -n PluginName` 生成插件脚本，在 `src/@ionic-native/plugins/plugin-name` 目录中的 `index.ts` 中配置好 cordova项目的相关信息，最后执行 `npm run build` 就可以在 `dist` 目录生成编译后的 native插件
将步骤1中生成的cordova插件拷贝到项目的 `node_modules` 中，步骤2中在 `dist` 目录中生成的native插件脚本拷贝到 `node_modules/@ionic-native` 中，然后 `package.json` 和 `config.xml` 中都进行配置就可以开始使用了。
## Promises 和 Observables
Ionic Native将插件回调封装在一个Promise 或一个Observable 的包中，为所有插件提供一个通用接口，并确保原生事件触发 angular 的变化检测。
## 安装
要在应用程序中添加Ionic Native，请运行以下命令安装core package：（**请注意**，默认情况下，每个Ionic应用程序都已经包含了该核心软件包）
~~~
npm install @ionic-native/core --save
~~~
## 使用
举个例子，比如安装 `cordova-plugin-camera` 这个相机插件：
~~~
ionic cordova plugin add cordova-plugin-camera //原生插件
npm install @ionic-native/camera --save //ionic 封装的代码
~~~
可以通过 `ionic cordova plugin ls` 查看已经安装的插件，可以通过这些列出的名字进行卸载！
## 将插件添加到App模块中
安装插件包后，将其添加到`AppModule`的`NgModule`中。
~~~
...
import { Camera } from '@ionic-native/camera';
...
@NgModule({
...
providers: [
...
Camera
...
]
...
})
export class AppModule { }
~~~
## 使用该插件
~~~
import { Geolocation } from '@ionic-native/geolocation'; //先导入该插件的ionic native
import { Platform } from 'ionic-angular';
class MyComponentOrService {
constructor(private platform: Platform, private geolocation: Geolocation) {
platform.ready().then(() => {
// get current position
geolocation.getCurrentPosition().then(pos => {
console.log('lat: ' + pos.coords.latitude + ', lon: ' + pos.coords.longitude);
});
const watch = geolocation.watchPosition().subscribe(pos => {
console.log('lat: ' + pos.coords.latitude + ', lon: ' + pos.coords.longitude);
});
// to stop watching
watch.unsubscribe();
});
}
}
~~~
## 该插件没有ionic native 包？
可以在项目的`src/`下面添加`declarations.d.ts` 这个声明文件，来避免typescript 编译出错！
~~~
/*
Declaration files are how the Typescript compiler knows about the type information(or shape) of an object.
They're what make intellisense work and make Typescript know all about your code.
A wildcard module is declared below to allow third party libraries to be used in an app even if they don't
provide their own type declarations.
To learn more about using third party libraries in an Ionic app, check out the docs here:
http://ionicframework.com/docs/v2/resources/third-party-libs/
For more info on type definition files, check out the Typescript docs here:
https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html
*/
// declare module '*';
declare let cordova: any;
declare let ShareSDKPlugin: any;
~~~
# 参考
http://www.damirscorner.com/blog/tags/cordova.html
[Plugin Development Guide](http://cordova.apache.org/docs/en/8.x/guide/hybrid/plugins/index.html)
- PWA 概念
- Immutable
- Angular 基础概念
- 入门参考
- Angular 更新总结
- Angular 生态系统
- Rx.js
- Ngrx
- CQRS/ES 模式
- Angular 5 详解
- 测试
- 定义共享模块
- 懒路由加载
- angular组件
- 双向绑定及变化检测
- 样式
- ionic 3详解
- ionic3
- ionic 插件
- Ionic 添加动画
- Ghost-Loading
- 打包发布
- Android上架国内应用市场流程
- 总结
- 文章
- 问题合集
- Cordova
- 插件开发指南
- Android插件开发指南-官网
- IOS插件开发指南-官网
- Hooks 编写
- 桥接技术
- ===cordova插件收集===
- 相关主题-官网
- 实战-自定义插件流程
- UI 及 相关资源