鸿蒙 UI 开发基础语法与组件复用全解析：从装饰器到工程化实践指南

一、引言：鸿蒙 UI 开发的语法体系与范式革新

在鸿蒙全场景应用开发体系中，基于 ArkTS 语言的声明式 UI 范式构成了跨设备界面开发的技术基石。区别于传统命令式 UI 的编程模型，鸿蒙 UI 通过装饰器语法与组件化架构，实现了 "数据即视图" 的响应式开发模式。本文将系统拆解从基础语法到组件复用的完整知识体系，帮助开发者快速构建具备跨设备适配能力的高质量界面。

二、装饰器系统：组件功能的元数据标识

装饰器作为鸿蒙 UI 范式的核心语法机制，通过 @符号为组件注入特定功能属性，是构建 UI 体系的逻辑起点。

2.1 组件类型装饰器

@Component：标记自定义组件的核心装饰器，要求必须包含 build () 方法定义界面结构。该装饰器赋予结构体 UI 渲染能力，是业务组件封装的基础单元：

@Component
export  struct MyButton {
  @State text: string = '点击我'

  build() {
    Button(this.text)
      .onClick(() => {
        this.text = '已点击'
      })
  }
}

@Entry：应用启动的入口组件标记，每个鸿蒙应用仅允许一个入口组件。规范要求入口组件必须包含根容器（如 Column/Row）作为布局起点：

import { MyButton } from './TestPage'

@Entry
@Component
struct Index {
  build() {
    Column() {
      MyButton()
    } // 根容器包裹业务组件
  }
}

2.2 响应式数据装饰器

@State：声明组件内响应式状态变量，数据变更会自动触发 UI 重渲染，作用域限定于当前组件。状态变量需在组件顶层作用域声明：

@Component
export struct Count {
  @State count: number = 0 // 状态变更触发UI刷新

  build() {
    Button(`计数: ${this.count}`)
      .onClick(() => this.count++)
  }
}

@Prop 与 @Link 的双向绑定机制：

// 父组件状态管理
@Component struct Parent {
  @State msg: string = '初始值'

  build() {
  }
}
// 子组件数据接收模式对比
@Component struct ChildProp {
  @Prop msg: string // 单向只读模式

  build() {
  }
}
@Component struct ChildLink {
  @Link msg: string // 双向绑定模式

  build() {
  }
}

@Prop：实现父组件到子组件的单向数据传递，子组件不可修改接收到的数据
@Link：建立父子组件间的数据双向绑定，任意一方变更会实时同步到对方

三、组件系统：从基础单元到交互配置

鸿蒙 UI 采用积木式组件化设计，通过系统组件与自定义组件的组合，实现复杂界面的构建。

3.1 系统组件的工程化应用

无参基础组件：适用于分隔线、空白占位等基础场景，直接调用无需参数配置：

@Entry
@Component
struct Index {
  build() {
    Column() {
      Text('列表项1')
      Divider() // 无参数分割线组件
      Text('列表项2')
    }
  }
}

参数化组件调用：需传入必要业务参数（如图像路径、文本内容），支持变量与表达式赋值：

@Entry
@Component
struct Index {
  build() {
    Column() {
      Image($r('app.media.background')) // 引用本地资源
        .width(100)            // 固定宽度
        .height(100)           // 固定高度
        .objectFit(ImageFit.Contain) // 图片适配策略（枚举值）
    }
  }
}

3.2 组件属性与事件系统

属性链式配置：通过方法链实现样式与属性的声明式配置，支持常量、变量与条件表达式：

@Entry
@Component
struct Index {
  @State isFullScreen: boolean = false // 控制全屏状态的变量

  build() {
    Column() {
      Text('重要通知')
        .fontSize(18)// 字体尺寸
        .fontColor(Color.Red)// 字体颜色（预定义枚举）
        .margin({ top: 16, bottom: 8 })// 上下边距
        .width(this.isFullScreen ? '100%' : '50%') // 条件宽度设置
      Button('全屏')
        .onClick(() => {
          this.isFullScreen = !this.isFullScreen // 切换全屏状态
        })
    }
  }
}

事件处理最佳实践：推荐使用箭头函数避免 this 作用域问题，支持全场景交互事件：

@Entry
@Component
struct Index {
  @State isLoading: boolean = false // 加载状态

  build() {
    Column() {
      Button('提交')
        .onClick(() => { // 箭头函数保持this指向
          this.isLoading = true // 触发状态变更
        })
    }
  }
}

四、自定义组件：业务逻辑的工程化复用

自定义组件是提升鸿蒙 UI 开发效率的核心手段，通过封装系统组件实现业务逻辑的模块化复用。

4.1 组件定义与跨模块引用

标准组件结构：基于 struct 定义，配合 @Component 装饰器，必须包含 build () 方法：

@Component
struct IconButton {
  @Prop icon: string // 接收图标路径
  @Prop text: string // 接收按钮文本

  build() {
    Row() { // 水平布局容器
      Image(this.icon)
        .width(24) // 图标尺寸
      Text(this.text)
        .margin({ left: 8 }) // 文本间距
    }
    .padding(12) // 整体内边距
    .backgroundColor('#F5F5F5') // 背景色
  }
}

跨文件组件复用：通过 export/import 实现组件的工程化引用：

// 组件导出定义
@Component
export struct MyButton {
  /* 组件实现 */
  build() {

  }
}
__________________________________

import { MyButton } from './TestPage'

@Entry
@Component
struct Index {

  build() {
    Row() { // 水平布局容器
     MyButton() {
       
     }
    }
  }
}

4.2 高级语法提升开发效能

@Builder：UI 片段的参数化封装：封装可复用的 UI 结构块，支持参数化配置：

@Entry
@Component
struct Index {
  build() {
    Row() { // 水平布局容器
      this.MyCard('Title 1', 'Content 1') // 卡片组件
    }
  }

  @Builder
  MyCard(title: string, content: string) { // 卡片组件构建器
    Column() {
      Text(title).fontSize(16).fontWeight(FontWeight.Bold)
      Text(content).fontSize(14).margin({ top: 8 })
    }
    .padding(16).backgroundColor('#FFFFFF').borderRadius(8)
  }
}

@Extend：系统组件的功能扩展：为系统组件添加自定义属性方法，实现样式复用：

@Entry
@Component
struct Index {
  build() {
    Row() { // 水平布局容器
      Text('Hello World') // 文本组件
        .setCornerRadius(10)
    }
  }
}

@Extend(Text)
// 扩展Text组件的圆角功能
function setCornerRadius(radius: number) {
  .fontSize(14) // 基础字体大小
  .borderRadius(radius) // 新增圆角属性
}