cordova 自定義插件plugin.xml配置知識點

plugin.xml

plugin

插件清單的頂級元素

屬性	描述
xmlns(string)	必須。插件名稱空間http://apache.org/cordova/ns/plugins/1.0。如果包含其他命名空間的xml，也應包含在元素中
id(string)	必須。插件的npm樣式辨別符
version(string)	必須。插件的版本号。

示例：

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
    xmlns:android="http://schemas.android.com/apk/res/android"
    id="my-plugin-id"
    version="1.0.2">

engines and engine

指定此插件支援的基于Apache Cordova的架構的版本

屬性	描述
name(string)	必須。預設架構：cordova
version(string)	必須。架構必須具有的版本才能安裝
scriptSrc(string)	必須。僅用于定制架構，告訴插件人員定制架構的腳本
platform(string)	必須。僅對于自定義架構，架構支援的平台

示例：

<engines>
  <engine name="cordova-android" version="=1.8.0" />
    <engine name="cordova" version=">=1.7.0" />
<engine name="my_custom_framework" version="1.0.0" platform="android" scriptSrc="path_to_my_custom_framework_version"/>
  <engine name="another_framework" version=">0.2.0" platform="ios|android" scriptSrc="path_to_another_framework_version"/>
  <engine name="even_more_framework" version=">=2.2.0" platform="*" scriptSrc="path_to_even_more_framework_version"/>
</engines>

name

指定插件的名稱

describe

指定該插件的描述

author

指定作者的名稱

keywords

包含逗号分隔的關鍵字描述插件

license

指定插件的許可證

asset

用于列出要複制到Cordova應用程式www目錄中的檔案或目錄，嵌套在中的任何元素都指定特性平台的web asset

屬性	描述
src(string)	必須。檔案或目錄位于插件包中相對于plugin.xml文檔的位置
target(string)	必須。檔案或目錄位于Cordova應用程式相對于www目錄的位置

示例：

<!-- a single file, to be copied in the root directory -->
<asset src="www/foo.js" target="foo.js" />
<!-- a directory, also to be copied in the root directory -->
<asset src="www/foo" target="foo" />

js-module

子產品被包裝在一個封閉的子產品中，子產品，輸出和範圍要求。

屬性	描述
src(string)	必須。相對于plugin.xml檔案應用插件目錄中的檔案。
name(string)	必須。提供子產品名稱的最後一部分

示例：

<js-module src="socket.js" name="Socket">
</js-module>

clobbers

用于指定windwo插入module.exports的對象下的名稱空間。

屬性描述

target(string) 必須。插入module.exports的命名空間
示例：

屬性	描述
target(string)	必須。插入module.exports的命名空間

<js-module src="socket.js" name="Socket">
  <clobbers target="chrome.socket" />
</js-module>
<!--module.exports被插入到window對象中window.chrome.socket-->

merges
- 用于window在module.exports與任何現有值合并的對象下指定名稱空間
  
  屬性描述
  
  target(string) 必須。module.exports合并到的名稱空間
- 示例：
```
<js-module src="socket.js" name="Socket">
  <merges target="chrome.socket" />
</js-module>
           
```

屬性	描述
target(string)	必須。module.exports合并到的名稱空間

runs

設定代碼應使用指定cordova.require,而不是安裝到window對象上
示例

<js-module src="socket.js" name="Socket">
  <runs/>
</js-module>

dependency

指定在其目前插件依賴其他插件

屬性	描述
id(string)	提供插件的id
url(string)	插件的URL，這裡應該引用CLI嘗試克隆git儲存庫
commit(string)	任何git參考
subdir(string)	指定目前插件依賴項作為git存儲庫的子目錄所在。始終指定相對于git資訊庫根目錄的路徑，而不是父插件
version(string)	取決于插件的版本号

示例：

<dependency id="cordova-plugin-someplugin" url="https://github.com/myuser/someplugin" commit="428931ada3891801" subdir="some/path/here" />
<dependency id="cordova-plugin-someplugin" version="1.0.1">

platform

辨別據有關聯的本機代碼或需要對其配置檔案進行修改的平台

屬性	描述
name(string)	必須。允許值：ios

示例：

<platform name="android">
  <!-- android-specific elements -->
</platform>

source-file

辨別應安裝到項目中的可執行源代碼

屬性	描述
src(string)	必須。檔案相對于plugin.xml的目錄路徑
target-dir(string)	相對于Cordova項目的根目錄，應将檔案複制到的目錄
framework(boolean)	預設false，将指定的檔案作為架構添加到項目中
compiler-flags(string)	為特定的源檔案配置設定指定的編譯器标志

示例：

<!-- android -->
<source-file src="src/android/Foo.java" target-dir="src/com/alunny/foo" />
<!-- ios -->
<source-file src="src/ios/CDVFoo.m" />
<source-file src="src/ios/someLib.a" framework="true" />
<source-file src="src/ios/someLib.a" compiler-flags="-fno-objc-arc" />

header-file

類似source-file,專門用于區分源檔案、标頭和資源的平台

屬性	描述
src(string)	必須。檔案相對于plugin.xml的路徑
target-dir(string)	相對于Cordova項目的根目錄，檔案複制到的目錄
type(string)	如果該值為BridgingHeader，則檔案導入其中，Bridging-Header.h并且可以從swift程式中調用。

示例：

對于iOS：

<header-file src="CDVFoo.h" />
<header-file src="CDVSomeHeader.h" type="BridgingHeader" />

resource-file

專門用于區分源檔案、标頭和資源的平台

屬性	描述
src(string)	必須。檔案相對于plugin.xml的路徑
target-dir(string)	相對于Cordova項目的根目錄，檔案複制到的目錄
arch(string)	允許值：X86、X64、ARM,僅在針對體系結構進行建構時才包括該檔案
device-target	允許值：win(windows)\phone\all,僅在針對指定目标裝置類型進行建構時包括該檔案
version	僅在為與指定版本字元串比對的版本進行建構時才包括該檔案
reference	應從src引用該檔案，而不是将其複制到目标位置

示例：

對于Android：

<resource-file src="FooPluginStrings.xml" target="res/values/FooPluginStrings.xml" />
對于Windows：

<resource-file src="src/windows/win81/MobServices.pri" target="win81\MobServices.pri" device-target="windows" versions="8.1" arch="x64"/>

<!-- Example of referencing  -->
<resource-file src="x86/foo.dll" target="foo.dll" arch="x86" reference="true" />
<resource-file src="x64/foo.dll" target="foo.dll" arch="x64" reference="true" />

edit-config

對xml元素的屬性進行修改，而不是将新的子項附加到xml文檔樹中

屬性	描述
file(string)	要修改的檔案以及相對于Cordova項目根目錄的路徑。目标可以包含通配符(*)元素
target(string)	Xpath選擇器，該選擇器引用目标元素以對其屬性修改。
model(string)	屬性修改模式類型。merge：如果元素已存在，替換，overwrite：用指定屬性替換目标元素中的所有屬性

file目錄不存在、target元素不存在都會不執行修改
示例：

<!-- plugin-1 -->
<edit-config file="AndroidManifest.xml" target="/manifest/uses-sdk" mode="merge">
    <uses-sdk android:minSdkVersion="16" android:maxSdkVersion="23" />
</edit-config>
<edit-config file="AndroidManifest.xml" target="/manifest/application/activity[@android:name='MainActivity']" mode="overwrite">
    <activity android:name="MainActivity" android:label="NewLabel" android:configChanges="orientation|keyboardHidden" />
</edit-config>

管理edit-config沖突
- 如果edit-cofnig有沖突或插件怪異，須先解決，要麼删除重新添加，要麼 --force強制添加，還原其他插件沖突修改

config-file

辨別要修改的基于XML的配置檔案，在該文檔中應進行的修改及應修改的内容。僅允許将新的子項附加到xml文檔樹中。

屬性	描述
target(string)	要修改的檔案以及相對于Cordova項目根目錄的路徑。目标可以包含通配符(*)元素
parent(string)	Xpath選擇器，引用要添加到配置檔案中的元素的父級。
after(string)	在可接受同級之後添加XML代碼片段
device-target(string)	允許值：win、phone、all
version(string)	當影響meta-name時适用package.appxmanifest，此屬性訓示特定Windows版本的應用程式清單應僅針對與指定版本字元串比對的版本進行更改。值可以是任何有效的節點語義版本範圍字元串。

例子：

對于XML：

<config-file target="AndroidManifest.xml" parent="/manifest/application">
    <activity android:name="com.foo.Foo" android:label="@string/app_name">
        <intent-filter>
        </intent-filter>
    </activity>
</config-file>
對于plist：

<config-file target="*-Info.plist" parent="CFBundleURLTypes">
    <array>
        <dict>
            <key>PackageName</key>
            <string>$PACKAGE_NAME</string>
        </dict>
    </array>
</config-file>
對于特定于Windows的屬性：

<config-file target="package.appxmanifest" parent="/Package/Capabilities" versions="&lt;8.1.0">
    <Capability Name="picturesLibrary" />
    <DeviceCapability Name="webcam" />
</config-file>
<config-file target="package.appxmanifest" parent="/Package/Capabilities" versions=">=8.1.0" device-target="phone">
    <DeviceCapability Name="webcam" />
</config-file>

plugin-list

指定要附加到IOS Cordova 項目中AppInfo.plist的鍵和值。已過時

示例：

lib-file

類似于源檔案、資源檔案和頭檔案，專門針對使用使用者生成的庫的平台

屬性	描述
src(string)	必須。檔案相對于plugin.xml的路徑
arch(string)	為其.so建立檔案的體系結構，device或simulator
device-target(string)	允許的值：win(windows)
version(string)	訓示僅在建構與指定版本字元串比對的版本時才應包含

示例：

<lib-file src="src/BlackBerry10/native/device/libfoo.so" arch="device" />
<lib-file src="src/BlackBerry10/native/simulator/libfoo.so" arch="simulator" />
對于Windows：

<lib-file src="Microsoft.WinJS.2.0, Version=1.0" arch="x86" />
<lib-file src="Microsoft.WinJS.2.0, Version=1.0" versions=">=8.1" />
<lib-file src="Microsoft.WinJS.2.0, Version=1.0" target="phone" />
<lib-file src="Microsoft.WinJS.2.0, Version=1.0" target="win" versions="8.0" arch="x86" />

framework

辨別插件所依賴的架構

屬性	描述
src(string)	必須。系統架構的名稱或該架構的相對路徑，該路徑包含在插件檔案中
custom(boolean)	訓示架構是否作為插件檔案的一部分包含在内
weak(boolean)	預設false。是否應用弱連接配接架構
type(string)	添加架構的類型
parent(string)	添加引用的子項目的目錄的相對路徑。
arch(string)	允許值：x86，x64或ARM。訓示僅在針對指定體系結構進行建構時才應包括該架構
device-target(string)	允許的值：win(windows)
version(string)	訓示僅在建構與指定版本字元串比對的版本時才應包含
target-dir(string)	架構複制到的子目錄
implementation(string)	相對路徑設定為.dll包含用C++編寫的WinMD元件實作的檔案
spec(string)	與配對type=“podspec”，這是您要安裝的CocoaPod的規格字元串（僅靜态庫
embed(boolean)	預設值：false。與配對custom=“true”，如果要将自定義架構嵌入到應用程式包中，則将其設定為true，以便可以在運作時動态加載（動态架構）

示例：

對于iOS：

<framework src="libsqlite3.dylib" />
<framework src="social.framework" weak="true" />
<framework src="relative/path/to/my.framework" custom="true" />
<framework src="GoogleCloudMessaging" type="podspec" spec="~> 1.2.0" />
在Android上（從cordova-[email protected]4.0.0開始），架構标簽用于包含Maven依賴項或包含捆綁的庫項目。

<!-- Depend on latest version of GCM from play services -->
<framework src="com.google.android.gms:play-services-gcm:+" />
<!-- Depend on v21 of appcompat-v7 support library -->
<framework src="com.android.support:appcompat-v7:21+" />
<!-- Depend on library project included in plugin -->
<framework src="relative/path/FeedbackLib" custom="true" />

hook

自定義腳本

屬性	描述
類型(string)	必須。指定将在其中調用自定義腳本的操作
src(string)	必須。指定發生特定操作時要調用的腳本的位置

示例：

preference

将各種選項設定為一對名稱/值屬性。名稱不區分大小寫。

平台特有首選項：

屬性	描述
AllowInlineMediaPlayback(boolean)	預設false。是否允許HTML5媒體播放使用浏覽器提供的控件而不是本機控件在螢幕布局中内聯顯示。将playsinline屬性添加到任何元素。注意：在iOS 10之前，元素需要改用webkit-playsinline屬性名稱。
AndroidLaunchMode(string)	預設是singleTop。值：standard、singleTop、singleTask、singleInstance。設定Activity啟動模式
android-maxSdkVersion(integer)	預設值未指定。設定AndroidMainifedt.xml中use-sdk标簽maxVersion屬性值
android-minSdkVersion(integer)	預設值取決于cordova-adnroid版本。設定AndroidMainifedt.xml中use-sdk标簽minSdkVersion屬性值
androrid-targetSdkVersion(integer)	預設值取決于cordova-android版本。設定AndroidMainifedt.xml中use-sdk标簽targetSdkVersion屬性值
BackGroundColor(string)	設定應用程式的背景色
BackupWebStorage(string)	預設值cloud。允許值：node、local、cloud。cloud：允許web存儲資料通過iCloud本分。local：允許通過iTunes同步進行本地備份。none：不允許備份

示例

<preference name="DisallowOverscroll" value="true"/>
<preference name="Fullscreen" value="true" />
<preference name="BackgroundColor" value="0xff0000ff"/>
<preference name="HideKeyboardFormAccessoryBar" value="true"/>
<preference name="Orientation" value="landscape" />

這裡隻列舉出幾個首選項，具體請參照官網。

info

提供給使用者的其他資訊。

示例：

<info>
You need to install __Google Play Services__ from the `Android Extras` section using the Android SDK manager (run `android`).

You need to add the following line to the `local.properties`:

android.library.reference.1=PATH_TO_ANDROID_SDK/sdk/extras/google/google_play_services/libproject/google-play-services_lib
</info>