插件開發指南 · Angular 與 Cordova

[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)