tiapp.xml / timodule.xml 详解

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

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.

Top Level Elements
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>

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

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

<property name="name" type="type">value</property>

• 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

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

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

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

Android specific section
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:

<android xmlns:android="http://schemas.android.com/apk/res/android">
<!-- .. -->
</android>

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

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

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)

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.

Common Requirements
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:

<android xmlns:android="http://schemas.android.com/apk/res/android">
    <manifest>
        <supports-screens
            android:smallScreens="false"
            android:normalScreens="true"
            android:largeScreens="true"
            android:anyDensity="false"
        />
    </manifest>
</android>

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

<android xmlns:android="http://schemas.android.com/apk/res/android">
    <manifest>
        <application android:debuggable="true" />
    </manifest>
</android>

Setting install location preferences.
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:

<android xmlns:android="http://schemas.android.com/apk/res/android">
   <tool-api-level>8</tool-api-level>
   <manifest android:installLocation="preferExternal">
      <uses-sdk android:minSdkVersion="7" />
   </manifest>
</android>

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

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

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

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.

Modules
See the Module Developer Guides for Android and iOS.

timodule.xml
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.

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

<?xml version="1.0" encoding="UTF-8"?>
<ti:app xmlns:ti="http://ti.appcelerator.org">
    <id>com.appcelerator.helloWorld</id>
    <name>helloWorld</name>
    <version>1.0</version>
    <publisher>not specified</publisher>
    <url>not specified</url>
    <description>not specified</description>
    <copyright>not specified</copyright>
    <icon>appicon.png</icon>
    <persistent-wifi>false</persistent-wifi>
    <prerendered-icon>false</prerendered-icon>
    <statusbar-style>default</statusbar-style>
    <statusbar-hidden>false</statusbar-hidden>
    <fullscreen>false</fullscreen>
    <navbar-hidden>false</navbar-hidden>
    <analytics>true</analytics>
    <guid></guid>
    <iphone>
        <orientations device="iphone">
            <orientation>Ti.UI.PORTRAIT</orientation>
        </orientations>
        <orientations device="ipad">
            <orientation>Ti.UI.PORTRAIT</orientation>
            <orientation>Ti.UI.UPSIDE_PORTRAIT</orientation>
            <orientation>Ti.UI.LANDSCAPE_LEFT</orientation>
            <orientation>Ti.UI.LANDSCAPE_RIGHT</orientation>
        </orientations>
    </iphone>
    <android xmlns:android="http://schemas.android.com/apk/res/android">
    </android>
    <modules>
    </modules>
</ti:app>