属于web程序顶级目录的config.xml全局配置文件可以控制应用程序许多方面的行为。该文件是平台无关的,基于 W3C'sPackaged Web Apps (Widgets)标准,被扩展支持Cordova API、插件和平台相关的设置。
通过Cordova CLI创建的项目,可以在www目录里面找到该文件:
app/www/config.xml
当使用CLI去编译程序的时候,该文件会被复制到不同平台下面的www子目录里面去,比如:
app/platforms/ios/www/config.xml
app/platforms/blackberry10/www/config.xml
如果你使用CLI创建的项目,但是接下来你使用SDK的方式进行开发,你需要进行下面中的某一步去为IOS或者Android设置源文件。
app/platforms/android/res/www/config.xml
app/platforms/ios/<APP_NAME>/config.xml
该部分主要描述全局的和交叉平台的配置选项,需要了解特定平台的配置选项,可以阅读下面的章节:
除了下面描述的各种选项外,你还可以为不同的平台配置不一样的核心图片集,更加详细的信息参考
Icons and Splash Screens。
核心配置元素
下面这个例子展示了通过CLI的create命令产生的默认config.xml文件:
<widget id="com.example.testtwo" version="1.0.0" xmlns="http://www.w3.org/ns/widgets" xmlns:gap="http://phonegap.com/ns/1.0">
<name>TestTwo</name>
<description>
Hello World sample application that responds to the deviceready event.
</description>
<author email="support@phonegap.com" href="http://phonegap.com">
PhoneGap Team
</author>
<content src="index.html" />
<feature name="http://api.phonegap.com/1.0/device" />
<preference name="permissions" value="none" />
<preference name="orientation" value="default" />
<preference name="target-device" value="universal" />
<preference name="fullscreen" value="true" />
<preference name="webviewbounce" value="true" />
<preference name="prerendered-icon" value="true" />
<preference name="stay-in-webview" value="false" />
<preference name="ios-statusbarstyle" value="black-opaque" />
<preference name="detect-data-types" value="true" />
<preference name="exit-on-suspend" value="false" />
<preference name="show-splash-screen-spinner" value="true" />
<preference name="auto-hide-splash-screen" value="true" />
<preference name="disable-cursor" value="false" />
<preference name="android-minSdkVersion" value="7" />
<preference name="android-installLocation" value="auto" />
<icon src="icon.png" />
<icon gap:density="ldpi" gap:platform="android" src="res/icon/android/icon-36-ldpi.png" />
<icon gap:density="mdpi" gap:platform="android" src="res/icon/android/icon-48-mdpi.png" />
<icon gap:density="hdpi" gap:platform="android" src="res/icon/android/icon-72-hdpi.png" />
<icon gap:density="xhdpi" gap:platform="android" src="res/icon/android/icon-96-xhdpi.png" />
<icon gap:platform="blackberry" src="res/icon/blackberry/icon-80.png" />
<icon gap:platform="blackberry" gap:state="hover" src="res/icon/blackberry/icon-80.png" />
<icon gap:platform="ios" height="57" src="res/icon/ios/icon-57.png" width="57" />
<icon gap:platform="ios" height="72" src="res/icon/ios/icon-72.png" width="72" />
<icon gap:platform="ios" height="114" src="res/icon/ios/icon-57-2x.png" width="114" />
<icon gap:platform="ios" height="144" src="res/icon/ios/icon-72-2x.png" width="144" />
<icon gap:platform="webos" src="res/icon/webos/icon-64.png" />
<icon gap:platform="winphone" src="res/icon/windows-phone/icon-48.png" />
<icon gap:platform="winphone" gap:role="background" src="res/icon/windows-phone/icon-173.png" />
<gap:splash gap:density="ldpi" gap:platform="android" src="res/screen/android/screen-ldpi-portrait.png" />
<gap:splash gap:density="mdpi" gap:platform="android" src="res/screen/android/screen-mdpi-portrait.png" />
<gap:splash gap:density="hdpi" gap:platform="android" src="res/screen/android/screen-hdpi-portrait.png" />
<gap:splash gap:density="xhdpi" gap:platform="android" src="res/screen/android/screen-xhdpi-portrait.png" />
<gap:splash gap:platform="blackberry" src="res/screen/blackberry/screen-225.png" />
<gap:splash gap:platform="ios" height="480" src="res/screen/ios/screen-iphone-portrait.png" width="320" />
<gap:splash gap:platform="ios" height="960" src="res/screen/ios/screen-iphone-portrait-2x.png" width="640" />
<gap:splash gap:platform="ios" height="1024" src="res/screen/ios/screen-ipad-portrait.png" width="768" />
<gap:splash gap:platform="ios" height="768" src="res/screen/ios/screen-ipad-landscape.png" width="1024" />
<gap:splash gap:platform="winphone" src="res/screen/windows-phone/screen-portrait.jpg" />
<access origin="http://127.0.0.1*" />
</widget
下面的元素出现在config.xml的顶级元素中,他们被cordova支持的所有平台支持:
- <widget>的id属性提供了应用程序的域标识,version标识版本号,是通过major/minor/patch得到
- <name>标识了应用程序的名称,它出现在设备的home页面及app store里面
- <description>和<author>元素标识了app的简介信息,可能出现在appstore的软件介绍里面
- <content>,可选元素,它指示了开始页面的路径,默认为index.html
- <access>元素集标明了应用程序可以访问的外部域有哪些,默认值只允许访问本地电脑
- <preference>标签集包含了各种不同的name/value选项,name是不区分大小写的。
全局Preference
下面的全局Preference应用于所有平台:
- FullScreen允许隐藏屏幕上方的状态栏,默认值为false
<preference name="Fullscreen" value="true" />
- Orientation允许你锁定方向,防止界面旋转,可能的值为
default
,landscape
, 或者portrait。比如:
<preference name="Orientation" value="landscape" />
多个平台的Preference
下面的Preference可以引用于多个平台,但是不能应用于所有平台:
- DisallowOverscroll(boolean,false):在用户滚动过程中,当你不想要显示任何反馈,可以将该值设置为true
Android和IOS<preference name="DisallowOverscroll" value="true"/>
- BackgroundColor:设置背景颜色,支持32位色彩,首字节代表alpha通道,其他代表RGB通道
可用于Android和BlackBerry,通过重写CSS可以用于所有平台,如:body{background-color:blue;}<preference name="BackgroundColor" value="0xff0000ff"/>
- HideKeyboardFormAccessoryBar(boolean,false):在下面键盘出现是,需要隐藏工具栏,从而帮助用户从一个form转到另一个form的时候,可以将该值设置为true。
应用于IOS和BlackBerry<preference name="HideKeyboardFormAccessoryBar" value="true"/>
feature元素
如果你使用CLI去编译项目,你可以使用
plugin命令启用设备API,但是它不会修改顶层的config.xml文件,因此,feature不会应用到工作流中。如果你工作在SDK目录下,并且使用特定平台的config.xml,你可以使用feature去启用设备API和额外的插件,它经典的使用方法如下:
<feature name="Plugin" value="PluginID" />
他们通常以自定义值出现在平台特定的config.xml文件中。比如,这儿有一个为android项目指明设备API的例子:
<feature name="Device">
<param name="android-package" value="org.apache.cordova.device.Device" />
</feature>
为IOS项目的例子:
<feature name="Device">
<param name="ios-package" value="CDVDevice" />
</feature>