l 介紹
本文將細緻講解cordova插件的創建、編寫、配置、發佈,涉及aar+jar+so、靜態資源、四大組件等。
l 環境準備
1.node
2.ionic
3.cordova
4.plugman
plugman是用於安裝和卸載用於Apache Cordova項目的插件的命令行工具,
安裝plugman
$ npm install -g plugman
5.AndroidStudio
l 一切都要從一個簡單cordova插件開始
l 創建ionic項目
用於測試cordova的插件
ionic start CordovaProject blank
此時cordovaProject下會生成如下結構
在添加platforms和plugins之後,可以在此目錄下打包
CordovaProject$ cordova build android
l 創建插件
創建一個最簡單的Toast插件
plugins$ plugman create --name ThsToast --plugin_id cordova-plugin-ths-toast --plugin_version 1.0.0
創建插件的完整模版:為了方便在插件開發過程中進行測試,將插件創建在 cordovaPluginProject 項目目錄下的 plugins 文件夾下
plugman platform add 創建ThsToast插件的平台基礎代碼
進入具體的插件目錄下,創建插件安卓和iOS平台基礎代碼
cordova-plugin-ths-toast$ plugman platform add --platform_name android
cordova-plugin-ths-toast$ plugman platform add --platform_name ios
添加之後將在cordova-plugin-ths-toast目錄下產生android和ios兩個目錄,
生成的java文件內容如圖所示
重命名ThsToast插件目錄名稱(可選)
接着手動將ThsToast目錄重命名為和上述plugin_id一樣的值:cordova-plugin-ths-toast,命名方式和cordova插件命名規範保持一致,ths是公司的統一標識,通常是英文字符串
重命名ThsToast插件目錄下android目錄java代碼中的package包名和api方法名
需要將默認的包名改為[反向域值].cordova.[插件name],要注意的是,plugin.xml中配置的java文件target-dir輸出目錄需要和這裏包名目錄匹配,如
plugin.xml
<source-file src="src/android/ThsToast.java" target-dir="src/org/apache/cordova/thstoast" />
注意:起名不要和安卓原生方法衝突了,比如這裏ThsToast如果改成Toast,就會和android.widget.Toast中的Toast類重名,主要是區分是系統的還是公司的插件
l 插件配置
ThsToast插件目錄下的plugin.xml配置js調用方法名和資源文件輸出路徑
添加完平台後,cordova-plugin-ths-toast 目錄下的 plugin.xml 文件將添加如下內容
修改 plugin.xml 文件內容如下
<?xml version='1.0' encoding='utf-8'?>
<plugin id="cordova-plugin-ths-toast" version="1.0.0" xmlns="http://apache.org/cordova/ns/plugins/1.0" xmlns:android="http://schemas.android.com/apk/res/android">
<name>Toast</name>
<js-module name="ThsToast" src="www/ThsToast.js">
<!-- target修改, 通過window.ThsToast.show或ThsToast.show即可調用api -->
<clobbers target="ThsToast" />
</js-module>
<platform name="android">
<config-file parent="/*" target="res/xml/config.xml">
<feature name="ThsToast">
<!-- param value修改,[包名].[文件名] -->
<param name="android-package" value="cn.com.ths.thstoast.ThsToast" />
</feature>
</config-file>
<config-file parent="/*" target="AndroidManifest.xml" />
<!-- target-dir修改,最終打包出的java文件完整目錄路徑 -->
<source-file src="src/android/ThsToast.java" target-dir="src/cn/com/ths/thstoast" />
</platform>
<platform name="ios">
<config-file parent="/*" target="config.xml">
<feature name="ThsToast">
<param name="ios-package" value="ThsToast" />
</feature>
</config-file>
<source-file src="src/ios/ThsToast.m" />
</platform>
</plugin>
ThsToast插件目錄下的www/xxx.js 修改js api對象和調用函數
修改exports處理邏輯,增強可讀性(可選)
暴露給js的api方法名通過plugin.xml配置
www/xxx.js中export的ThsToast在plugin.xml中是通過clobbers的target值暴露給js調用的,如果target值改為toast,通過target.show即可調用插件api
<js-module name="ThsToast" src="www/ThsToast.js">
<!-- 通過window.ThsToast.show或ThsToast.show即可調用api -->
<clobbers target="ThsToast" />
</js-module>
exec函數幹了什麼
www/xxx.js中的exec函數可以理解為java中暴露給js的回調方法,用於觸發java的excute方法,該js函數傳的'show'和[arg0],success,error參數將會以action和args,callbackContext.success,callbackContext.error參數的形式傳入java中的excute方法
@Override
public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
……
}
l 在ThsToast插件根目錄裏寫好README,小盆友看了也會用
cordova-plugin-ths-toast$ touch README.md
一個簡單模版
# cordova-plugin-ths-toast
彈出提示框 cordova插件
## 支持平台
Android
## 安裝插件
|```
# 通過npm 安裝插件
cordova plugin add cordova-plugin-ths-toast
# 通過github安裝
cordova plugin add https://github.com/THS-FE/cordova-plugin-ths-toast
# 通過本地文件路徑安裝
cordova plugin add 文件路徑
|```
**説明: ionic 項目命令前加上ionic,即ionic cordova plugin xxxxx**
參數説明:
1. DEFAULT_DELAY 默認提示框延遲彈出的毫秒數
## 配置文件修改
在config.xml文件中 **platform name="android"** 節點下添加以下配置
|```xml
<preference name="DEFAULT_DELAY" value="1000"/>
|```
## 使用方法
顯示提示框
|```javascript
/**
* 顯示提示框
* @param text 顯示文字
* @param success 成功的回調函數
*/
showToast(text, success) {
try {
ThsToast.show(text, success, err => {
console.log('err', err);
this.commUtilProvider.showToast('顯示提示框失敗');
})
}
catch (err) {
console.log(err);
}
};
|```
隱藏提示框
|```javascript
/**
* 隱藏提示框
* @param success 成功的回調函數
*/
hideToast(success) {
try {
ThsToast.hide(success, err => {
console.log('err', err);
this.commUtilProvider.showToast('隱藏提示框失敗');
})
}
catch (err) {
console.log(err);
}
};
|```
**説明:使用ts 進行開發時,需要在文件上變聲明下declare const ThsToast;**
|```typescript
import { Component, OnInit, Input } from '@angular/core';
declare const ThsToast;
@Component({
selector: 'app-explore-container',
templateUrl: './explore-container.component.html',
styleUrls: ['./explore-container.component.scss'],
})
|```
## 常見錯誤
後續更新
|```
l 給ThsToast插件加上package.json,準備發佈到npm
進入ThsToast插件根目錄下
第一種方式:npm init
cordova-plugin-ths-toast$ npm init
第二種方式:plugman createpackagejson(推薦)
cordova-plugin-ths-toast$ plugman createpackagejson ./
上面的命令都將創建一個 package.json 文件,但第二種方式相對於npm init的優點是會生成"cordova"和"keywords"兩個屬性。
"cordova"用於説明插件支持的平台,"keywords"
規定可以在cordova官網通過關鍵字搜索到該cordova插件,"engines"表示插件依賴的各平台版本號,詳細內容請參考cordova創建插件
{
"name": "cordova-plugin-ths-toast",
"version": "1.0.0",
"description": "",
"cordova": {
"id": "cordova-plugin-ths-toast",
"platforms": [
"android",
"ios"
]
},
"keywords": [
"ecosystem:cordova",
"cordova-android",
"cordova-ios",
"toast",
"cordova-plugin-ths-toast"
],
engines: {
cordovaDependencies: {
"1.0.0": { "cordova-android": ">4.0.0" },
">1.0.0": { "cordova-android": ">5.0.0" }
}
},
"author": "",
"license": "ISC"
}
注意: "name"屬性表示插件在npm倉庫中的唯一id,"cordova"中的"id"必須和name保持一致,因為要通過此id才能找到具體哪個插件的平台支持, 比如安裝時就是通過name的值在npm倉庫中查找對應插件並安裝:
cordova plugin add cordova-plugin-ths-toast
這裏可以搜索keywords中的插件
l 發佈插件到git
上傳到公司倉庫: https://github.com/THS-FE
注意github地址一定要發佈到公司git倉庫,不然無法修改和維護源代碼
l 發佈插件到npm
每次發佈記得更新版本號,不然無法發佈
cordova-plugin-ths-toast$ npm login // 沒有賬號則需要到官網申請,登錄過一次後就不用登了
cordova-plugin-ths-toast$ npm publish
l 安裝插件
cordova plugin add cordova-plugin-ths-toast
l 使用插件
js環境
ThsToast.show()
ts環境
declare const ThsToast;
ThsToast.show()
l 插件效果演示
l cordova開發進階
l 開發進階之插件配置
活動
<platform name="android">
<config-file target="AndroidManifest.xml" parent="/manifest/application">
<activity android:name="cn.com.ths.thstoast.MyActivity"/>
</config-file>
</platform>
廣播
靜態註冊
<platform name="android">
<!-- 自定義的廣播接收器 -->
<receiver android:name="cn.com.ths.thstoast.MyBroadcastReceiver" android:enabled="true">
<intent-filter>
<!-- 飛行模式開/關廣播 -->
<action android:name="android.intent.action.AIRPLANE_MODE" />
<category android:name="$PACKAGE_NAME" />
</intent-filter>
</receiver>
</platform>
服務
<platform name="android">
<service
android:name="cn.com.ths.thstoast.MyService"
android:enabled="true"
android:exported="true" />
</platform>
內容提供者
<platform name="android">
<!-- 訪問其他應用的內容需要配置應用讀寫權限 -->
<uses-permission android:name="android.permission.READ_CALENDAR"/>
<uses-permission android:name="android.permission.WRITE_CALENDAR"/>
<!-- 如果不是上面Calendar這種系統provider(android.provider.*),則需要註冊 -->
<provider
android:name="org.apache.cordova.provider.TestContentProvider"
android:authorities="org.apache.cordova.provider.testprovider"
android:exported="false" />
</platform>
jar+aar+so配置
jar配置
<platform name="android">
<lib-file src="src/android/libs/jpush-android-3.0.1.jar" />
</platform>
so配置
so 路徑
so是在NDK平台開發的,NDK是用來給安卓手機開發軟件用的,但是和SDK不同的是它用的是C語言,而SDK用的是Java語言。NDK開發的軟件在安卓的環境裏是直接運行的,一般只能在特定的CPU指令集的機器上運行。
so配置通常配置在libs目錄下
so plugin.xml配置,注意輸出路徑子目錄也要改
<source-file src="src/android/libs/armeabi/libjcore110.so" target-dir="libs/armeabi" />
<source-file src="src/android/libs/armeabi-v7a/libjcore110.so" target-dir="libs/armeabi-v7a" />
<source-file src="src/android/libs/arm64-v8a/libjcore110.so" target-dir="libs/arm64-v8a" />
<source-file src="src/android/libs/x86/libjcore110.so" target-dir="libs/x86" />
<source-file src="src/android/libs/x86_64/libjcore110.so" target-dir="libs/x86_64" />
</source-file>
aar配置
aar文件配置
aar和jar類似,但是他包含了所有資源,class以及res資源文件,aar和gradle通常放在libs下
gradle配置
gradle中要在repositories中配置flatDir,dependencies中配置compile的aar包
repositories{
jcenter()
flatDir{
dirs 'libs'
}
}
dependencies {
compile 'com.android.support:appcompat-v7:23.1.0'
compile(name:'ijkplayer-java-debug', ext:'aar')
compile(name:'giraffeplayer-debug', ext:'aar')
}
aar plugin.xml
<platform name="android">
<framework src="src/android/libs/giraffeplayer-build.gradle" custom="true" type="gradleReference" />
<resource-file src="src/android/libs/giraffeplayer-debug.aar" target="libs/giraffeplayer-debug.aar" />
<resource-file src="src/android/libs/ijkplayer-java-debug.aar" target="libs/ijkplayer-java-debug.aar" />
</platform>
靜態資源和java文件
靜態資源路徑
靜態資源規定放在src/android/res目錄下
靜態資源輸出目錄配置 通過resource-file和source-file配置當前路徑和輸出路徑,靜態資源默認路徑是src/android/res/xxx, 輸出路徑是res/xxx
<platform name="android">
<source-file src="src/android/res/drawable-hdpi/jpush_richpush_btn_selector.xml" target-dir="res/drawable" />
<source-file src="src/android/res/drawable-hdpi/jpush_richpush_progressbar.xml" target-dir="res/drawable" />
<source-file src="src/android/res/drawable-hdpi/jpush_ic_richpush_actionbar_back.png" target-dir="res/drawable-hdpi" />
<source-file src="src/android/res/drawable-hdpi/jpush_ic_richpush_actionbar_divider.png" target-dir="res/drawable-hdpi" />
<source-file src="src/android/res/layout/jpush_popwin_layout.xml" target-dir="res/layout" />
<source-file src="src/android/res/layout/jpush_webview_layout.xml" target-dir="res/layout" />
<source-file src="src/android/res/layout/test_notification_layout.xml" target-dir="res/layout" />
<source-file src="src/android/res/values/jpush_style.xml" target-dir="res/values" />
</platform>
java文件路徑
java文件通常放在src/android目錄下
java文件輸出目錄配置 默認路徑是src/android/Xxx.java 輸出目錄是src/包/名/字/,注意target-dir是目錄路徑,target才是文件路徑。
<platform name="android">
<source-file src="src/android/MyReceiver.java" target-dir="src/cn/jpush/phonegap" />
<source-file src="src/android/JPushPlugin.java" target-dir="src/cn/jpush/phonegap" />
</platform>
meta-data
拿一個分享插件舉例做示範
plugin.xml:配置preference,用於接收用户傳參variable的值,config-file中配置meta-data, 保存參數鍵值信息用於給java類調用。
<preference name="WEIXIN_APP_ID" />
<platform name="android">
<preference name="WEIXIN_APP_ID" value="WEIXIN_APP_ID" />
<!-- 友盟 AK -->
<meta-data
android:name="WEIXIN_APP_ID"
android:value="WEIXIN_APP_ID" >
</meta-data>
</platform>
權限
當需要使用系統的某個功能時,一定要加上權限詢問配置,所有的權限在這查看
<platform name="android">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_LOCATION_EXTRA_COMMANDS" />
</platform>
l 開發進階之插件實現
開啓活動
簡單來説,活動相當於angular的page,vue的vue,是一個可包含組件(fragment)的ui頁面。
開啓普通活動
// 應用上下文
Context context = cordova.getActivity().getApplicationContext();
String pkgName = context.getPackageName();
// 打開app應用
Intent intent = context
.getPackageManager()
.getLaunchIntentForPackage(pkgName);
// 打開XxxActivity
// Intent intent=new Intent(cordova.getActivity(), XxxActivity.class);
// 打開應用必須要加 CATEGORY_LAUNCHER
intent.addCategory(Intent.CATEGORY_LAUNCHER);
intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_SINGLE_TOP);
// 啓動應用
context.startActivity(intent);
// 啓動活動
// cordova.getActivity().startActivity(intent);
// 啓動有返回值的活動
// cordova.startActivityForResult((CordovaPlugin) this, intent, 0);
本插件中開啓活動代碼
public class ThsToast extends CordovaPlugin {
private static final String TAG = "ThsToast";
@Override
public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
Log.d(TAG, "start execute!");
// 啓動活動
Intent intent = new Intent(cordova.getActivity(), MyActivity.class);
cordova.getActivity().startActivity(intent);
}
}
啓動活動演示:
打開第三方Android SDK活動 如:百度地圖uri
// 如果有百度地圖 uri詳情:http://lbsyun.baidu.com/index.php?title=uri/api/android
Intent intent = Intent.parseUri("intent://map/direction?"
+ "origin="+options.getOrigin4Baidu()
+ "&destination="+options.getDestination4Baidu()
+ "&mode="+options.getModel4Baidu()
+ "&coord_type=wgs84&referer=Autohome|GasStation#Intent;scheme=bdapp;package=com.baidu.BaiduMap;end",0);
cordova.getActivity().startActivity(intent);
使用廣播
廣播其實就是一個在app範圍內的事件推送和接受中心,類似於iframe的postMessage。
在cordova項目中使用和原生廣播沒有區別,一般靜態廣播用在插件比較多,如果是動態廣播,則需要在activity中通過registerReceiver註冊
public class ThsToast extends CordovaPlugin {
private static final String TAG = "ThsToast";
@Override
public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
Log.d(TAG, "start execute!");
// 動態註冊廣播:
MyBroadcastReceiver myReceiver = new MyBroadcastReceiver();
IntentFilter itFilter = new IntentFilter();
itFilter.addAction("android.intent.action.AIRPLANE_MODE");
cordova.getContext().registerReceiver(myReceiver, itFilter);
}
}
android/MyBroadcastReceiver.java
public class MyBroadcastReceiver extends BroadcastReceiver {
private String ACTION_BOOT = "android.intent.action.AIRPLANE_MODE";
@Override
public void onReceive(Context context, Intent intent) {
String action = intent.getAction();
if (ACTION_BOOT.equals(action)) {
Toast.makeText(context, "切換飛行模式!", Toast.LENGTH_SHORT).show();
}
}
}
廣播效果演示:
使用服務
服務可以同步或執行一些小任務、小進程,甚至對其他進程的ui頁面做操作,可類比angular的service服務。
和原生Service一樣的用法
public class ThsToast extends CordovaPlugin {
private static final String TAG = "ThsToast";
@Override
public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
Log.d(TAG, "start execute!");
// 啓動服務
cordova.getContext().startService(new Intent(cordova.getActivity(), MyService.class));
}
}
使用內容提供者
內容提供者其實是一個手機系統範圍的API調度中心,比如可以讀取和修改通訊錄和相冊的內容。
使用jar+aar+so
使用jar
jar包可以理解為api的集合,解壓後全部是編譯好的class,但是不包含資源文件,可以直接使用使用其中的類。
jar包路徑通常位於libs目錄下
查看依賴的api源文件
使用so
通常在jar中使用
使用aar
例如跳轉activity
使用meta-data
保存用户添加插件時傳入的參數鍵值對象
meta-data 在java中獲取參數對象
Plugin.java:通過cordova.getActivity().getPackageManager().getApplicationInfo(cordova.getActivity().getPackageName(), PackageManager.GET_META_DATA)獲取參數存儲的對象appInfo,再通過appInfo.metaData.getType(key)取得參數value,getType有getString、getInt……
meta-data 如何傳參
傳入插件參數有兩種辦法,
1.用cordova 安裝時利用--variable key=value 傳入
cordova plugin add cordova-plugin-share --variable WEIXIN_APP_ID=xxx --variable WEIXIN_APP_SECRET=xxx
2.添加插件完成後,在項目的config.xml中手動添加,cordova build後生效
<plugin name="cordova-plugin-share" spec="1.0.0">
<variable name="WEIXIN_APP_ID" value="xxx" />
<!--...-->
</plugin>
使用權限
import android.Manifest;
public static final String WRITE = Manifest.permission.WRITE_EXTERNAL_STORAGE;
public static final String READ = Manifest.permission.READ_EXTERNAL_STORAGE;
public static final int REQ_CODE = 0;
@Override
public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
if (action.equals("show")) {
this.args = args;
this.callbackContext = callbackContext;
if (cordova.hasPermission(READ) && cordova.hasPermission(WRITE)) {
// 有權限則跳轉活動
this.launchActivity();
} else {
// 若沒有權限則請求
this.getPermission();
}
return true;
}
return false;
}
/**
* 請求權限
**/
protected void getPermission() {
cordova.requestPermissions(this, REQ_CODE, new String[]{WRITE, READ});
}
@Override
public void onRequestPermissionResult(int requestCode, String[] permissions,
int[] grantResults) throws JSONException {
for (int r : grantResults) {
if (r == PackageManager.PERMISSION_DENIED) {
this.callbackContext.sendPluginResult(new PluginResult(PluginResult.Status.ERROR, PERMISSION_DENIED_ERROR));
return;
}
}
switch (requestCode) {
case REQ_CODE:
launchActivity();
break;
}
}
使用生命週期和常用鈎子
excute:執行插件方法
調用插件執行方法。第一個參數action是調用的方法名,第二個參數args是傳入的參數數組,第三個參數CallbackContext是傳入的回調函數上下文,可以通過callbackContext.success(message)和callbackContext.error(errorMessage)傳入回調參數;
@Override
public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
}
initialize:初始化
在插件構造函數執行和字段初始化之後調用,此時尚未執行excute方法。
@Override
public void initialize (CordovaInterface cordova, CordovaWebView webView) {}
pluginInitialize:無參初始化
在插件構造函數執行和字段初始化之後調用,沒有參數,此時尚未執行excute方法,pluginInitialize 不支持 cordova 3.0-3.5 。
@Override
protected void pluginInitialize() {}
插件初始化到執行的過程執行順序如下,依次是initialize、pluginInitialize、execute:
2020-09-03 00:20:34.928 19307-19435/com.ths.exam.lilin D/ThsToast: start initialize!
2020-09-03 00:20:34.928 19307-19435/com.ths.exam.lilin D/ThsToast: start pluginInitialize!
2020-09-03 00:20:34.929 19307-19435/com.ths.exam.lilin D/ThsToast: start execute!
onStart:活動開始週期
活動正在被啓動,已經可見,但是還沒位於前台。
@Override
public void onStart() {}
onResume:活動恢復週期
活動位於前台,並且可以與用户交互了。
/**
* 當活動將開始與用户互動時調用。
*
* @param multitasking 表示是否為應用程序打開了多任務
*/
@Override
public void onResume(boolean multitasking) {
super.onResume(multitasking);
// deviceready();
}
onPause:活動暫停週期
活動處於正在停止的狀態,通常當要離開這活動的時候會被調用。接下去onStop()馬上會被調用,如果是彈出一個對話框,那麼onStop不會被調用。
/**
* 在系統即將開始恢復上一個活動時調用
*
* @param multitasking 表示是否為應用程序打開了多任務
*/
@Override
public void onPause(boolean multitasking) {
super.onPause(multitasking);
}
onStop:活動停止週期
活動即將停止,活動完全不可見。
/**
* 活動停止前調用
*/
@Override
public void onStop() {
super.onStop();
}
onReset:活動重置週期
這個方法表示活動正在重新啓動,活動由停止狀態恢復為運行狀態,通常由上一個活動返回到這個活動時,這個活動會調用此方法。
/**
* 當視圖導航時調用
*/
@Override
public void onReset() {}
onActivityResult:返回活動數據
當從另一個活動返回到當前活動時,當前活動中的onActivityResult可接收剛才活動的返回數據。
@Override
public void onActivityResult(int requestCode, int resultCode, Intent intent) {
super.onActivityResult(requestCode, resultCode, intent);
}
onDestroy:活動銷燬週期
活動完全銷燬前調用,可以在這做一些資源釋放的操作。
/**
* 活動銷燬前調用
*/
@Override
public void onDestroy() {
// deviceready = false;
}
l 總結
本文從創建一個簡單的cordova自定義插件,到四大組件的配置和使用,以及如何導入和使用jar、aar、so、靜態資源方面做了詳細講解,最後歸納了常用的生命週期和回調方法。
看到這,我們應該已經具備獨立創建和改寫插件的基本能力,剩下的就只有自己多看多用cordova-plugin,實踐出真知,若有總結不到位或者遺漏的地方,還請各位朋友多多指出,共同交流完善!如果這篇文章對前端或其他方向的你有所幫助或者啓發,記得點個贊哦親:)
l 下載文中演示的插件
cordova plugin add cordova-plugin-ths-toast