ti-expert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Titanium expert

Titanium 专家

Practical architecture and implementation guidance for Titanium SDK apps (Alloy and Classic). Focus on maintainability, clear boundaries, and low-friction testing.

为Titanium SDK应用（Alloy和Classic模式）提供实用的架构与实现指导，重点关注可维护性、清晰的边界划分以及低门槛测试。

Project detection

项目检测

:::info Auto-detects Alloy vs Classic projects This skill detects project type automatically and tailors guidance.

Alloy indicators:

```
app/
```
folder (MVC structure)
```
app/views/
```
,
```
app/controllers/
```
folders
```
alloy.jmk
```
or
```
config.json
```
files

Classic indicators:

```
Resources/
```
folder with
```
app.js
```
at root
No
```
app/
```
folder structure

Behavior:

Alloy detected: provides Alloy MVC patterns and Backbone.js guidance
Classic detected: avoids Alloy-only patterns and recommends Classic options or migration
Unknown: asks the user to clarify the project type :::

:::info 自动检测Alloy与Classic项目该技能可自动检测项目类型，并提供针对性指导。

Alloy项目标识：

包含
```
app/
```
文件夹（MVC结构）
包含
```
app/views/
```
、
```
app/controllers/
```
文件夹
存在
```
alloy.jmk
```
或
```
config.json
```
文件

Classic项目标识：

根目录下的
```
Resources/
```
文件夹中包含
```
app.js
```
无
```
app/
```
文件夹结构

对应行为：

检测到Alloy项目：提供Alloy MVC模式及Backbone.js相关指导
检测到Classic项目：避免仅适用于Alloy的模式，推荐Classic项目的实现方案或迁移建议
未知项目类型：请用户明确项目类型 :::

Workflow

工作流程

Architecture: define structure by technical type with flat folders (
```
lib/api
```
,
```
lib/services
```
,
```
lib/actions
```
,
```
lib/repositories
```
,
```
lib/helpers
```
)
Data strategy: choose Models (SQLite) or Collections (API)
Contracts: define I/O specs between layers
Implementation: write XML views and ES6+ controllers
Quality: testing, error handling, logging, performance
Cleanup: implement a
```
cleanup()
```
pattern for memory management

架构设计：按技术类型定义扁平文件夹结构（
```
lib/api
```
、
```
lib/services
```
、
```
lib/actions
```
、
```
lib/repositories
```
、
```
lib/helpers
```
）
数据策略：选择Models（SQLite）或Collections（API）
契约定义：明确各层之间的输入输出规范
开发实现：编写XML视图与ES6+控制器
质量保障：测试、错误处理、日志记录、性能优化
内存清理：实现
```
cleanup()
```
模式进行内存管理

Architectural Maturity Tiers

架构成熟度层级

Choose the appropriate tier based on project complexity:

根据项目复杂度选择合适的层级：

Tier 1: Basic (Rapid Prototyping)

层级1：基础版（快速原型开发）

Best for: Simple utility apps or developers transitioning from Classic.
Structure: Logic resides directly within
```
index.js
```
.
UI Access: Direct usage of the
```
$
```
object throughout the file.
Pros: Zero boilerplate, extremely fast start.
Cons: Unmaintainable beyond 500 lines of code.

适用场景：简单工具类应用，或从Classic模式过渡的开发者
结构：逻辑直接写在
```
index.js
```
中
UI访问：在整个文件中直接使用
```
$
```
对象
优势：无需任何模板代码，启动速度极快
劣势：代码量超过500行后难以维护

Tier 2: Intermediate (Modular Alloy)

层级2：进阶版（模块化Alloy）

Best for: Standard commercial applications.
Structure: Business logic extracted to
```
app/lib/
```
using a flat technical-type organization.
Pattern: Slim Controllers that
```
require()
```
services.
Memory: Mandatory implementation of
```
$.cleanup = cleanup
```
.

适用场景：标准商业应用
结构：业务逻辑提取至
```
app/lib/
```
，按技术类型进行扁平组织
模式：轻量控制器，通过
```
require()
```
引入服务
内存管理：必须实现
```
$.cleanup = cleanup
```

Tier 3: Advanced / Enterprise (Service-Oriented)

层级3：高级版/企业版（面向服务）

Best for: High-complexity apps (IDEs like TiDesigner, multi-state platforms).
Architecture: Dependency Injection via a
```
ServiceRegistry
```
.
ID Scoping: Services do not receive the entire
```
$
```
object. They receive a "Scoped UI" object containing only relevant IDs.
Cognitive Load: "Black Box" logic—encapsulated units that reduce mental fatigue.
Observability: Structured logging with a mandatory
```
service
```
context.

Detailed examples and full implementation samples are available in: Architectural Tiers Detail

适用场景：高复杂度应用（如TiDesigner这类IDE、多状态平台应用）
架构：通过
```
ServiceRegistry
```
实现依赖注入
ID作用域：服务不接收完整的
```
$
```
对象，仅接收包含相关ID的“作用域UI对象”
认知负担：“黑盒”逻辑——封装的单元可降低脑力消耗
可观测性：结构化日志，且必须包含
```
service
```
上下文

详细示例与完整实现样例请查看：架构层级详情

Organization policy (low freedom)

组织规范（低自由度）

Use technical-type organization in

lib

(for example:

api

services

actions

repositories

helpers

policies

providers

Keep
```
lib
```
flat and predictable:
```
lib/<type>/<file>.js
```
only.
Do not recommend deep nesting like
```
lib/services/auth/session/login.js
```
.
Keep UI layers aligned by screen (
```
controllers/
```
,
```
views/
```
,
```
styles/
```
) and avoid unnecessary depth.

在
```
lib
```
目录中按技术类型组织文件（例如：
```
api
```
、
```
services
```
、
```
actions
```
、
```
repositories
```
、
```
helpers
```
、
```
policies
```
、
```
providers
```
）
保持
```
lib
```
目录扁平且可预测：仅使用
```
lib/<type>/<file>.js
```
结构
不推荐深度嵌套，如
```
lib/services/auth/session/login.js
```
UI层按页面保持对齐（
```
controllers/
```
、
```
views/
```
、
```
styles/
```
），避免不必要的层级

Code standards (low freedom)

代码规范（低自由度）

No semicolons: let ASI handle it
Modern syntax:
```
const/let
```
, destructuring, template literals
```
applyProperties()
```
: batch UI updates to reduce bridge crossings
Memory cleanup: any controller with global listeners must set
```
$.cleanup = cleanup
```
Error handling: use AppError classes, log with context, never swallow errors
Testable code: inject dependencies, avoid hard coupling

不使用分号：让ASI（自动分号插入）处理
使用现代语法：
```
const/let
```
、解构赋值、模板字符串
使用
```
applyProperties()
```
：批量更新UI以减少桥接交互
内存清理：任何包含全局监听器的控制器必须设置
```
$.cleanup = cleanup
```
错误处理：使用AppError类，携带上下文日志，绝不吞掉错误
可测试代码：注入依赖，避免硬耦合

Titanium style sheets rules (low freedom)

Titanium样式表规则（低自由度）

:::danger Critical: platform-specific properties require modifiers Using

Ti.UI.iOS.*

Ti.UI.Android.*

properties without platform modifiers breaks cross-platform builds.

Example of the damage:

tss

// Wrong: adds Ti.UI.iOS to Android project
"#mainWindow": {
  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
}

Correct: always use platform modifiers

tss

// Correct: only adds to iOS
"#mainWindow[platform=ios]": {
  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
}

Properties that always need platform modifiers:

iOS:

statusBarStyle

modalStyle

modalTransitionStyle

, any

Ti.UI.iOS.*

Android:
```
actionBar
```
configuration, any
```
Ti.UI.Android.*
```
constant

Available modifiers:

[platform=ios]

[platform=android]

[formFactor=handheld]

[formFactor=tablet]

[if=Alloy.Globals.customVar]

For more platform-specific patterns, see the

ti-ui

skill. :::

Titanium layout system:

Three layout modes:
```
layout: 'horizontal'
```
,
```
layout: 'vertical'
```
, and composite (default, no
```
layout
```
needed)
No padding on container Views: use margins on children instead
```
width: Ti.UI.FILL
```
fills available space (preferred),
```
width: '100%'
```
= 100% of parent
```
height: Ti.UI.SIZE
```
wraps content,
```
height: Ti.UI.FILL
```
fills available space

:::danger 重要提示：平台专属属性必须使用修饰符直接使用

Ti.UI.iOS.*

或

Ti.UI.Android.*

属性而不加平台修饰符会破坏跨平台构建。

错误示例：

tss

// 错误写法：会在Android项目中添加Ti.UI.iOS相关代码
"#mainWindow": {
  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
}

正确写法：始终使用平台修饰符

tss

// 正确写法：仅在iOS项目中生效
"#mainWindow[platform=ios]": {
  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
}

必须添加平台修饰符的属性：

iOS：

statusBarStyle

、

modalStyle

、

modalTransitionStyle

，所有

Ti.UI.iOS.*

属性

Android：
```
actionBar
```
配置，所有
```
Ti.UI.Android.*
```
常量

可用修饰符：

[platform=ios]

、

[platform=android]

、

[formFactor=handheld]

、

[formFactor=tablet]

、

[if=Alloy.Globals.customVar]

更多平台专属模式，请查看

ti-ui

技能文档。 :::

Titanium布局系统：

三种布局模式：
```
layout: 'horizontal'
```
、
```
layout: 'vertical'
```
，以及复合模式（默认，无需设置
```
layout
```
）
容器视图不设置内边距：改为在子元素上设置外边距
```
width: Ti.UI.FILL
```
填充可用空间（推荐使用），
```
width: '100%'
```
表示占父元素的100%宽度
```
height: Ti.UI.SIZE
```
自适应内容高度，
```
height: Ti.UI.FILL
```
填充可用空间

Alloy builtins quick reference

Alloy内置对象速查

Key builtins:

OS_IOS

OS_ANDROID

(compile-time),

Alloy.CFG

(config.json),

Alloy.Globals

(shared state),

$.args

(controller params),

$.destroy()

(cleanup bindings),

platform="ios"

formFactor="tablet"

(XML conditionals).

For the complete reference with examples, see Alloy builtins and globals.

核心内置对象：

OS_IOS

OS_ANDROID

（编译时）、

Alloy.CFG

（来自config.json）、

Alloy.Globals

（共享状态）、

$.args

（控制器参数）、

$.destroy()

（清理绑定）、

platform="ios"

formFactor="tablet"

（XML条件判断）

完整带示例的参考文档，请查看Alloy内置对象与全局变量。

Quick decision matrix

快速决策矩阵

Question	Answer
How to create a new Alloy project?	`ti create -t app --alloy` (not `--classic` + `alloy new` )
Fastest way to build?	`tn <recipe>` (using TiNy CLI wrapper)
Controller > 100 lines?	Extract to Tier 2 (Services)
More than 50 IDs in XML?	Use Tier 3 (ID Scoping)
Where does API call go?	`lib/api/`
Where does business logic go?	`lib/services/`
How deep should `lib` folders be?	One level: `lib/<type>/<file>.js`
Where do I store auth tokens?	Keychain (iOS) / KeyStore (Android) via service
Models or Collections?	Collections for API data, Models for SQLite persistence
Ti.App.fireEvent or EventBus?	Always EventBus (Backbone.Events)
Direct navigation or service?	Always Navigation service (auto cleanup)
Inline styles or TSS files?	Always TSS files (per-controller + `app.tss` for global)

问题	答案
如何创建新的Alloy项目？	`ti create -t app --alloy` （不要用 `--classic` + `alloy new` ）
最快的构建方式？	`tn <recipe>` （使用TiNy CLI包装器）
控制器代码超过100行？	提取至层级2（服务层）
XML中包含超过50个ID？	使用层级3（ID作用域）
API请求代码放在哪里？	`lib/api/`
业务逻辑放在哪里？	`lib/services/`
`lib` 文件夹的层级深度应为多少？	仅一层： `lib/<type>/<file>.js`
在哪里存储认证令牌？	通过服务存储到iOS的Keychain或Android的KeyStore中
选Models还是Collections？	API数据用Collections，SQLite持久化用Models
用Ti.App.fireEvent还是EventBus？	始终使用EventBus（Backbone.Events）
直接导航还是用服务？	始终使用导航服务（自动清理）
内联样式还是TSS文件？	始终使用TSS文件（按控制器划分 + 全局的 `app.tss` ）

Reference guides (progressive disclosure)

参考指南（渐进式披露）

Architecture & Patterns

架构与模式

Architectural Tiers Detail
Architectural Patterns (Factory, Singleton, Repository)
Structure & Organization
Contracts & Communication
State Management
Anti-patterns to Avoid

架构层级详情
架构模式（工厂模式、单例模式、仓库模式）
结构与组织
契约与通信
状态管理
需避免的反模式

Implementation & API

实现与API

Alloy Builtins & Globals
Code Conventions
Controller Patterns
Theming & Dark Mode
Migration Patterns
Examples Collection

Alloy内置对象与全局变量
代码规范
控制器模式
主题与暗黑模式
迁移模式
示例集合

Quality & Performance

质量与性能

Performance Optimization
ListView & ScrollView Performance
Error Handling & Logging
Unit & Integration Testing
E2E Testing & CI/CD

性能优化
ListView与ScrollView性能优化
错误处理与日志
单元与集成测试
端到端测试与CI/CD

Security

安全

Security Fundamentals
Device Security

安全基础
设备安全

Tools

工具

CLI Expert & TiNy

CLI专家与TiNy