Back to Details

ti-howtos

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Titanium SDK how-tos

Titanium SDK操作指南

Hands-on guide to Titanium SDK native integrations. Focuses on practical steps, platform differences, and the details that usually bite.
Titanium SDK原生集成实操指南，聚焦实用步骤、平台差异及常见易踩坑细节。

Project detection

项目检测

::::info Auto-detects Titanium projects This skill detects Titanium projects automatically.
Indicators:
  • tiapp.xml
    exists (definitive)
  • Alloy project: 
    app/
    folder
  • Classic project: 
    Resources/
    folder
Behavior:
  • Titanium detected: provide native integration guidance, permissions, modules, and platform notes
  • Not detected: say this skill is for Titanium projects only ::::
::::info 自动检测Titanium项目 本技能可自动检测Titanium项目。
检测标识：
  • 存在
    tiapp.xml
    文件（确定性标识）
  • Alloy项目：包含
    app/
    文件夹
  • 经典项目：包含
    Resources/
    文件夹
行为逻辑：
  • 检测到Titanium项目：提供原生集成指导、权限配置、模块依赖及平台注意事项
  • 未检测到：提示本技能仅适用于Titanium项目 ::::

Integration workflow

集成流程

  1. Requirement check: permissions, 
    tiapp.xml
    , and module dependencies.
  2. Service setup: listeners and services (Location, Push, Core Motion, and so on).
  3. Lifecycle sync: tie listeners to Android and iOS lifecycle events.
  4. Error handling: use robust callbacks for async native calls.
  5. Platform optimization: apply platform-specific logic (Intent filters, Spotlight, Core Motion).
  1. 需求检查：权限、
    tiapp.xml
    配置及模块依赖。
  2. 服务设置：监听器与服务配置（定位、推送、Core Motion等）。
  3. 生命周期同步：将监听器与Android和iOS的生命周期事件绑定。
  4. 错误处理：为异步原生调用添加健壮的回调逻辑。
  5. 平台优化：应用平台特定逻辑（Intent过滤器、Spotlight、Core Motion等）。

Native integration rules

原生集成规则

iOS permissions

iOS权限配置

  • Location: 
    NSLocationWhenInUseUsageDescription
    or 
    NSLocationAlwaysAndWhenInUseUsageDescription
    in 
    tiapp.xml
    .
  • Motion activity: required for Core Motion Activity API.
  • Camera and photo: 
    NSCameraUsageDescription
    and 
    NSPhotoLibraryUsageDescription
    .
  • Background modes: required for background audio, location, or VOIP.
  • iOS 17+: add 
    PrivacyInfo.xcprivacy
    for UserDefaults and File Timestamps.
  • 定位：在
    tiapp.xml
    中添加
    NSLocationWhenInUseUsageDescription
    或
    NSLocationAlwaysAndWhenInUseUsageDescription
    。
  • 运动活动：使用Core Motion Activity API时需配置。
  • 相机与相册：添加
    NSCameraUsageDescription
    和
    NSPhotoLibraryUsageDescription
    。
  • 后台模式：后台音频、定位或VOIP功能需配置。
  • iOS 17+：为UserDefaults和文件时间戳添加
    PrivacyInfo.xcprivacy
    配置。

Android resource management

Android资源管理

  • Services: stop background services when they are no longer needed.
  • Location: use 
    distanceFilter
    and FusedLocationProvider (requires 
    ti.playservices
    ).
  • Intents: set action, data type, and category. Copy the root activity to 
    tiapp.xml
    for intent filters.
  • 服务：不再需要时停止后台服务。
  • 定位：使用
    distanceFilter
    和FusedLocationProvider（需依赖
    ti.playservices
    模块）。
  • Intents：设置action、数据类型及category。复制根Activity到
    tiapp.xml
    以配置Intent过滤器。

Data and networking

数据与网络

  • HTTPClient: handle both 
    onload
    and 
    onerror
    .
  • SQLite: close both 
    db
    and 
    resultSet
    to avoid locks.
  • Filesystem: check 
    isExternalStoragePresent()
    before using SD card storage.
  • Binary data: use 
    Ti.Buffer
    and 
    Ti.Codec
    for byte-level work.
  • Streams: use 
    BufferStream
    , 
    FileStream
    , or 
    BlobStream
    for chunked I/O.
  • HTTPClient：同时处理
    onload
    和
    onerror
    事件。
  • SQLite：关闭
    db
    和
    resultSet
    以避免锁表。
  • 文件系统：使用SD卡存储前先检查
    isExternalStoragePresent()
    。
  • 二进制数据：使用
    Ti.Buffer
    和
    Ti.Codec
    处理字节级操作。
  • 流：使用
    BufferStream
    、
    FileStream
    或
    BlobStream
    处理分块I/O。

Media and memory

媒体与内存

  • Camera and gallery: use 
    imageAsResized
    to reduce memory pressure.
  • Audio: handle 
    pause
    and 
    resume
    for streaming interruptions.
  • WebView: avoid TableView embedding; set 
    touchEnabled=false
    if needed.
  • Video: Android requires fullscreen; iOS supports embedded players.
  • 相机与相册：使用
    imageAsResized
    减少内存压力。
  • 音频：处理流中断时的
    pause
    和
    resume
    逻辑。
  • WebView：避免嵌入TableView；必要时设置
    touchEnabled=false
    。
  • 视频：Android要求全屏播放；iOS支持嵌入式播放器。

Platform-specific properties

平台特定属性

::::danger Platform-specific properties need modifiers Using 
Ti.UI.iOS.*
or 
Ti.UI.Android.*
without platform modifiers can break cross-platform builds.
Bad example:
javascript
// Wrong: adds Ti.UI.iOS to Android build
const win = Ti.UI.createWindow({
  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
});
Good options:
TSS modifier (Alloy):
tss
"#mainWindow[platform=ios]": {
  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
}
Conditional code:
javascript
if (OS_IOS) {
  $.mainWindow.statusBarStyle = Ti.UI.iOS.StatusBar.LIGHT_CONTENT;
}
Always require modifiers:
  • iOS: 
    statusBarStyle
    , 
    modalStyle
    , 
    modalTransitionStyle
    , any 
    Ti.UI.iOS.*
    .
  • Android: 
    actionBar
    config, any 
    Ti.UI.Android.*
    constant.
For TSS platform modifiers, see the code conventions in 
skills/ti-expert/references/code-conventions.md#platform--device-modifiers
or the platform UI guides in 
references/ios-platform-deep-dives.md
. ::::
::::danger 平台特定属性需添加修饰符 未添加平台修饰符直接使用
Ti.UI.iOS.*
或
Ti.UI.Android.*
会破坏跨平台构建。
错误示例：
javascript
// 错误：会在Android构建中引入Ti.UI.iOS代码
const win = Ti.UI.createWindow({
  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
});
正确方案：
TSS修饰符（Alloy框架）：
tss
"#mainWindow[platform=ios]": {
  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
}
条件判断代码：
javascript
if (OS_IOS) {
  $.mainWindow.statusBarStyle = Ti.UI.iOS.StatusBar.LIGHT_CONTENT;
}
必须添加修饰符的属性：
  • iOS：
    statusBarStyle
    、
    modalStyle
    、
    modalTransitionStyle
    及所有
    Ti.UI.iOS.*
    属性。
  • Android：
    actionBar
    配置及所有
    Ti.UI.Android.*
    常量。
关于TSS平台修饰符的更多内容，请参考
skills/ti-expert/references/code-conventions.md#platform--device-modifiers
中的代码规范，或
references/ios-platform-deep-dives.md
中的平台UI指南。 ::::

Reference guides

参考指南

Core features

核心功能

  • Location and maps: GPS tracking and battery-efficient location rules.
  • Google Maps v2 (Android): API keys, Google Play Services, and v2 features.
  • iOS Map Kit: 3D camera, system buttons, and iOS callouts.
  • Notification services: push notifications (APNs/FCM), local alerts, interactive notifications.
  • 定位与地图：GPS追踪及省电定位规则。
  • Google Maps v2（Android）：API密钥、Google Play Services及v2版本特性。
  • iOS Map Kit：3D相机、系统按钮及iOS标注框。
  • 通知服务：推送通知（APNs/FCM）、本地提醒、交互式通知。

Data handling

数据处理

  • Remote data sources: HTTPClient lifecycle, JSON/XML parsing, uploads, downloads, sockets, SOAP, SSL.
  • Local data sources: filesystem operations, SQLite, Properties API, persistence strategy.
  • Buffer, Codec, and Streams: binary data manipulation and serial data flows.
  • 远程数据源：HTTPClient生命周期、JSON/XML解析、上传下载、套接字、SOAP、SSL。
  • 本地数据源：文件系统操作、SQLite、Properties API、持久化策略。
  • Buffer、Codec与流：二进制数据处理及串行数据流。

Media and content

媒体与内容

  • Media APIs: audio playback and recording, video streaming, camera and gallery, ImageViews, density assets.
  • 媒体API：音频播放与录制、视频流、相机与相册、ImageView、适配不同密度的资源。

Web integration

Web集成

  • Web content integration: WebView (WKWebView), local and remote content, bidirectional communication.
  • Webpack build pipeline: Ti 9.1.0+ build pipeline, npm integration, and the 
    @
    alias.
  • Web内容集成：WebView（WKWebView）、本地与远程内容、双向通信。
  • Webpack构建流水线：Ti 9.1.0+构建流水线、npm集成及
    @
    别名。

Platform-specific (Android)

平台特定（Android）

  • Android platform deep dives: intents, intent filters, broadcast permissions, background services.
  • Android平台深度解析：Intents、Intent过滤器、广播权限、后台服务。

Platform-specific (iOS)

平台特定（iOS）

  • iOS platform deep dives: iOS 17 privacy, silent push, Spotlight, Handoff, iCloud, Core Motion, WatchKit and Siri.
  • iOS平台深度解析：iOS 17隐私政策、静默推送、Spotlight、Handoff、iCloud、Core Motion、WatchKit与Siri。

Advanced and DevOps

进阶与DevOps

  • Extending Titanium: Hyperloop, native modules (Proxy and View), Xcode debugging, AndroidX migration for SDK 9.0.
  • Debugging and profiling: memory management, leak detection, native tools.
  • Automation (Fastlane and Appium): CI/CD, UI testing, store deployment.
  • 扩展Titanium：Hyperloop、原生模块（Proxy与View）、Xcode调试、SDK 9.0的AndroidX迁移。
  • 调试与性能分析：内存管理、内存泄漏检测、原生工具。
  • 自动化（Fastlane与Appium）：CI/CD、UI测试、应用商店部署。

Related skills

相关技能

For tasks beyond native feature integration, use:
TaskUse this skill
Project architecture, services, memory cleanup
ti-expert
UI layouts, ListViews, gestures, animations
ti-ui
Hyperloop, app distribution, tiapp.xml config
ti-guides
Alloy MVC, models, data binding
alloy-guides
若需处理原生功能集成之外的任务，请使用以下技能：
任务对应技能
项目架构、服务、内存清理
ti-expert
UI布局、ListView、手势、动画
ti-ui
Hyperloop、应用分发、tiapp.xml配置
ti-guides
Alloy MVC、模型、数据绑定
alloy-guides

Response format

响应格式

  1. Prerequisites: required permissions, 
    tiapp.xml
    config, or modules.
  2. Step-by-step implementation: task-focused code guide with error handling.
  3. Platform caveats: iOS and Android differences.
  4. Best practices: memory, lifecycle, and performance tips.
  1. 前置条件：所需权限、
    tiapp.xml
    配置或依赖模块。
  2. 分步实现：以任务为核心的代码指南，包含错误处理。
  3. 平台注意事项：iOS与Android的差异。
  4. 最佳实践：内存、生命周期及性能优化建议。