• 在ArkUI框架中，狀態管理是構建動態交互應用的核心機制。@State、@Prop、@Link構成了狀態管理的核心三角，開發者可以高效地實現組件間狀態的聲明、傳遞與同步。

基本概念

1. @State 裝飾器

• 定位：用于聲明組件私有狀態變量，當狀態變化時自動觸發UI刷新。

• 生命周期：與組件生命周期綁定，組件銷毀后狀態失效。

• 數據類型支持：支持簡單類型（string/number/boolean）、復雜類型（Object/Array/Date/Map/Set）、聯合類型及ArkUI框架類型（如ResourceStr）。

• 觀察機制：僅能觀測到第一層屬性變化（如數組元素增減、對象屬性修改），深層嵌套需通過 @Observed 裝飾器增強。

• 多類型支持：支持聯合類型如@State data: string | number = 0

• 特性：

  • 僅組件內部可訪問，需本地初始化。
  • 與子組件 @Prop 單向同步，與 @Link 雙向同步。，但父組件無法直接訪問子組件的 @State。
  • Date/Map/Set：通過特定API（如setFullYear()、set()）修改可觸發刷新。
  • 避免深拷貝大對象：使用@Observed裝飾類增強觀測能力。
  • 使用UIUtils.getTarget()判斷是否需要更新狀態。

• 示例：管理組件內部狀態，如按鈕點擊計數

  @Component
  struct MyComponent {
    @State count: number = 0;
    
    build() {
      Button(`Clicked ${this.count} times`)
        .onClick(() => { this.count++ })
    }
  }
  

• 常見問題

  • 箭頭函數陷阱：

  // 錯誤：this指向代理對象而非組件實例
  vm.changeCoverUrl = () => { this.coverUrl = '#00F5FF'; };
  

  • 解決方案：

  vm.changeCoverUrl(self => self.coverUrl = '#00F5FF');
  

2. @Prop 裝飾器

• 定位：子組件通過@Prop聲明接收父組件的數據，單向同步且不可逆。

• 初始化規則：必須通過父組件初始化，本地初始化可選（但需顯式指定類型）。

• 類型安全：需與父組件數據源類型嚴格一致，否則無法觸發更新。

• 數據屏障：通過深拷貝（基礎類型）或引用傳遞（對象類型）建立父子組件間的單向通信（基礎類型（string/number/boolean）直接復制，復雜類型（object/class）僅復制引用）

• 嵌套場景：傳遞復雜類型時，避免深拷貝大對象，建議嵌套層數不超過 5 層，深層嵌套推薦使用 @ObjectLink。

• 特性：

  • 從父組件接收數據，本地修改不影響父組件。
  • 父組件必須通過命名參數初始化子組件。
  • 支持與 @State、@Link 等父組件狀態變量同步。
  • 深拷貝特性可能導致復雜類型數據丟失部分信息（如 PixelMap）。
  • 不支持在 @Entry 組件中使用。

• 深拷貝規則：

  類型	拷貝方式	注意事項
  Primitive	值拷貝	無需額外處理
  Array/Map/Set	引用拷貝+淺層遍歷	復雜類型需配合@Observed使用
  Class/Object	實例拷貝	需手動實現深拷貝（如clone）

• 嵌套類型處理：

  • 使用@Observed確保深層屬性可觀測。
  • 數組同步需保持類型一致性。

• 示例：接收父組件數據且不反向修改，如配置參數傳遞。

  @Component
  struct Child {
    @Prop config: { color: string };
    
    build() {
      Text('Hello').fontColor(this.config.color)
    }
  }
  
  @Entry
  @Component
  struct Parent {
    @State settings = { color: '#FF0000' };
    
    build() {
      Child({ config: this.settings })
    }
  }
  

• 常見問題

  • 未初始化錯誤：

  // 錯誤：@Prop未初始化且父組件未傳遞
  @Component struct Child {
    @Prop count: number; // 缺少初始化
  }
  

  • 解決方案：

  // 方案1：本地初始化
  @Prop count: number = 0;
  
  // 方案2：父組件必須傳遞
  Child({ count: this.stateCount });
  

3. @Link 裝飾器

• 定位：子組件通過@Link與父組件共享狀態變量，實現雙向數據綁定。

• 引用傳遞：直接綁定父組件的狀態變量引用

• 更新傳播：父→子、子→父雙向同步，支持跨多級組件傳遞（需配合@Provide/@Consume）

• 雙向同步陷阱：雙向綁定可能導致循環依賴，需謹慎設計父子組件通信邏輯。

• 生命周期共享：變量與父組件狀態強關聯，父組件銷毀后子組件鏈接失效。

• 特性：

  • 父組件必須通過命名參數初始化子組件（必須從父組件初始化，禁止本地初始化）。
  • 支持與 @State、@StorageLink 等雙向同步。
  • 對復雜類型（如對象、數組）的屬性修改可觸發雙向更新。
  • 需要與 @Observed 配合實現嵌套對象監聽。
  • 修改嵌套屬性需通過代理對象（避免直接操作原生對象）。

• 示例：父子組件共同維護同一狀態，如表單雙向綁定。

  @Component
  struct InputField {
    @Link value: string;
    
    build() {
      TextInput({ text: this.value })
        .onChange((val) => { this.value = val })
    }
  }
  
  @Entry
  @Component
  struct FormPage {
    @State inputValue: string = '';
    
    build() {
      InputField({ value: $inputValue })
    }
  }
  

• 常見問題與解決方案

  • 狀態更新未觸發：直接修改嵌套屬性未通過代理

  // 錯誤：直接修改嵌套屬性
  this.obj.property = newValue;
  
  // 正確：通過臨時變量觸發代理
  let temp = this.obj;
  temp.property = newValue;
  this.obj = { ...temp };
  

對比分析

總結

1. 優先選擇@State：組件狀態管理的基石，適用于私有狀態維護。
2. 謹慎使用@Prop：實現父組件到子組件的單向數據分發，適合配置傳遞，避免過度嵌套和復雜類型。
3. 雙向綁定用@Link：提供雙向同步能力，適用于實時交互場景（如表單、搜索框聯動），需嚴格匹配數據類型，避免沖突。
4. 性能優化：
   • 對復雜對象使用 @Observed, 減少不必要的代理開銷。
   • 避免在build()方法中修改狀態。
   • 避免大規模數據的深拷貝
   • 使用不可變數據結構
5. 調試技巧：
   • 使用 @Watch 監聽變化
   • 通過日志輸出狀態變更軌跡
   • 檢查裝飾器是否遺漏初始化參數。
   • 使用TypeScript嚴格模式避免類型錯誤。
   • 利用開發者工具的 State Inspector

通過深入理解這三個裝飾器的特性和適用場景，開發者可以構建出高效、可維護的 ArkUI 應用。在實際項目中，建議結合具體業務需求靈活選擇，同時注意狀態管理的邊界劃分，避免過度耦合。

我是今陽，如果想要進階和了解更多的干貨，歡迎關注 “今陽說” 接收我的最新文章