alloy-guides

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Alloy MVC framework guide

Alloy MVC框架指南

Reference for building Titanium mobile applications with the Alloy MVC framework and Backbone.js.

使用Alloy MVC框架和Backbone.js构建Titanium移动应用的参考文档。

Project detection

项目检测

:::info AUTO-DETECTS ALLOY PROJECTS This skill automatically detects Alloy projects when invoked and provides framework-specific guidance.

Detection occurs automatically - no manual command needed.

Alloy project indicators:

```
app/
```
folder (MVC structure)
```
app/views/
```
,
```
app/controllers/
```
folders
```
app/models/
```
folder

Behavior based on detection:

Alloy detected → Provides Alloy MVC documentation, Backbone.js patterns, TSS styling, widgets
Not detected → Indicates this skill is for Alloy projects only, does not suggest Alloy-specific features :::

:::info 自动检测Alloy项目调用此技能时会自动检测Alloy项目，并提供框架专属指导。

检测自动进行 - 无需手动执行命令。

Alloy项目标识：

```
app/
```
文件夹（MVC结构）
```
app/views/
```
、
```
app/controllers/
```
文件夹
```
app/models/
```
文件夹

基于检测结果的行为：

检测到Alloy项目 → 提供Alloy MVC文档、Backbone.js模式、TSS样式、组件相关内容
未检测到Alloy项目 → 提示此技能仅适用于Alloy项目，不会提供Alloy专属功能建议 :::

Quick reference

快速参考

Topic	Reference File
Core concepts, MVC, Backbone.js, conventions	CONCEPTS.md
Controllers, events, conditional code, arguments	CONTROLLERS.md
Models, collections, data binding, migrations	MODELS.md
XML markup, elements, attributes, events	VIEWS_XML.md
TSS styling, themes, platform-specific styles	VIEWS_STYLES.md
Dynamic styles, autostyle, runtime styling	VIEWS_DYNAMIC.md
Controllers-less views, patterns	VIEWS_WITHOUT_CONTROLLERS.md
Creating and using widgets	WIDGETS.md
CLI commands, code generation	CLI_TASKS.md
PurgeTSS integration (optional addon)	PURGETSS.md

主题	参考文档
核心概念、MVC、Backbone.js、约定规范	CONCEPTS.md
控制器、事件、条件代码、参数	CONTROLLERS.md
模型、集合、数据绑定、迁移	MODELS.md
XML标记、元素、属性、事件	VIEWS_XML.md
TSS样式、主题、平台专属样式	VIEWS_STYLES.md
动态样式、自动样式、运行时样式	VIEWS_DYNAMIC.md
无控制器视图、模式	VIEWS_WITHOUT_CONTROLLERS.md
组件创建与使用	WIDGETS.md
CLI命令、代码生成	CLI_TASKS.md
PurgeTSS集成（可选插件）	PURGETSS.md

Project structure

项目结构

Standard Alloy project structure:

app/
├── alloy.js              # Initializer file
├── alloy.jmk             # Build configuration
├── config.json           # Project configuration
├── assets/               # Images, fonts, files (→ Resources/)
├── controllers/          # Controller files (.js)
├── i18n/                 # Localization strings (→ i18n/)
├── lib/                  # CommonJS modules
├── migrations/           # DB migrations (<DATETIME>_<name>.js)
├── models/               # Model definitions (.js)
├── platform/             # Platform-specific resources (→ platform/)
├── specs/                # Test-only files (dev/test only)
├── styles/               # TSS files (.tss)
├── themes/               # Theme folders
├── views/                # XML markup files (.xml)
└── widgets/              # Widget components

标准Alloy项目结构：

app/
├── alloy.js              # 初始化文件
├── alloy.jmk             # 构建配置
├── config.json           # 项目配置
├── assets/               # 图片、字体、文件（→ Resources/）
├── controllers/          # 控制器文件 (.js)
├── i18n/                 # 本地化字符串（→ i18n/）
├── lib/                  # CommonJS模块
├── migrations/           # 数据库迁移文件 (<DATETIME>_<name>.js)
├── models/               # 模型定义文件 (.js)
├── platform/             # 平台专属资源（→ platform/）
├── specs/                # 测试专用文件（仅开发/测试环境）
├── styles/               # TSS文件 (.tss)
├── themes/               # 主题文件夹
├── views/                # XML标记文件 (.xml)
└── widgets/              # 组件

MVC quick start

MVC快速入门

Controller (

app/controllers/index.js

javascript

function doClick(e) {
    alert($.label.text);
}
$.index.open();

View (

app/views/index.xml

xml

<Alloy>
    <Window class="container">
        <Label id="label" onClick="doClick">Hello, World</Label>
    </Window>
</Alloy>

Style (

app/styles/index.tss

javascript

".container": { backgroundColor: "white" }
"Label": { color: "#000" }

控制器 (

app/controllers/index.js

javascript

function doClick(e) {
    alert($.label.text);
}
$.index.open();

视图 (

app/views/index.xml

xml

<Alloy>
    <Window class="container">
        <Label id="label" onClick="doClick">Hello, World</Label>
    </Window>
</Alloy>

样式 (

app/styles/index.tss

javascript

".container": { backgroundColor: "white" }
"Label": { color: "#000" }

Key concepts

核心概念

Models/Collections: Backbone.js objects with sync adapters (sql, properties)
Views: XML markup with TSS styling
Controllers: JavaScript logic with
```
$
```
reference to view components
Data Binding: Bind collections to UI components automatically
Widgets: Reusable components with MVC structure
Conventions: File naming and placement drive code generation

模型/集合：带有同步适配器（sql、properties）的Backbone.js对象
视图：采用TSS样式的XML标记
控制器：带有
```
$
```
引用视图组件的JavaScript逻辑
数据绑定：自动将集合与UI组件绑定
组件：具备MVC结构的可复用组件
约定规范：文件命名和存放位置驱动代码生成

Critical rules

关键规则

Platform-specific properties in TSS

TSS中的平台专属属性

:::danger CRITICAL: Platform-specific properties require modifiers Using

Ti.UI.iOS.*

Ti.UI.Android.*

properties in TSS without platform modifiers causes cross-platform compilation failures.

Example of the failure:

tss

// WRONG - Adds Ti.UI.iOS to Android project
"#mainWindow": {
  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT  // FAILS on Android!
}

Correct approach - use platform modifiers:

tss

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

// CORRECT - Only adds to Android
"#mainWindow[platform=android]": {
  actionBar: {
    displayHomeAsUp: true
  }
}

Properties that always require platform modifiers:

iOS:

statusBarStyle

modalStyle

modalTransitionStyle

, any

Ti.UI.iOS.*

Android:
```
actionBar
```
config, 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 Code conventions (ti-expert) or Platform UI guides (ti-ui). :::

:::danger 重要提示：平台专属属性需要使用修饰符在TSS中使用

Ti.UI.iOS.*

或

Ti.UI.Android.*

属性时，如果不添加平台修饰符，会导致跨平台编译失败。

错误示例：

tss

// 错误 - 会在Android项目中添加Ti.UI.iOS相关代码
"#mainWindow": {
  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT  // 在Android上会失败！
}

正确做法 - 使用平台修饰符：

tss

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

// 正确 - 仅在Android项目中生效
"#mainWindow[platform=android]": {
  actionBar: {
    displayHomeAsUp: true
  }
}

必须使用平台修饰符的属性：

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-expert）或平台UI指南（ti-ui）。 :::

Common patterns

常见模式

Creating a model

创建模型

bash

alloy generate model book sql title:string author:string

bash

alloy generate model book sql title:string author:string

Data binding

数据绑定

xml

<Collection src="book" />
<TableView dataCollection="book">
    <TableViewRow title="{title}" />
</TableView>

xml

<Collection src="book" />
<TableView dataCollection="book">
    <TableViewRow title="{title}" />
</TableView>

Platform-specific code

平台专属代码

javascript

if (OS_IOS) {
    // iOS-only code
}
if (OS_ANDROID) {
    // Android-only code
}

javascript

if (OS_IOS) {
    // iOS专属代码
}
if (OS_ANDROID) {
    // Android专属代码
}

Widget usage

组件使用

xml

<Widget src="mywidget" id="foo" />

xml

<Widget src="mywidget" id="foo" />

Compilation process

编译流程

Cleanup: Resources folder cleaned
Build Config: alloy.jmk loaded (pre:load task)
Framework Files: Backbone.js, Underscore.js, sync adapters copied
MVC Generation: Models, widgets, views, controllers compiled to JS
Main App: app.js generated from template
Optimization: UglifyJS optimization, platform-specific code removal

清理：清理Resources文件夹
构建配置：加载alloy.jmk（pre:load任务）
框架文件：复制Backbone.js、Underscore.js、同步适配器
MVC生成：将模型、组件、视图、控制器编译为JS
主应用：从模板生成app.js
优化：UglifyJS优化、移除平台专属代码

References

参考资料

Read detailed documentation from the reference files listed above based on your specific task.

根据具体任务，查看上述列出的参考文档获取详细内容。

Task	Use This Skill
Modern architecture, services, patterns	`ti-expert`
Alloy CLI, config files, debugging errors	`alloy-howtos`
Utility-first styling with PurgeTSS (optional)	`purgetss`
Native features (location, push, media)	`ti-howtos`

任务	使用对应技能
现代架构、服务、模式	`ti-expert`
Alloy CLI、配置文件、调试错误	`alloy-howtos`
使用PurgeTSS的实用优先样式（可选）	`purgetss`
原生功能（定位、推送、媒体）	`ti-howtos`

alloy-guides

Original

Translation

Alloy MVC framework guide

Alloy MVC框架指南

Project detection

项目检测

Quick reference

快速参考

Project structure

项目结构

MVC quick start

MVC快速入门

Key concepts

核心概念

Critical rules

关键规则

Platform-specific properties in TSS

TSS中的平台专属属性

Common patterns

常见模式

Creating a model

创建模型

Data binding

数据绑定

Platform-specific code

平台专属代码

Widget usage

组件使用

Compilation process

编译流程

References

参考资料

Related skills

相关技能