ArkTS 开发指南

MyApp/
├── AppScope/
│   └── app.json5                  // 全局应用配置
├── entry/                         // 主模块（HAP）
│   └── src/main/
│       ├── ets/                   // ArkTS 源码
│       │   ├── entryability/
│       │   │   └── EntryAbility.ets
│       │   ├── pages/             // 页面
│       │   │   ├── Index.ets
│       │   │   └── Detail.ets
│       │   ├── components/         // 自定义组件
│       │   ├── model/             // 数据模型
│       │   └── utils/             // 工具类
│       └── resources/             // 资源（图片/字符串/布局）
├── oh-package.json5              // 依赖配置（类似 package.json）
└── build-profile.json5           // 构建配置

interface Person {
  name: string
  age: number
}

// 不需要 implements Person！
// 只要结构匹配就能赋值
let p: Person = {
  name: 'Alice',
  age: 18
}

// class 也能赋值给 interface（结构匹配即可）
class User {
  name: string = ''
  age: number = 0
}
let u: Person = new User()  // ✅ 结构匹配

// ❌ 默认不允许 null
let name: string = null  // 编译错误

// ✅ 显式标注可空
let name: string | null = null

// 空值合并运算符（类似 Optional.orElse）
let display = name ?? 'unknown'

// 可选链（类似 Optional.map）
let len = name?.length  // name 为 null 时返回 undefined，不报错

let name = 'Alice'
let age = 18

// 模板字符串（反引号）
let msg = `Name: ${name}, Age: ${age}`

// 多行字符串
let html = `<div>
  <p>${name}</p>
</div>`

// 表达式嵌入
let result = `Total: ${items.reduce((a, b) => a + b, 0)}`

class Counter {
  count: number = 0

  // ❌ 普通函数：this 不指向 Counter
  bad() {
    setTimeout(function() {
      this.count++  // this 是 undefined 或全局对象！
    }, 1000)
  }

  // ✅ 箭头函数：this 继承自 Counter
  good() {
    setTimeout(() => {
      this.count++  // this 指向 Counter 实例 ✅
    }, 1000)
  }
}

// ArkTS 不支持 TS 的 constructor(public x: number) 简写
// 必须显式声明字段 + 赋值

class User {
  name: string
  age: number

  constructor(name: string, age: number) {
    this.name = name
    this.age = age
  }
}

// 或者用对象字面量 + interface 替代 class
interface User { name: string; age: number }
const user: User = { name: 'Alice', age: 18 }

let arr: number[] = [3, 1, 2]

// 添加/删除
arr.push(4)           // 尾部添加
arr.pop()              // 尾部删除
arr.unshift(0)         // 头部添加
arr.shift()             // 头部删除
arr.splice(1, 1)        // 索引1删1个

// 查找
arr.includes(2)         // true
arr.indexOf(2)           // 2
arr.find(x => x > 1)       // 3（第一个满足条件的）

// 变换
arr.sort((a, b) => a - b) // 排序（原地）
arr.reverse()            // 反转（原地）
let sliced = arr.slice(0, 2)  // 截取（返回新数组）

// 展开（类似 Java 的 list.addAll）
let combined = [...arr, 5, 6]

// 解构赋值
let [a, b, ...rest] = [1, 2, 3, 4]
// a=1, b=2, rest=[3,4]

@Component
struct Counter {
  @State count: number = 0

  build() {
    Column() {
      Text(`Count: ${this.count}`)
        .fontSize(30)

      Button('+1')
        .onClick(() => {
          this.count++  // 修改 @State → UI 自动刷新！
        })
    }
  }
}

@Component
struct Parent {
  @State name: string = 'Alice'

  build() {
    Column() {
      Button('改名').onClick(() => {
        this.name = 'Bob'  // 父改 → 子也刷新
      })
      Child({ name: this.name })  // 传递给子组件
    }
  }
}

@Component
struct Child {
  @Prop name: string  // 只读，子组件不能修改

  build() {
    Text(`Hello, ${this.name}`)
  }
}

@Component
struct Parent {
  @State count: number = 0

  build() {
    Column() {
      Text(`Parent: ${this.count}`)
      Child({ count: this.count })  // 注意：传 $ 引用
    }
  }
}

@Component
struct Child {
  @Link count: number  // 双向绑定，可修改

  build() {
    Column() {
      Text(`Child: ${this.count}`)
      Button('+1').onClick(() => {
        this.count++  // 子改 → 父也刷新！
      })
    }
  }
}

@Component
struct GrandParent {
  @Provide theme: string = 'dark'

  build() {
    Column() {
      Parent()   // 不需要逐层传 theme
    }
  }
}

@Component
struct DeepChild {
  @Consume theme: string  // 直接消费祖先的数据

  build() {
    Text('Theme:').fontColor(this.theme === 'dark' ? '#fff' : '#000')
  }
}

@Observed
class User {
  name: string
  age: number

  constructor(name: string, age: number) {
    this.name = name
    this.age = age
  }
}

@Component
struct UserCard {
  @ObjectLink user: User  // 监听 User 对象属性变化

  build() {
    Column() {
      Text(`${this.user.name}, ${this.user.age}`)
    }
  }
}

@Component
struct Parent {
  @State user: User = new User('Alice', 18)

  build() {
    Column() {
      UserCard({ user: this.user })
      Button('长大一岁').onClick(() => {
        this.user.age++  // UserCard 自动刷新
      })
    }
  }
}

@Component
struct UserList {
  @State users: Array<string> = ['Alice', 'Bob', 'Carol']

  build() {
    Column() {
      Text('用户列表').fontSize(20)

      ForEach(this.users, (name: string, index: number) => {
        Text(`${index + 1}. ${name}`)
          .fontSize(16)
          .padding(12)
          .onClick(() => {
            Console.info(`点击了 ${name}`)
          })
      }, (name: string) => name)  // keyGenerator（唯一键）
    }
  }
}

build() {
  Column() {
    if (this.isLoading) {
      Text('加载中...')
    } else if (this.data === null) {
      Text('暂无数据')
    } else {
      Text(this.data)
    }
  }
}

@Component
struct Card {
  @BuilderParam content: () => void

  build() {
    Column() {
      Text('--- Card Header ---')
      this.content()  // 父组件传入的内容在这里渲染
      Text('--- Card Footer ---')
    }
    .border({ width: 1 })
  }
}

// 使用
build() {
  Card() {
    Text('自定义内容')
    Image('logo.png')
  }
}

@Extend(Text)
function highlight(color: string, size: number) {
  .fontColor(color)
  .fontSize(size)
  .fontWeight(FontWeight.Bold)
}

// 使用：Text 专属扩展方法
build() {
  Text('重要').highlight('#ff0000', 18)
}

// entry/src/main/resources/base/profile/main_pages.json
{
  "src": ["pages/Index", "pages/Detail", "pages/Settings"]
}

@Entry
@Component
struct DetailPage {
  @State data: string = ''

  // 组件创建后、build 前调用
  aboutToAppear() {
    this.loadData()
  }

  // 组件销毁前
  aboutToDisappear() {
    Console.info('DetailPage destroyed')
  }

  // 页面重新显示（从其他页面返回）
  onPageShow() {
    Console.info('Page shown')
  }

  // 返回键拦截
  onBackPress(): boolean {
    return true  // true = 拦截，不执行默认返回
  }

  build() { ... }
}

// 创建 Promise（类似 CompletableFuture.supplyAsync）
function fetchUser(id: number): Promise<User> {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (id > 0) {
        resolve({ name: 'Alice', age: 18 })
      } else {
        reject(new Error('Invalid id'))
      }
    }, 1000)
  })
}

// 方式1：then/catch（类似 CompletableFuture 链）
fetchUser(1)
  .then(user => Console.info(user.name))
  .catch(err => Console.error(err))

// 方式2：async/await（推荐，更可读）
async function main() {
  try {
    const user = await fetchUser(1)
    Console.info(user.name)
  } catch (e) {
    Console.error(`Failed: ${e}`)
  }
}

async function loadAll() {
  // 并发发起 3 个请求，全部完成后继续
  const [user, posts, friends] = await Promise.all([
    fetchUser(1),
    fetchPosts(1),
    fetchFriends(1)
  ])
  // 三个结果同时可用
}

// 任一完成即返回
const fastest = await Promise.race([
  fetchFromCache(),
  fetchFromNetwork()
])

import { taskpool } from '@kit.ArkTS'

// 在 TaskPool 中执行的函数（不能访问主线程的变量）
@Concurrent
function heavyCompute(n: number): number {
  let sum = 0
  for (let i = 0; i < n; i++) {
    sum += i
  }
  return sum
}

// 在主线程调用
async function main() {
  const result = await taskpool.execute(heavyCompute, 100000000)
  Console.info(`Result: ${result}`)
}

// 主线程
import { worker } from '@kit.ArkTS'

const w = new worker.ThreadWorker('workers/CalcWorker.ets')

// 发送消息给 Worker
w.postMessage({ data: 42 })

// 接收 Worker 的消息
w.onmessage = (e) => {
  Console.info(`Worker result: ${e.data}`)
}

// workers/CalcWorker.ets（Worker 线程）
const w: worker.ThreadWorkerGlobalScope = worker.workerInstance
w.onmessage = (e) => {
  const result = e.data * 2
  w.postMessage(result)
}