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

指定插件的名称

<name>Foo</name>

describe

指定该插件的描述

<description>Foo plugin description</description>

author

指定作者的名称

<author>Foo plugin author</author>

keywords

包含逗号分隔的关键字描述插件

<keywords>foo,bar</keywords>

license

指定插件的许可证

<license>Apache 2.0 License</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" />

• 也可以用asset复制文件到指定目录

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的命名空间

  • 示例：

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

• 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的键和值。已过时
示例：

<plugins-plist key="Foo" string="CDVFoo" />

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-android@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)	必须。指定发生特定操作时要调用的脚本的位置

示例：

<hook type="after_plugin_install" src="scripts/afterPluginInstall.js" />

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>