PhoneGap 13 插件配置标准

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属性。

原文链接：Plugin Specification