Titanium中Android模块开发指南（汉语言）

Titanium中Android模块开发指南（中文）
官方地址：Android Module Development Guide

摘要
本指南教你如何在Titanium中开发Android模块从而扩展Titanium的功能. 在本指南中,你将会学习到以下几点:

• 设置你的环境能够构建Android模块
• 构建一个Android模块
• 打包一个Android模块
• 理解Android模块API

Titanium Android模块开发指南
为了使用Android模块SDK, 你必须具有Android SDK相关的知识. 本指南将假定你知道如何使用原生的Android SDK进行开发.

前提条件

• Titanium Mobile SDK 1.5 及以上版本
• 最新版的Python( >= 2.5), 必须在PATH路径中, 或定义PYTHONHOME常量
         在Windows中, Titanium Developer / Desktop绑定了Python2.5,因此不需要额外配置
• Oracle JDK
• Android SDK
• Ant 1.7.1 或以上版本,必须包含在PATH中.
         如果你不想单独安装Ant,你可以使用Eclipse

环境设置
参照 Titanium命令行工具 完成环境设置.

创建一个模块
要创建一个模块,我们需要传递一些参数给titanium命令行工具.

• 模块的名字 ($MODULE_NAME) 和ID ($MODULE_ID)
• 模块的目标运行平台 (android)
• Android SDK的安装目录 ($ANDROID_SDK) 例如 /opt/android-sdk

对于一个Android, 我们以如下参数创建一个模块：


作为一个示例, 我们创建了一个运行简单的加减操作的模块, 命名为 “calc”, 给定其ID为 “org.appcelerator.calc”, 并把Android SDK的路径指向 /path/to/android-sdk

如果运行成功,应该能在当前目录下看到新创建的 calc 子目录了.

模块项目目录布局
在模块目录中, 你可以看到刚生产的文件和目录树：

• LICENSE – 模块的版权说明
• build.properties – Ant的properties文件，包含Titanium SDK和Android SDK的路径
• build.xml – Ant 构建脚本 – 用于构建, 分发和测试模块
• manifest – 包含模块的版本,作者,许可,版权,名称,ID,GUID和平台信息的清单文件
• timodule.xml – 放置自定义的activities和想插入到AndroidManifest.xml文件的配置
• hooks – 脚本目录，在模块被添加/安装/删除/卸载的时候调用
• documentation – 生成的Markdown文件，包含了你的模块的例子文档
• assets – 模块所需的其他资源比如图像等放这里(详看README)
• lib – 放置需要的第三方JAR文件，他们将会被自动的追加到你的工程和模块zip中[*]src – 模块源代码目录
• example – 模块例子工程

Eclipse集成
TItanium 会创建导入为Eclipse项目所需要的文件, 在Eclipse 执行如下操作导入calc项目:

• 在顶部菜单中单击 “File > Import…”
• 打开General文件夹后，双击“Existing Project into Workspace”
• 点击“Select root directory”之后的“Browse…”
• 选择模块项目目录
• 在 Projects 列表中可以看到你的模块了:
• 
• 按下“Finish”后，就应该能够在Eclipse的”Package Explorer “下看到你的模块工程了.

构建模块zip
dist目录下的zip包是模块的可分发形式, 它通常遵循的命名模式为$MODULE_ID-android-$MODULE_VERSION.zip
其中包含:

• 编译的包含类,生成的绑定,以及资源文件的JAR包
• lib目录中的第三方JAR包
• 模块清单, 包括作者,版本,许可,版权等部署需要的元数据
• 模块的timodule.xml文件

通过Ant从命令行构建
如果ant已经在PATH中, 你可以简单地在模块顶层目录执行, 你会看到如下输出:


从Eclipse构建
如果你米有安装Ant,或者你更愿意使用Eclipse, 参照下面的步骤:

• 在模块目录中右击build.xml文件
• 点击 Run As > Ant Build
• 你将看到类似的输出

模块分发
要再Titanium Mobile应用程序中使用模块, 参照下面的步骤:
[list]

复制模块的zip文件到Titanium应用程序的根目录, 或Titanium SDK的根目录

在应用程序的tiapp.xml文件的标签内添加如下XML:

<!-- $MODULE_VERSION should be the same as "version" in the module manifest --> [*]<modules> [*]    <module version="$MODULE_VERSION">$MODULE_ID</module> [*]    <!-- For example, if we were adding the calc module: --> [*]    <module version="0.1">org.appcelerator.calc</module> [*]</modules> 

在应用程序代码中使用 require 函数包含模块代码到应用程序中, 例如:

var Module = require('$MODULE_ID');[*]// For example, to load the calc module:[*]var Calc = require('org.appcelerator.calc');

下一次应用程序启动或构件时, 模块应该被包含在应用程序中了.[/list]

用嵌入的Example项目进行测试
使你的模块能够工作,最简单的方法是在example/app.js文件中编写代码,并使用ant运行和测试模块代码. example目录等同于应用程序的Resources目录.

运行示例项目的过程非常简单:

• 运行android模拟器
• 模拟器启动后便可运行你的模块代码了.

运行Android模拟器
从命令行在模块项目木下运行:


你应该会在控制台中看到模拟器的输出！

在Eclipse中配置调用信息:

• 右击build.xml, 点击Run As > Ant Build… (第二个选项)
• 为了一个新的启动配置将会打开一个配置设置的窗口
• 然后选择execute对象，去掉**dist对象，选择run.emulator对象
• 重命名启动配置，然他跟明显的看的出来含义，比如“run emulator”
• 窗口长啥样的一个例子，calc module:
• 
• 点击Apply然后运行
• 这样你就可以通过外部工具菜单（或者工具栏）的run运行这个启动配置


• 你应该能看到在Eclipse的控制台窗口，emulator有输出信息

运行Example项目

Once the emulator is up and running, you just need to wait for the unlock screen to appear, and you can start running your project. Make sure to unlock the screen so you’ll see the example project when it launches.

From command line, run this inside your module project:



在Eclipse中设置启动配置:

Follow the same steps from the Launch configuration setup above, but use the run target instead of the run.emulator target. You should also name the configuration something different, for example run calc project

疑难排除技巧:

如果你运行对象是超时，试着找到emulator，然后通过以下命令重启ADB服务：



到这里，如果你成功的运行了模块例子工程的话，你将在模拟器中看到默认的”hello world“应用:


生成模块和Example代理

作为初始创建项目的一部分,Titanium产生两个示例项目中使用的类：

• module类, 如: src/org/appcelerator/calc/CalcModule.java
• proxy类, 如: src/org/appcelerator/calc/ExampleProxy.java

产看这些代码来了解一下Modules和Proxies是怎么样跟Javascript通信的，在下一节将简要介绍了Titanium 和Kroll的API。

Android Titanium API

模块和代理(Kroll part 1)

• 一个模块是一个静态的、可选的顶级接口点，总是可以通过相同的名字访问.Titanium.UI 和 Titanium.App 就是两个在顶级API TItanium对象下的两个Module例子.
• 代理是能够被用于通过一个模块或其他代理创建和查询的动态对象.当你使用“Titanium.UI.createView”:http://developer.appcelerator.com/apidoc/mobile/latest/Titanium.UI.createView-method.html 创建一个原生视图时, 视图对象本身就是一个代理
• 模块和代理都能够向Javascript API导出方法,属性,常量以及getters/setters方法.

模块

• 必须使用 @Kroll.module 符号标注,并继承 KrollModule 类
• 模块可以有父模块, 比如 “Titanium.App.Properties“http://developer.appcelerator.com/apidoc/mobile/latest/Titanium.App.Properties-module 模块就存在于 Titanium.App 下
• 可以给定一个唯一的ID用于require()
• 可以导出为顶级对象(与Titanium同级)

代理

• 必须使用 @Kroll.proxy 符号标注, 并继承 KrollProxy 类
• 当使用 @Kroll.proxy#creatableInModule() 时, 有一个生成的 “create” 方法.
• 有内置的事件管理

导出方法和属性(Kroll part 2)

方法

代理和模块的方法通过 @Kroll.method 符号标注进行导出. 下面是一个简单的例子:

@Kroll.methodpublic String getMessage() {    return "Hello World";}

如果你导出的方法要求当前Activity, 你可以添加 KrollInvocation 作为第一个参数:

@Kroll.methodpublic String getMessage(KrollInvocation invocation) {    Activity activity = invocation.getTiContext().getActivity();}

方法还有许多其他的选项, 详细信息可查看 @Kroll.method Javadoc

属性

属性可以以两种不同的形式导出:

1，getter/setter方法通过 @Kroll.getProperty 和 @Kroll.setProperty 符号导出, Getter/setter方法还可以被导出为Kroll方法(这是在Titanium中常用的模式)
2，使用 Kroll.property 符号导出为一个对象字段(使用反射,速度稍慢)

该示例为message属性导出了一个getter和setter, 以及同名的方法:

@Kroll.getProperty @Kroll.methodpublic String getMessage() {        return "Hello World";}@Kroll.setProperty @Kroll.methodpublic void setMessage(String message) {    Log.d(TAG, "Tried setting message to: " + message);}

在Javascript中可以这样使用:

var object = //..object.message = "hi"; // orobject.setMessage("hi");

常量

常量是 @Kroll.module 中的以及静态属性, 该字段以 [email protected] 符号标注, 必须是static和final, 这儿有一个例子:

@Kroll.modulepublic class MyModule extends KrollModule {    @Kroll.constant    public static final int CONSTANT = 100;}

常量可以直接使用: Ti.My.CONSTANT == 100

视图

在Titanium中视图必须要有2个class::

视图代理: TiViewProxy的子类

• 负责视图属性和方法暴露给JavaScript(和一般代理做的一样).
• 实现TiUIView的createView(Activity activity)方法来返回一个TiUIView的实例
• 很多时候，你想在UI线程中调用你的UIView，参考 @Kroll.method#runOnUiThread

视图实现: TiUIView的子类

• 必须用视图的一个实例来调用setNativeView，无论是在构造函数中，或在processProperties
• 视图实现负责从视图代理的获取数据，并直接应用到本地View
• 这个类可以选择性的实现propertyChanged 和 processProperties，当用户在proxy中设置了属性的话会的得到通知。

作为了一个简单的例子，参考Button 的实现方法ButtonProxy 和TiUIButton

重量级和轻量级窗口

当用户使用Titanium.UI.createWindow API 创建一个窗口时, 运行一些检查来告知是否创建应该是 heavy weight:

• 如果一个窗口被设置了以下任何一个属性的话，他就是”heavyweight“: fullscreen, navBarHidden, modal, windowSoftInputMode, 或者tabOpen:true
• 相反的话, 他就是”lightweight“
• Heavyweight窗口会在栈中生成一个新的Activity，而且也一直为窗口创建新的Javascript Context
• Lightweight窗口创建的时候一个全屏的View（调用代码是相同的Activity） ，如果设置了url属性的话，也会为每个窗口创建新的Javascript Context

线程安全

从Javascript的Context（潜在的任何Activity或Thread）调用一个方法或者属性的话，在设计你的API的时候，很重要的一点是保证线程安全。

为了确保一个方法是在UI线程上执行, 可以参考 @Kroll.method#runOnUiThread(). 以下是例子:

@Kroll.proxypublic class MyProxy extends KrollProxy {  @Kroll.method(runOnUiThread=true)  public int doSomething() {    return 100;  }}