Titanium中Android模塊開發指南

作者：rensanning 2012-05-18 10:08:56

本指南教你如何在Titanium中開發Android模塊從而擴展Titanium的功能. 在本指南中,你將會學習到以下幾點:設置你的環境能夠構建Android模塊;構建一個Android模塊;打包一個Android模塊;理解Android模塊API.

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

官方地址：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, 我們以如下參數創建一個模塊：

引用

titanium create --platform=android --type=module --name=$MODULE_NAME --id=$MODULE_ID --android=$ANDROID_SDK

作為一個示例,我們創建了一個運行簡單的加減操作的模塊,命名為“calc”,給定其ID為“org.appcelerator.calc”,并把Android SDK的路徑指向/path/to/android-sdk

引用

titanium create --platform=android --type=module --name=calc --id=org.appcelerator.calc --android=/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中, 你可以簡單地在模塊頂層目錄執行, 你會看到如下輸出:

引用

$ ant
Buildfile: /Users/marshall/Code/test/test_modules/calc/build.xml

init:
[mkdir] Created dir: /Users/marshall/Code/test/test_modules/calc/build/classes
[mkdir] Created dir: /Users/marshall/Code/test/test_modules/calc/dist

process.annotations:
[javac] Compiling 2 source files to /Users/marshall/Code/test/test_modules/calc/build/classes
[javac] Note: [KrollBindingGen] Running Kroll binding generator.
[javac] Note: [KrollBindingGen] No binding data found, creating new data file.
[javac] Note: [KrollBindingGen] Found binding for module Calc
[javac] Note: [KrollBindingGen] Found binding for proxy Example

compile:
[javac] Compiling 2 source files to /Users/marshall/Code/test/test_modules/calc/build/classes
[copy] Copying 1 file to /Users/marshall/Code/test/test_modules/calc/build/classes

dist:
[jar] Building jar: /Users/marshall/Code/test/test_modules/calc/dist/calc.jar
[zip] Building zip: /Users/marshall/Code/test/test_modules/calc/dist/org.appcelerator.calc-android-0.1.zip

BUILD SUCCESSFUL
Total time: 1 second

從Eclipse構建

如果你米有安裝Ant,或者你更愿意使用Eclipse,參照下面的步驟:

在模塊目錄中右擊build.xml文件
點擊RunAs>AntBuild
你將看到類似的輸出

模塊分發

要再TitaniumMobile應用程序中使用模塊,參照下面的步驟:

[list]

復制模塊的zip文件到Titanium應用程序的根目錄,或TitaniumSDK的根目錄
在應用程序的tiapp.xml文件的標簽內添加如下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模擬器

從命令行在模塊項目木下運行:

引用

ant run.emulator

你應該會在控制臺中看到模擬器的輸出！

在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:

引用

ant run

在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服務：

$ $ANDROID_SDK/tools/adb kill-server
$ $ANDROID_SDK/tools/adb start-server

到這里，如果你成功的運行了模塊例子工程的話，你將在模擬器中看到默認的”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 符號標注進行導出. 下面是一個簡單的例子:

Java代碼

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

如果你導出的方法要求當前Activity, 你可以添加 KrollInvocation 作為第一個參數:

Java代碼

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

方法還有許多其他的選項,詳細信息可查看@Kroll.methodJavadoc

屬性

屬性可以以兩種不同的形式導出:

1，getter/setter方法通過@Kroll.getProperty和@Kroll.setProperty符號導出,Getter/setter方法還可以被導出為Kroll方法(這是在Titanium中常用的模式)

2，使用Kroll.property符號導出為一個對象字段(使用反射,速度稍慢)

該示例為message屬性導出了一個getter和setter,以及同名的方法:

Java代碼

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

在Javascript中可以這樣使用:

Js代碼

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

常量

常量是 @Kroll.module 中的以及靜態屬性, 該字段以 “@Kroll.constant” 符號標注, 必須是static和final, 這兒有一個例子:

Java代碼

@Kroll.module   
public 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(). 以下是例子:

Java代碼

責任編輯：佚名來源： rensanning的博客

Titanium Android