鴻蒙開發——1、ArkTS聲明式開發:UI范式基本語法

• • @[TOC](鴻蒙開發——1、ArkTS聲明式開發:UI范式基本語法)
  • 一、ArkTS的基本組成
  • • （1）核心概念（像貼標簽一樣控制組件）
    • （2）基礎工具包（現成的積木塊）
    • （3）高效開發技巧（進階工具箱）
    • （4）常見誤區提醒及類比理解
  • 二、聲明式UI描述（ 給組件"搭積木"的入門指南）
  • • （1）🧱創建組件（像拼樂高一樣簡單）
    • （2）🎨配置屬性（給組件穿衣服）
    • （3）🕹?配置事件（給按鈕裝開關）
    • （4）🎁 配置子組件（俄羅斯套娃）
    • （5）💡避坑指南
  • 三、🧩自定義組件的通俗指南
  • • （1）什么是自定義組件？
    • （2）為什么需要自定義組件？
    • （3）快速入門案例
    • （4）🛠? 組件建造說明書
    • • 組件結構三要素
      • 裝飾器的作用
      • 構建規則（易錯點）
    • （5）🎨 樣式與交互技巧
    • • 鏈式調用設置樣式
      • 組件樣式繼承的坑
    • （6）?? 常見問題急救包
    • （7）🌰 實戰案例：計數器組件
    • 🚀 進階技巧

一、ArkTS的基本組成

（1）核心概念（像貼標簽一樣控制組件）

• 裝飾器（給代碼貼魔法標簽）
  ? @Component：相當于給代碼塊貼個“可復用組件”標簽。比如你寫了個按鈕樣式，貼上這個標簽后，整個程序都能重復使用這個按鈕。

  ? @Entry：相當于“主入口”標簽，告訴系統：“這個組件是App啟動時第一個顯示的界面”。

  ? @State：相當于“自動刷新”標簽。比如你在購物車數字上貼了這個標簽，當數量變化時，界面會自動更新顯示最新數值。

• UI描述（像寫菜譜一樣寫界面）
  用簡單直白的代碼描述界面結構，比如：

  build() {Column() { // 豎著排列Text("你好！").fontSize(20) // 文字Button("點擊我").onClick(() => { 操作代碼 }) // 按鈕}
  }
  

  就像寫菜譜說“先放文字，再放按鈕”一樣直觀。

---

（2）基礎工具包（現成的積木塊）

• 系統組件（開箱即用的積木）
  ? 基礎積木：文字(Text)、圖片(Image)、按鈕(Button)

  ? 排列工具：

  Column（豎排：像疊漢堡）  Row（橫排：像排隊）  Stack（疊放：像貼紙一樣層層疊加）RelativeContainer（相對布局：支持容器內部的子元素設置相對位置關系，適用于處理界面復雜的場景，對多個子元素進行對齊和排列。子元素可以指定兄弟元素或父容器作為錨點，基于錨點進行相對位置布局。）
  

• 屬性鏈式調用（像串珠子一樣設置樣式）
  連續設置多個屬性：

  Text("標題").fontSize(24)       // 字號24.fontColor("#FF0000") // 紅色.margin({top:10})   // 上方留10像素空白
  

  就像給文字戴項鏈，一顆接一顆地加裝飾。

• 事件綁定（給按鈕裝開關）
  給組件添加交互功能：

  Button("提交").onClick(() => { 提交數據 }) // 點擊事件.onLongPress(() => { 彈出菜單 }) // 長按事件
  

  相當于給按鈕裝了兩個觸發器：短按和長按分別觸發不同操作。

---

（3）高效開發技巧（進階工具箱）

• @Builder（打造自己的積木模具）
  把常用的界面片段打包成模板：

  @Builder
  function RedButton(text:string) {Button(text).backgroundColor("#FF0000")
  }
  // 使用時直接調用
  RedButton("危險操作")
  

  相當于做了一個紅色按鈕的模具，隨用隨取。

• @Styles/@Extend（批量改裝修飾）
  ? 統一風格：給所有標題設置統一樣式，類似于CSS中的類樣式

  @Styles function titleStyle() {.fontSize(20).fontColor("#333")
  }
  Text("標題1").titleStyle()
  

  ? 擴展組件：給系統按鈕添加圓角

  @Extend(Button)
  function roundButton() {.borderRadius(8)
  }
  

• 狀態樣式（智能變裝術）
  根據組件狀態自動切換樣式：

  Button("登錄").stateStyles({normal: { backgroundColor: "#EEE" }, // 默認灰色pressed: { backgroundColor: "#CCC" } // 按下變深灰})
  

  就像按鈕被按下時會“變色回應”你的操作。

---

（4）常見誤區提醒及類比理解

1. 裝飾器順序：@Entry必須放在最外層，像信封的收件人地址要寫在最上面
2. 狀態管理：只有被@State標記的變量變化才會觸發界面刷新，普通變量修改不會更新顯示
3. 鏈式調用：屬性設置順序有時會影響效果（比如先設寬度再設邊距可能導致布局錯位）

類比理解：
開發界面就像裝修房子：

• 裝飾器是各種功能標簽（如“承重墻”“可拆卸隔斷”）
• 系統組件是現成的家具（桌子、椅子）
• @Builder是自己設計的定制家具圖紙
• 狀態樣式是智能家居系統（天黑自動開燈）

二、聲明式UI描述（ 給組件"搭積木"的入門指南）

（1）🧱創建組件（像拼樂高一樣簡單）

兩種組裝方式：

1. 無參數組件（空手組裝）

   Divider() // 直接寫組件名加空括號，就像拼一根直線
   

   適合不需要額外參數的組件，比如分割線、空白間隔

2. 有參數組件（帶說明書組裝）

   // 圖片必須帶地址參數
   Image('https://example.com/cat.jpg') // 相當于給圖片框塞照片// 文字可以不帶內容（顯示空文本）
   Text() // 相當于一個隱形的文字占位符
   

參數小技巧：

• 可以插入變量或算式：

  Image(this.userAvatar) // 使用變量里的圖片地址
  Text(`剩余次數：${5 - this.count}`) // 顯示動態計算結果
  

（2）🎨配置屬性（給組件穿衣服）

連續點選設置法：

Text('你好世界').fontSize(20)          // 文字大小.fontColor('#FF0000')  // 文字顏色.margin({top:10})      // 上方留10像素空白

就像給洋娃娃穿衣服：先穿裙子，再戴帽子，最后穿鞋子

顏色/樣式快捷選項：

Text('特別提示').fontColor(Color.Red)     // 使用預定義紅色.fontWeight(FontWeight.Bold) // 直接選"加粗"模式

（3）🕹?配置事件（給按鈕裝開關）

箭頭函數用法：

Button('點我抽獎').onClick(() => {this.luckyNumber = Math.random() // 點擊后生成隨機數})

相當于給按鈕裝了個"按下就執行"的魔法開關，箭頭函數內部的this是詞法作用域，由上下文確定。匿名函數可能會有this指向不明確問題，在ArkTS中不允許使用。

錯誤用法提醒：

// ? 不要用普通函數
Button('錯誤示例').onClick(function() {// 這里的this會指向錯誤的地方！})// ? 正確用箭頭函數
Button('正確示例').onClick(() => {// 箭頭函數自動綁定正確上下文})

（4）🎁 配置子組件（俄羅斯套娃）

容器組件用法：

Column() { // 創建一個垂直排列的容器Text('標題').fontSize(24)      // 第一個子組件Divider()                    // 中間加分割線Image('logo.png').width(100) // 最后放圖片
}

像往抽屜里放東西：先放書本，再放文具，最后放零食

多層嵌套示例：

Column() {Row() { // 橫向排列容器Image('頭像.jpg').width(50)Text('張三').fontSize(16)}Grid() { // 網格布局Image('產品1.jpg')Image('產品2.jpg')Image('產品3.jpg')}
}

（5）💡避坑指南

• 組件創建不用new

  // ? 正確
  Text('你好')
  // ? 錯誤
  new Text('你好')
  

• 樣式設置順序不影響（大部分情況）

  // 這兩種寫法效果相同
  Text().fontSize(20).color('red')
  Text().color('red').fontSize(20)
  

• 容器組件必須包含內容

  // ? 正確用法
  Column() {Text('內容')
  }
  // ? 空容器會報錯
  Column()
  

類比理解：
開發界面就像玩裝修游戲：

• 組件是各種家具（按鈕=臺燈，圖片=掛畫）
• 屬性是家具的皮膚（顏色/尺寸/位置）
• 事件是家具的互動功能（點擊臺燈會亮）
• 容器是房間布局（書架=垂直排列，電視柜=水平排列）

三、🧩自定義組件的通俗指南

（1）什么是自定義組件？

就像搭樂高積木，系統組件是現成的積木塊，而自定義組件是開發者自己設計的特殊積木。它能組合多個積木、重復使用，還能根據數據變化自動更新外觀。

（2）為什么需要自定義組件？

1. 代碼復用：像寫好的菜譜，重復使用不重寫代碼
2. 邏輯分離：把界面和數據處理分開，像把食材和烹飪步驟分開
3. 維護方便：改一個地方，所有用到的地方自動更新

（3）快速入門案例

// 定義一個會變色的問候組件
@Component 
struct HelloComponent {@State message: string = 'Hello!'; // 會變的數據build() {Row() {Text(this.message).onClick(() => {this.message = '你戳我干嘛~'; // 點擊后文字變化})}}
}// 在頁面中使用
@Entry
@Component
struct MainPage {build() {Column() {HelloComponent()  // 使用自定義組件HelloComponent({ message: '你好呀！' }) // 傳入不同參數}}
}

---

（4）🛠? 組件建造說明書

組件結構三要素

@Component                // 🏷? 組件身份證
struct MyComponent {       // 🏗? 組件骨架build() { /* UI描述 */ } // 🎨 繪制方法
}

裝飾器的作用

裝飾器	作用	示例
@State	數據變化自動刷新界面	@State count = 0
@Entry	標記為頁面入口	@Entry struct HomePage
@Reusable	組件可復用優化性能	@Reusable struct Item

構建規則（易錯點）

• 根節點要求：

  @Entry 
  @Component
  struct MyPage {build() {// ? 正確：容器組件作為根節點Column() { Text('Hello') }// ? 錯誤：ForEach不能當根節點// ForEach([1,2,3], ...)}
  }
  

• 禁止操作：

  build() {// ? 不能聲明變量// let num = 1// ? 不能直接改狀態// this.count++// ? 正確方式：通過事件修改Button('+1').onClick(() => this.count++)
  }
  

---

（5）🎨 樣式與交互技巧

鏈式調用設置樣式

Text('藝術字').fontSize(24)          // 字號.fontColor('#FF69B4')  // 粉色.margin({top:20})      // 上邊距

組件樣式繼承的坑

// 子組件
@Component
struct MyButton {build() { Button('按鈕') }
}// 父組件使用時
MyButton().backgroundColor('red') // ? 這個紅色會加在"隱形容器"上

（實際效果：按鈕外圍會有紅色背景，而不是按鈕本身）

---

（6）?? 常見問題急救包

• 為什么點擊沒反應？

  • 檢查是否漏寫@State裝飾器
  • 確認事件綁定用了箭頭函數：.onClick(() => {})

• 組件顯示空白？

  • 檢查build()是否有根節點
  • 確認導出了組件：export struct MyComponent

• 樣式不生效？

  • 嘗試用!important強制樣式：.width(100).width!('80%')

---

（7）🌰 實戰案例：計數器組件

@Component
export struct MyCounter {@State num: number = 0build() {Row() {Button('-').onClick(() => this.num--)Text(`${this.num}`).margin(10)Button('+').onClick(() => this.num++)}}
}
@Entry
@Component
struct Index {build() {RelativeContainer() {Column() {Text('商品數量:')MyCounter()  // 復用計數器MyCounter({ num: 5 }) // 初始值5}}.height('100%').width('100%')}
}

Tip：這個組件可以用于購物車、投票等需要增減操作的場景

---

🚀 進階技巧

1. 組件凍結（API11+）：

   @Component({ freezeWhenInactive: true }) // 離開屏幕時凍結組件
   struct LazyComponent {}
   

2. 跨頁面傳參：

   @Entry({ routeName: 'detail', storage: myStorage })
   @Component
   struct DetailPage {}
   

---

學習路線建議：從簡單組件開始 → 掌握狀態管理 → 嘗試復雜布局 → 優化組件性能