Back to Details

ti-ui

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Titanium SDK UI expert

Titanium SDK UI专家

A practical guide to Titanium SDK UI. Covers layouts, event handling, animations, performance, and platform-specific components for iOS and Android.
这是一份Titanium SDK UI实用指南，涵盖iOS和Android平台的布局、事件处理、动画、性能优化以及平台特定组件相关内容。

Project detection

项目检测

:::info auto-detects titanium projects This skill detects Titanium projects and provides UI guidance.
Detection happens automatically. You do not need to run a command.
Titanium project indicator:
  • tiapp.xml
    (required for all Titanium projects)
Applicable to both:
  • Alloy projects (app/ folder structure)
  • Classic projects (Resources/ folder)
Behavior based on detection:
  • Titanium detected: Provide UI guidance for Alloy and Classic, ListView/TableView patterns, and platform differences
  • Not detected: State this is for Titanium projects only and skip UI guidance :::
:::info 自动检测Titanium项目 该技能可检测Titanium项目并提供UI开发指导。
检测过程自动进行，无需执行命令。
Titanium项目标识：
  • tiapp.xml
    （所有Titanium项目必备文件）
适用于两种项目类型：
  • Alloy项目（app/目录结构）
  • 经典项目（Resources/目录）
基于检测结果的行为：
  • 检测到Titanium项目：提供Alloy和经典项目的UI指导、ListView/TableView模式以及平台差异说明
  • 未检测到Titanium项目：说明本技能仅适用于Titanium项目，不提供UI指导 :::

Quick reference

快速参考

TopicReference
App structuresapplication-structures.md
Layouts, positioning, unitslayouts-and-positioning.md
Events, bubbling, lifecycleevent-handling.md
ScrollView vs ScrollableViewscrolling-views.md
TableViewtableviews.md
ListView templates, performancelistviews-and-performance.md
Touch, swipe, pinch, gesturesgestures.md
Orientation handlingorientation.md
Custom fonts, attributed stringscustom-fonts-styling.md
Animations, 2D/3D matricesanimation-and-matrices.md
Icons, splash screens, densitiesicons-and-splash-screens.md
Android action bar, themesplatform-ui-android.md
iOS navigation, 3D Touchplatform-ui-ios.md
VoiceOver, TalkBack, a11yaccessibility-deep-dive.md
主题参考文档
应用结构application-structures.md
布局、定位、单位layouts-and-positioning.md
事件、冒泡、生命周期event-handling.md
ScrollView vs ScrollableViewscrolling-views.md
TableViewtableviews.md
ListView模板、性能listviews-and-performance.md
触摸、滑动、捏合、手势gestures.md
屏幕方向处理orientation.md
自定义字体、富文本字符串custom-fonts-styling.md
动画、2D/3D矩阵animation-and-matrices.md
图标、启动页、屏幕密度icons-and-splash-screens.md
Android Action Bar、主题platform-ui-android.md
iOS导航、3D Touchplatform-ui-ios.md
VoiceOver、TalkBack、无障碍accessibility-deep-dive.md

Critical rules

关键规则

Performance

性能

  • Do not use 
    Ti.UI.SIZE
    in ListViews. It causes jerky scrolling. Use fixed heights.
  • Prefer ListView over TableView for new apps with large datasets.
  • Batch updates with 
    applyProperties
    to reduce bridge overhead.
  • Avoid WebView inside TableView. It kills scrolling performance.
  • 请勿在ListView中使用
    Ti.UI.SIZE
    ，这会导致滚动卡顿，应使用固定高度。
  • 对于包含大数据集的新应用，优先使用ListView而非TableView。
  • 使用
    applyProperties
    批量更新属性，减少桥接层开销。
  • 避免在TableView内嵌套WebView，这会严重影响滚动性能。

iOS accessibility

iOS无障碍访问

  • Do not set accessibility properties on container views. It blocks child interaction.
  • Do not set 
    accessibilityLabel
    on text controls on Android. It overrides visible text.
  • 请勿在容器视图上设置无障碍属性，这会阻止子视图的交互。
  • 请勿在Android的文本控件上设置
    accessibilityLabel
    ，这会覆盖可见文本内容。

Layout

布局

  • Use 
    dp
    units for cross-platform consistency.
  • Android ScrollView is vertical or horizontal, not both. Set 
    scrollType
    .
  • 使用
    dp
    单位确保跨平台一致性。
  • Android的ScrollView仅支持垂直或水平单一方向滚动，需设置
    scrollType
    。

Platform-specific properties

平台特定属性

:::danger critical: platform-specific properties require modifiers Using 
Ti.UI.iOS.*
or 
Ti.UI.Android.*
properties without platform modifiers will crash cross-platform compilation.
Example of the damage:
javascript
// Wrong: adds Ti.UI.iOS to an Android build
const win = Ti.UI.createWindow({
  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
})
Correct approaches:
Option 1: TSS modifier (Alloy projects):
tss
"#mainWindow[platform=ios]": {
  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
}
Option 2: Conditional code:
javascript
if (OS_IOS) {
  $.mainWindow.statusBarStyle = Ti.UI.iOS.StatusBar.LIGHT_CONTENT
}
Properties that always require platform modifiers:
  • iOS: 
    statusBarStyle
    , 
    modalStyle
    , 
    modalTransitionStyle
    , any 
    Ti.UI.iOS.*
  • Android: 
    actionBar
    config, any 
    Ti.UI.Android.*
    constant
For platform-specific UI patterns, see platform-ui-ios.md and platform-ui-android.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
})
正确实现方式：
方式1：TSS修饰符（Alloy项目）：
tss
"#mainWindow[platform=ios]": {
  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
}
方式2：条件判断代码：
javascript
if (OS_IOS) {
  $.mainWindow.statusBarStyle = Ti.UI.iOS.StatusBar.LIGHT_CONTENT
}
必须添加平台修饰符的属性：
  • iOS: 
    statusBarStyle
    , 
    modalStyle
    , 
    modalTransitionStyle
    , 所有
    Ti.UI.iOS.*
    属性
  • Android: 
    actionBar
    配置, 所有
    Ti.UI.Android.*
    常量
关于平台特定UI模式，请参考platform-ui-ios.md和platform-ui-android.md。 :::

Event management

事件管理

  • Remove global listeners (
    Ti.App
    , 
    Ti.Gesture
    , 
    Ti.Accelerometer
    ) on pause to save battery.
  • Input events bubble up. System events do not.
  • 在应用暂停时移除全局监听器（
    Ti.App
    、
    Ti.Gesture
    、
    Ti.Accelerometer
    ）以节省电量。
  • 输入事件会向上冒泡，系统事件不会。

App architecture

应用架构

  • Limit tabs to 4 or fewer for better UX across platforms.
  • Use NavigationWindow for iOS hierarchical navigation.
  • Handle 
    androidback
    to prevent unexpected exits.
  • 标签栏的标签数量限制在4个以内，以确保跨平台的良好UX。
  • iOS平台使用NavigationWindow实现层级导航。
  • 处理
    androidback
    事件，防止应用意外退出。

Platform differences summary

平台差异总结

FeatureiOSAndroid
3D MatrixFull supportNo support
Pinch gestureFull supportLimited
ScrollViewBidirectionalUnidirectional
TableViewFull supportFull support
ListViewFull supportFull support
Default template imageLeft sideRight side
ListView action itemsSwipe actionsNo
Modal windowsFills screen, covers tab barNo effect (always full)
Navigation patternNavigationWindowBack button + Menu
功能iOSAndroid
3D矩阵完全支持不支持
捏合手势完全支持支持有限
ScrollView双向滚动单向滚动
TableView完全支持完全支持
ListView完全支持完全支持
默认模板图片位置左侧右侧
ListView操作项滑动操作无
模态窗口全屏显示，覆盖标签栏无特殊效果（始终全屏）
导航模式NavigationWindow返回按钮 + 菜单

UI design workflow

UI设计流程

  1. Choose app structure: tab-based or window-based
  2. Pick a layout mode: composite, vertical, or horizontal
  3. Decide sizing: 
    SIZE
    or 
    FILL
    based on component defaults
  4. Plan events: bubbling, app-level events, lifecycle
  5. Optimize performance: templates, batch updates
  6. Apply accessibility per platform
  7. Add motion: animations, 2D/3D transforms, transitions
  1. 选择应用结构：标签栏式或窗口式
  2. 选择布局模式：复合、垂直或水平
  3. 确定尺寸：根据组件默认值选择
    SIZE
    或
    FILL
  4. 规划事件：冒泡机制、应用级事件、生命周期事件
  5. 性能优化：模板使用、批量更新
  6. 按平台要求适配无障碍访问
  7. 添加动效：动画、2D/3D变换、过渡效果

Searching references

参考文档搜索

When you need specific patterns, grep these terms in the reference files:
  • App structure: 
    TabGroup
    , 
    NavigationWindow
    , 
    modal
    , 
    execution context
    , 
    androidback
  • Layouts: 
    dp
    , 
    Ti.UI.SIZE
    , 
    Ti.UI.FILL
    , 
    composite
    , 
    vertical
    , 
    horizontal
  • Events: 
    addEventListener
    , 
    cancelBubble
    , 
    bubbling
    , 
    Ti.App.fireEvent
  • TableView: 
    TableView
    , 
    TableViewRow
    , 
    setData
    , 
    appendRow
    , 
    className
  • ListView: 
    ItemTemplate
    , 
    bindId
    , 
    setItems
    , 
    updateItemAt
    , 
    marker
  • Gestures: 
    swipe
    , 
    pinch
    , 
    longpress
    , 
    shake
    , 
    accelerometer
  • Animation: 
    animate
    , 
    create2DMatrix
    , 
    create3DMatrix
    , 
    autoreverse
  • Fonts: 
    fontFamily
    , 
    PostScript
    , 
    createAttributedString
    , 
    ATTRIBUTE_
  • Icons/splash: 
    DefaultIcon
    , 
    appicon
    , 
    nine-patch
    , 
    drawable
    , 
    splash
    , 
    iTunesArtwork
    , 
    adaptive
  • Android: 
    Action Bar
    , 
    onCreateOptionsMenu
    , 
    theme
    , 
    Material3
    , 
    talkback
  • iOS: 
    3D Touch
    , 
    Popover
    , 
    SplitWindow
    , 
    badge
    , 
    NavigationWindow
  • Accessibility: 
    accessibilityLabel
    , 
    VoiceOver
    , 
    TalkBack
    , 
    accessibilityHidden
当需要特定模式时，可在参考文档中搜索以下关键词：
  • 应用结构：
    TabGroup
    , 
    NavigationWindow
    , 
    modal
    , 
    execution context
    , 
    androidback
  • 布局：
    dp
    , 
    Ti.UI.SIZE
    , 
    Ti.UI.FILL
    , 
    composite
    , 
    vertical
    , 
    horizontal
  • 事件：
    addEventListener
    , 
    cancelBubble
    , 
    bubbling
    , 
    Ti.App.fireEvent
  • TableView: 
    TableView
    , 
    TableViewRow
    , 
    setData
    , 
    appendRow
    , 
    className
  • ListView: 
    ItemTemplate
    , 
    bindId
    , 
    setItems
    , 
    updateItemAt
    , 
    marker
  • 手势：
    swipe
    , 
    pinch
    , 
    longpress
    , 
    shake
    , 
    accelerometer
  • 动画：
    animate
    , 
    create2DMatrix
    , 
    create3DMatrix
    , 
    autoreverse
  • 字体：
    fontFamily
    , 
    PostScript
    , 
    createAttributedString
    , 
    ATTRIBUTE_
  • 图标/启动页：
    DefaultIcon
    , 
    appicon
    , 
    nine-patch
    , 
    drawable
    , 
    splash
    , 
    iTunesArtwork
    , 
    adaptive
  • Android: 
    Action Bar
    , 
    onCreateOptionsMenu
    , 
    theme
    , 
    Material3
    , 
    talkback
  • iOS: 
    3D Touch
    , 
    Popover
    , 
    SplitWindow
    , 
    badge
    , 
    NavigationWindow
  • 无障碍访问：
    accessibilityLabel
    , 
    VoiceOver
    , 
    TalkBack
    , 
    accessibilityHidden

Related skills

相关技能

For work beyond UI components, use these skills:
TaskUse this skill
Project architecture, services, memory cleanup
ti-expert
Native features (camera, location, push, media)
ti-howtos
Alloy MVC, data binding, widgets
alloy-guides
若需处理UI组件之外的工作，可使用以下技能：
任务对应技能
项目架构、服务、内存清理
ti-expert
原生功能（相机、定位、推送、媒体）
ti-howtos
Alloy MVC、数据绑定、组件
alloy-guides