plugin.xml文件是在plugins命名空间(http://apache.org/cordova/ns/plugins/1.0)下面的xml文档。它包含一个定义插件的顶层 plugin 元素及定义插件结构的子元素。
一个插件元素示例:
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
xmlns:android="http://schemas.android.com/apk/res/android"
id="com.alunny.foo"
version="1.0.2">
plugin 元素
plugin元素是插件元数据的底层元素,它有下面的特性:
- xmlns(必须的):插件命名空间,http://apache.org/cordova/ns/plugins/1.0。如果文档有其他的命名空间,这些命名空间也应该包含在该元素里面。
- id(必须):插件的全路径,如:com.alunny.foo;
- version(必须):插件的版本,使用major.minor.patch的模式,正则表达式为:
^\d+[.]\d+[.]\d+$
engines和engine元素
engines的子元素指明了插件支持的基于Cordova框架的版本,如:
<engines>
<engine name="cordova" version="1.7.0" />
<engine name="cordova" version="1.8.1" />
<engine name="worklight" version="1.0.0" platform="android" scriptSrc="worklight_version"/>
</engines>
跟plugin的version特性相似,version也是有major.minor.patch组成
engine元素也可以使用模糊匹配去避免平台升级的时候带来的代码维护,可以使用> >= <和<=进行指明,如:
<engines>
<engine name="cordova" version=">=1.7.0" />
<engine name="cordova" version="<1.8.1" />
</engines>
engine默认是支持Cordova支持的所有平台,你也可以使用cordova指明版本号,也可以同时指定特定平台的特定版本号,如下:
<engines>
<engine name="cordova" version=">=1.7.0" />
<engine name="cordova-android" version=">=1.8.0" />
<engine name="cordova-ios" version=">=1.7.1" />
</engines>
这里列出了engine标签支持的:
* 'cordova'
* 'cordova-plugman'
* 'cordova-amazon-fireos'
* 'cordova-android'
* 'cordova-ios'
* 'cordova-blackberry10'
* 'cordova-wp7'
* 'cordova-wp8'
* 'cordova-windows8'
* 'android-sdk' // 返回安装的Android API的最高级别
* 'apple-xcode' // 返回xcode的版本号
* 'apple-ios' // 返回安装的ios的版本号
* 'apple-osx' // 返回osx的版本号
* 'blackberry-ndk' // 返回本地安装的blackberry sdk的版本号
如果要指明一个基于Cordova框架的自定义框架,必须像下面一样制定:
<engines>
<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>
一个自定义框架的engine元素必须包含下面的特性:name、version、scriptSrc和platform。
- name(必须):自定义框架的名字
- version(必须):自定义框架的版本
- scriptSrc(必须):自定义框架的代码文件
- platform(必须):框架支持的平台
如果没有engine元素指定,plugman会试着安装到项目的特定目录里面。
name元素
插件的名称,如:
<name>Foo</name>
name元素不需要本地化
description元素
插件描述,如:
<description>Foo plugin description</description>
该元素也不需要处理本地化
author元素
插件的作者,如:
<author>程序海洋的一叶小舟</author>
keywords元素
插件关键字,使用“,”分隔,如:
<keywords>foo,bar</keywords>
license元素
插件的许可,如:
<license>Apache 2.0 License</license>
asset元素
一个或者多个元素标明需要复制到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元素都必须包含src和target特性,基于web的插件包含许多asset元素。任何asset元素都是嵌套在平台platform内指定特定平台的web资产,特性包含:
- src(必须):插件的文件或者目录地址,相对plugin.xml路径。如果在特定位置找不到src指定的文件或者路径,plugman会终止并回滚安装进程,并通知用户
- target(必须):该文件或者目录怎么放到应用程序里面,相对于www路径。
js-module元素
许多插件包含一个或者多个javascript文件,每一个js-module元素对应一个javascript文件,并且防止插件使用者为每一个文件增加一个script标签。asset元素只是简单地从插件子目录拷贝文件到www目录,js-module更加复杂,如下所示:
<js-module src="socket.js" name="Socket">
<clobbers target="chrome.socket" />
</js-module>
当安装一个像上面所示的插件时,socket.js被复制到
www/plugins/my.plugin.id/socket.js,并且增加了一个 www/cordova_plugins.js 的入口。加载的时候,在cordova.js里面的代码使用xhr去读取每一个文件并使用script便签将它们注入到html页面中。它增加了一个映射,以适当的方式去(clobber)或者合并。
不要使用cordova.define去包围文件,它会自动添加。模块封装在一个带有module、exports和require的闭包里面,作为一个标准的AMD模块。
js-module详细描述:
- src引用一个相对于plugin文件的插件目录
- name是模块名称的最后一部分
- js-module中有三个标签是允许的
- <clobber target="some.value"/> 指明的是module.exports 会作为window.some.value 插入到 window对象中。只要你喜欢,你可以有很多<clobber>,但是windows不会创建任何对象
- <merges target="some.value"/> 指明了那个模块可以被组合进一个存在的 window.some.value里面,如果存在,则module的版本会被原始的版本号重写。只要你喜欢,你可以有很多<merges>,但是windows不会创建任何对象
- <runs/> 以为着你的代码需要用 cordova.require进行指定,但是它不会安装在window对象上面,当初始化带有事件处理或其他东西的时候是有用的
- 一个空的<js-module>依然会被加载,而且在其他模块中可以通过cordova.require进行引用
如果src不能够解析为一个文件地址,plugman会停止加载并回滚安装,发出问题的通知并以非0代码退出
嵌套在platform里面的<js-module>元素定义了平台特定的javascript模块绑定。
dependency 元素
dependency元素允许你指定当前插件依赖的插件。虽然未来的版本可能在插件库中就直接访问他们,但是暂时需要使用dependency标签通过url进行引用。像下面这样:
<dependency id="com.plugin.id" url="https://github.com/myuser/someplugin" commit="428931ada3891801" subdir="some/path/here" />
- id:插件ID,它需要全局唯一的;
- url:插件地址。是一个能够拷贝的代码库;
- commit:他是git checkout的一个引用:一个分支或者一个标签名称(比如:master,0.3.1),或者一个提交的hash码(如:975ddb228af811dd8bb37ed1dfd092a3d05295f9);
- subdir:目标插件在代码库中的子目录。它允许代码库包含几个关联的插件的时候是相当有用的。
未来,版本限制将出台,到时候就可以直接使用名字而不是显示的URL来进行抓取了。
相对依赖路径
如果你设置了dependency标签的url特性为“."开始并且提供了一个subdir特性,依赖插件将会被安装在父插件相同的目录或者代码库里面。
注意:subdir总是指明的是相对于git代码库根目录的目录,而不是父插件的目录,即使你安装一个本地路径的插件都是这样。plugman在git代码库的根目录寻找并发现其他的插件。
platform元素
platform指明了需要关联的本地代码或者需要修改它们配置文件的平台,使用标准的工具可以标识支持的平台并且安装代码到cordova项目里面。
没有platform标签的plugins假定是仅仅用于javascript,并且通用于所有的平台;
一个简单platform标签例子:
<platform name="android">
<!-- android-specific elements -->
</platform>
<platform name="ios">
<!-- ios-specific elements -->
</platform>
name特性是必须的,它指明了与它关联的子元素支持的平台。
平台名称必须是小写的,平台列表如下:
- amazon-fireos
- android
- bb10
- ios
- wp7
- wp8
source-file 元素
source-file元素标明了安装到项目中的可执行代码,如:
<!-- 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" />
它支持下面的特性:
- src(必须):相对于config.xml文件的路径
- target-dir:拷贝的项目中的相对路径
- framework(仅IOS):如果设置为true,需要增加特定的文件到框架里面
- compiler-flags(仅IOS):如果设置,分派特定的编译标识给特定的源文件
config-file元素
标识一个配置文件需要在什么地方修改以及怎样修改的一个配置。plist及xml两种文件类型测试可以修改这些元素;
config-file仅仅允许你去增加一个新的子元素到xml文档树。xml子元素插入到目标xml文档树中;
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>
它支持下面的特性:
- target:被修改的文件,该路径是相对于项目根目录的路径。target中可以包含通配符(*),这种情况下,plugman会按项目目录结构递归搜索,并使用第一个匹配的结果;在IOS中,相对于项目根目录的配置文件路径是不可知的,所以标明一个关联cordova-ios-project/MyAppName/config.xml的目录文件config.xml;
- parent:一个xpath路径,指明需要添加到的父元素的位置,如果使用绝对选择器,你可以使用通配符(*)去标识根元素;对于plist来说,parent元素指定了被插入的xml;如果选择器不能解析为一个特定的文档路径,工具将会停止并回滚安装进程,并报告错误同时以非零代码结束;
plugins-plist元素
这是一个过期元素,如下:
<config-file target="config.xml" parent="/widget/plugins">
<feature name="ChildBrowser">
<param name="ios-package" value="ChildBrowserCommand"/>
</feature>
</config-file>
<plugins-plist key="Foo" string="CDVFoo" />
resource-file和header-file元素
像source file一样,标识不同的平台上面使用的不同的源文件、头或者资源,如:
<resource-file src="CDVFoo.bundle" />
<resource-file src="CDVFooViewController.xib" />
<header-file src="CDVFoo.h" />
lib-file元素
像source、resource和头文件一样,但是它是标识像blackberry那样使用用户产生的库文件的。如:
<lib-file src="src/BlackBerry10/native/device/libfoo.so" arch="device" />
<lib-file src="src/BlackBerry10/native/simulator/libfoo.so" arch="simulator" />
framework元素
指明插件以来的框架(通常是在OS/Platform下),如:
<framework src="libsqlite3.dylib" />
<framework src="social.framework" weak="true" />
src特性标识需要增加到项目中的对于给定平台的正确形式的框架;
可选的weak选项标明框架是否使用弱引用,默认为false;
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 your `local.properties`
android.library.reference.1=PATH_TO_ANDROID_SDK/sdk/extras/google/google_play_services/libproject/google-play-services_lib
</info>
变量
在某些情况下,一个插件需要根据目标平台对配置文件进行更改;比如,为了在Android上面注册C2DM(包ID为com.alunny.message)它需要如下面的权限:
<uses-permission
android:name="com.alunny.message.permission.C2D_MESSAGE"/>
在这种情况下面,插入plugin.xml文件的内容提前是不知道的。这个时候就需要使用到变量的概念,变量是以美元符号($)开头的,后接一系列大写字母、数字及下划线。对于上面的例子,plugin.xml中为包含下面的标签:
<uses-permission
android:name="$PACKAGE_NAME.permission.C2D_MESSAGE"/>
plugman会使用特定的值代替变量,如果没有找到则使用一个空的字符串代替;可以被检测的参数值(这个时候由AndroidManifest.xml提供)或由工具提供;该过程依赖于特定的工具;
plugman可以要求用户指定插件需要的变量值,如:对于C2M的API_KEY和google地图可以使用下面的命令号标识:
plugman --platform android --project /path/to/project --plugin name|git-url|path --variable API_KEY=!@CFATGWE%^WGSFDGSDFW$%^#$%YTHGsdfhsfhyer56734
为了强制使用标量,在platform标签下需要包含一个<preference>标签,如:
<preference name="API_KEY" />
plugman会检测需要的参数,如果没有则会提醒用户输入并以非零方式退出;
某些变量名应该保留,如下面列表所示。
$PACKAGE_NAME
反向域风格的包的唯一标识符,在iOS对应于CFBundleIdentifier或在AndroidManifest.xml文件中的顶级manifest元素的package属性。