tiapp.xml / timodule.xml 詳解

【官方Guide】[url=https://wiki.appcelerator.org/display/guides/tiapp.xml+and+timodule.xml+Reference]https://wiki.appcelerator.org/display/guides/tiapp.xml+and+timodule.xml+Reference[/url]

The tiapp.xml and it's close cousin the timodule.xml are XML configuration files that Titanium Mobile uses to generate native resources and code. Many of the configuration that lives in tiapp.xml is cross-platform, but some is platform-specific as well. The timodule.xml file is meant for custom Titanium Mobile Modules, and generally only contains platform-specific configuration.

[b]Top Level Elements[/b]

These configuration elements live under the root <ti:app> tag of the tiapp.xml. Unless otherwise noted, the configuration value goes inside the tag's content, i.e. <element>VALUE</element>

[list]

[*]<id>: The application ID. In Android, this ID is used to generate the package ID of the application, which must follow Java Package Naming Standards

[*]<name>: The application name. This is generally what is shown under the application icon on the end-user's mobile device.

[*]<version>: The application version.

[*]<publisher>: The publisher of this application.

[*]<url>: The url of this application.

[*]<description>: The description of this application.

[*]<copyright>: The copyright of this application.

[*]<icon>: The application icon's filename. This file should be relative to the application's Resources directory, or alternatively, can also live under a platform-specific folder, i.e. Resources/iphone or Resources/android.

[*]<persistent-wifi>: iOS only.

[*]<prerendered-icon>: iOS only.

[*]<statusbar-style>: iOS only, style for the status bar

[*]<statusbar-hidden>: iOS only, Whether or not the status bar is hidden when the application starts.

[*]<fullscreen>: Whether or not the application will start by taking up the entire screen.

[*]<navbar-hidden>: Whether or not the navigation bar is hidden for this application

[*]<analytics>: Whether or not to automatically collect analytics for this application.

[*]<guid>: A unique ID that associates this application for use in analytics

[/list]

[b]Application properties[/b]

tiapp.xml also supports ad-hoc properties that can be used by the application with Titanium.App.Properties. Properties generally follow the form:

[list]

[*]name is the property name

[*]type is the property value's type, valid values are: string, bool, int, double

[*]value is the property's value

[/list]

Properties are also used in specific cases by each platform, which is further explained in each platform section.

[b]iPhone / iOS specific section[/b]

Under the top <ti:app> element, you may optionally have an <iphone> element that contains iPhone and iOS specific configuration.

[list]

[*]<orientations device="device">: Restricts the device to these orientations when the application is running. The value of "device" can be "iphone", or "ipad"

[*]<orientation>: An orientation for this <orientations> list, valid values are: Ti.UI.PORTRAIT, Ti.UI.UPSIDE_PORTRAIT, Ti.UI.LANDSCAPE_LEFT, Ti.UI.LANDSCAPE_RIGHT

[*]<backgroundModes>: A list of background modes this app supports

<mode>: A background mode, valid values are: audio, location, and voip.

[*]<requires>: A list of features this app requires

[*]<feature>: A feature that this app requires, valid values are: telephony, wifi, sms, still-camera, auto-focus-camera, front-facing-camera, camera-flash, video-camera, accelerometer, gyroscope, location-services, gps, magnetometer, gamekit, microphone, opengles-1, opengles-2, armv6, armv7, peer-peer

[/list]

[b]Android specific section[/b]

Under the top <ti:app> element, you may optionally have an <android> element that contains Android specific configuration. If the application requires any ad-hoc XML from AndroidManifest.xml, make sure to also add the android XML namespace, like so:

[list]

[*]<activities>: Defines a list of custom Javascript based Android activities

[*]<activity url="activity.js"/>: Creates an activity with a URL that points to the Javascript file (under Resources) that defines it.

Ad-hoc elements: Under the <activity> tag, any ad-hoc element from an AndroidManifest.xml is supported. See the documentation for the activity element in AndroidManifest.xml

[*]<services>: Defines a list of custom Javascript based Android services (long running background processes)

[*]<service url="service.js" type="standard"/>: Creates a service with a URL that points to the Javascript file (under Resources) that defines it. type is optional.

Ad-hoc elements: Under the <service> tag, any ad-hoc element from an AndroidManifest.xml is supported. See the documentation for the service element in AndroidManifest.xml

[*]<manifest>: Ad-hoc XML from AndroidManifest.xml

[*]<tool-api-level>: The version of the Android API that Titanium builds against. In Titanium Mobile 1.7.0, we default to Android API level 7.

[/list]

[b]Android specific application properties[/b]

Android also supports a number of application properties for various internal settings. (See Application properties above on how to define an application property)

[table]

|Property Name|Type|Default Value|Description|

|ti.android.shake.factor|double|1.3|shake factor used for the "shake" event in the Titanium.Gesture module|

|ti.android.shake.quiet.milliseconds|int|500|number of "quiet" milliseconds before the "shake" event is fired|

|ti.android.shake.active.milliseconds|int|1000|number of "active" milliseconds before the "shake" event is fired|

|ti.android.google.map.api.key.development|string|N/A|A Google Maps API Key for use in development|

|ti.android.google.map.api.key.production|string|N/A|A Google Maps API Key for use in production|

|ti.android.httpclient.maxbuffersize|int|524288|The maximum buffer size (in bytes) before an HTTP response is written to a temporary file instead of memory (default is 512KB)|

|ti.android.threadstacksize|int|16384|The stack size (in bytes) to use when creating a Javascript thread (default: 16KB). Bump larger when encountering StackOverflow errors in very large Javascript files|

|ti.android.compilejs|bool|N/A|Turns on or off JS compilation. By default, JS compilation is only on when distributing an application, but manually setting this to "true" will enable it for development as well.|

|ti.android.fastdev|bool|N/A|Enables or disables Fastdev. By default, Fastdev is enabled in development mode, and disabled in device and production mode.|

|ti.android.debug|bool|false|turn on detailed logging in the SDK|

|ti.android.runtime|string|v8|v8/rhino (since 1.8.0)|

[/table]

The official Android Developers website describes all the other elements that are supported, such as <service>, <uses-permission> and {{<activity> for instance, and these will be added using the same logic.

[b]Common Requirements[/b]

Configuring screen densities

To indicate that your application supports any screen densities, which was a common use-case, add the <supports-screens> element set to true like this:

[b]Enabling the debugger by default[/b]

To make the app debuggable by default, set the <application> attribute to `true` (it's false in our default manifest template):

[b]Setting install location preferences.[/b]

Your Android apps are installed by default to the device's internal storage, but Titanium apps can be installed to the SD card using the following configuration:

For the <code>android:installLocation</code> property, choose one of these values:

[list]

[*]android:installLocation="preferExternal" -- specifies that you prefer your app to install to the SD card, but if one isn't present the app can be installed to internal storage.

[*]android:installLocation="auto" – specifies that the phone's configuration will determine the installation location. Generally, your app will be installed to internal storage if sufficient space is available. In that case, users could still move your app by opening Settings > Applications > Manage applications, tapping your app, and tapping Move to SD card.

[*]android:installLocation="internalOnly" – which specifies that your app cannot be installed to the SD card. See the Android docs for the various reasons why you might choose this option.

Finally, you need to add the <uses-sdk> tag within the <manifest> node. This tag specifies that your app requires Google's version 7 or newer APIs — in other words, the phone must be running Android 2.1 Update 1 or newer. That pretty much covers all the newer phones, but will exclude some older devices. On those phones, your app will install to the internal storage.

[/list]

Properties for configuring the workaround for Google Android issues 2373 and 5277

See TIMOB-4941 and TIMOB-1559 for information about the Titanium workaround to Google issues 2373 and 5277

[table]

|Property Name|Type|Default Value|Description|

|ti.android.bug2373.disableDetection|bool|false|setting to true will completely disable the workaround|

|ti.android.bug2373.title|String|Restart Required|title of dialog|

|ti.android.bug2373.message|String|An application restart is required|message used in dialog. if skipAlert is true the message is shown in a Toast if message length is > 0|

|ti.android.bug2373.buttonText|String|Continue|button text on alert dialog|

|ti.android.bug2373.restartDelay|int|500|number of milliseconds to wait before starting the new copy of the app with the correct Intent settings.|

|ti.android.bug2373.finishDelay|int|0|number of milliseconds to wait before finishing (exiting) the current application.|

|ti.android.bug2373.skipAlert|bool|false|if true, the dialog box will not be shown, but the workaround will still be applied if disableDetection is false.|

[/table]

[b]Modules[/b]

See the Module Developer Guides for Android and iOS.

[b]timodule.xml[/b]

A timodule.xml follows the same structure as a tiapp.xml, but most of the metadata for a module project lives in the module's manifest file. Right now, the timodule.xml is only used in Android, and it supports all of the tags listed in the Android section above. Any custom metadata your Android module defines in it's timodule.xml <android> section will automatically be merged with a Titanium Mobile application that installs your module.

[b]Sample tiapp.xml[/b]

Here is a sample tiapp.xml, taken from a generated Titanium Mobile project: