---
description: UTS 与 TypeScript 语法差异规则指南
globs: **/*.uts, **/*.uvue
alwaysApply: false
---

# UTS 与 TypeScript 语法差异规则指南

适用于 AI 编程工具（如 Cursor）的参考规则

---

## 概述

UTS 是 uni-app x 的跨端开发语言，需要编译为原生语言（Kotlin/Swift），因此比 TypeScript 更严格。本规则指南帮助 AI 工具正确识别和转换 TS 代码到 UTS。

### 核心原则
1. **强类型要求**：UTS 是完全的静态类型语言，所有类型在编译时必须已知
2. **名义类型系统**：采用名义类型（nominal typing）而非结构化类型（structural typing）
3. **跨平台一致性**：代码需同时支持 Android（Kotlin）和 iOS（Swift）平台

---

## 一、核心语言特性规则

### 1. 不支持 undefined
- **规则**：所有变量必须赋值初始化后才能使用
- **替代方案**：使用 `null` 表示空值
- **示例**：
  ```typescript
  // ❌ 错误写法
  let value: string | undefined;
  
  // ✅ 正确写法
  let value: string | null = null;
  ```

### 2. 条件语句必须使用布尔类型
- **规则**：if/while/for 等条件语句必须使用布尔表达式
- **禁止**：隐式类型转换、truthy/falsy 值
- **示例**：
  ```typescript
  // ❌ 错误
  if (1) { }
  while ("") { }
  
  // ✅ 正确
  if (x > 0) { }
  while (isValid) { }
  ```

### 3. 对象字面量默认为 UTSJSONObject 类型
- **规则**：未明确类型的对象字面量推导为 `UTSJSONObject`
- **影响**：不能直接使用点运算符访问属性
- **最佳实践**：使用 `type` 定义具体类型
  ```typescript
  // 推荐使用 type
  type Person = { name: string; age: number };
  const person: Person = { name: "John", age: 30 };
  ```

### 4. 对象字面量仅支持 type 定义
- **规则**：对象字面量赋值只能给 `type` 定义的类型
- **禁止**：赋值给 `interface` 定义的类型

### 5. 不支持变量和函数提升（Hoisting）
- **规则**：必须先声明后使用
- **影响**：不能访问未声明的变量或函数

### 6. 使用 let 而非 var
- **规则**：优先使用 `let` 或 `const`
- **原因**：`var` 在不同平台行为不一致

---

## 二、类型系统规则

### 1. 对象字面量不能用于类型声明
- **规则**：类型声明必须使用 `type`、`class` 或 `interface`
- **示例**：
  ```typescript
  // ❌ 错误
  let o: { x: number; y: number } = { x: 2, y: 3 };
  
  // ✅ 正确
  type O = { x: number; y: number };
  let o: O = { x: 2, y: 3 };
  ```

### 2. type 定义对象类型时不支持嵌套对象字面量
- **规则**：需要提取嵌套对象定义独立的 type

### 3. 使用具体类型而非 unknown
- **规则**：不能声明类型为 `unknown`
- **替代方案**：使用 `any` 或具体类型

### 4. 不支持条件类型、映射类型、Utility Types
- **规则**：不能使用 Partial、Readonly、Pick、Omit 等
- **替代方案**：手动定义等效类型

### 5. 不支持 as const 断言和确定赋值断言
- **替代方案**：显式声明类型，声明时同时赋值

### 6. 类型别名不能出现在局部作用域
- **规则**：`type` 定义必须在顶层作用域

---

## 三、类和对象规则

### 1. 不支持以 # 开头的私有字段
- **规则**：使用 `private` 关键字替代

### 2. class 不支持通过索引访问字段
- **规则**：只能访问已声明的字段，不支持动态访问

### 3. 不支持静态块
- **替代方案**：使用静态方法

### 4. class 不能被用作对象
- **规则**：class 声明的是类型，不是值

### 5. 类继承时必须显式声明构造器
- **规则**：继承类时必须显式调用父类构造器

### 6. 类不允许 implements 类，接口不能继承类
- **规则**：只能接口被 implements，接口只能继承接口

### 7. 接口不能出现在局部作用域
- **规则**：接口定义必须在顶层作用域

### 8. Enum 成员初始化器仅支持数字或字符串常量
- **规则**：enum 不能在函数内部声明

---

## 四、函数规则

### 1. 使用 class 而非具有 call signature 的类型
- **替代方案**：使用类实现 `invoke` 方法

### 2. 函数声明不能作为值使用
- **替代方案**：使用函数表达式或箭头函数

### 3. 不支持对函数声明属性
- **替代方案**：使用类封装

### 4. 不支持 Function.apply 和 Function.call

---

## 五、其他重要规则

### 1. 不支持结构化类型系统
- **规则**：采用名义类型系统，类型兼容性基于类型名称

### 2. any 类型的特殊处理
- **特点**：表示"任意的非空类型"，使用时需要类型转换

---

## 总结

核心原则：
1. **严格类型检查**：所有变量必须明确类型，不能使用 `undefined`
2. **显式优于隐式**：避免隐式类型转换，显式声明类型
3. **类优先**：优先使用 `class` 和 `type`，而非 `interface` 或对象字面量
4. **顶层声明**：所有类型定义必须在顶层作用域
5. **强类型约束**：条件语句、函数参数等必须使用明确类型
6. **跨平台兼容**：确保代码在 Kotlin 和 Swift 平台都能编译通过

更多参考: [uts与ts的差异](https://doc.dcloud.net.cn/uni-app-x/uts/uts_diff_ts.html)