鸿蒙（OpenHarmony）声明式 UI 开发入门：从「智慧校园」项目学基础语法

2401_84552999

823人浏览 · 2025-10-09 10:39:58

2401_84552999 · 2025-10-09 10:39:58 发布

鸿蒙（OpenHarmony）作为国产开源操作系统，其应用开发采用 ArkUI 声明式框架，通过简洁的「组件 + 状态」语法实现界面与逻辑的解耦。本文结合我个人学习时写的「智慧校园」项目的实际代码，带初学者快速掌握鸿蒙开发的核心语法。

一、基础结构：组件（Component）与声明式 UI

鸿蒙应用的界面由 @Component 装饰的结构体（struct）定义，每个结构体对应一个可复用的 UI 组件。组件的界面布局通过 build() 方法内的组件嵌套实现，遵循「代码即界面（What You Code Is What You Get）」原则。

示例：登录页组件（LoginPage.ets）

// LoginPage.ets
@Entry  // 标记为应用入口组件（整个应用仅一个）
@Component  // 声明该结构体为UI组件
struct LoginPage {
  // 组件私有状态：@State装饰的变量变化时，UI会自动更新
  @State password: string = '';
  @State name: string = '';

  // 界面构建核心方法：所有UI布局均在此定义
  build() {
    // 垂直布局容器（Column）：子组件从上到下排列
    Column() {
      // 1. 标题图片区域（水平布局Row，确保图片居中）
      Row() {
        Image($r('app.media.tb'))  // 引用媒体资源（tb为图片名，需在resources目录配置）
          .width(80)  // 设置图片宽度
          .margin({ top: 20 })  // 图片顶部外边距20
      }

      // 2. 输入框组（垂直布局Column，用户名+密码输入框上下排列）
      Column() {
        // 用户名输入框（水平布局Row，确保输入框居中）
        Row() {
          TextInput({ placeholder: '请输入用户名' })  // 文本输入组件，提示文字为“请输入用户名”
            .onChange((value) => {  // 输入内容变化时触发的回调
              this.name = value;  // 将输入值同步到状态变量name
            })
            .width('80%')  // 输入框宽度占父容器（Column）的80%
            .height(40)  // 输入框高度固定40
        }

        // 密码输入框（带密码隐藏模式）
        Row() {
          TextInput({ placeholder: '请输入密码' })
            .onChange((value) => this.password = value)  // 简化写法：直接同步输入值到password
            .type(InputType.Password)  // 开启密码模式，输入内容隐藏为圆点
            .width('80%')  // 与用户名输入框宽度一致，保持界面整齐
        }
      }
    }
  }
}

关键语法点

@Component：标记结构体为 UI 组件，必须包含 build() 方法（用于定义界面布局）。
@Entry：标记应用的「入口组件」（整个应用仅一个），决定应用启动时显示的初始界面。
$r('app.media.tb')：资源引用语法，app.media 表示资源目录中的「媒体资源文件夹」，tb 是具体资源名（需提前在 resources 目录中配置图片）。

二、状态管理：@State 实现 UI 自动更新

鸿蒙通过「状态装饰器」（如 @State、@Link 等）实现「状态变量 → UI 界面」的自动同步。其中最常用的 @State 用于装饰组件的「私有状态变量」—— 当变量值变化时，组件会自动重新渲染相关 UI，无需手动调用刷新方法。

示例：登录页的输入同步逻辑

在 LoginPage 组件中，name 和 password 被 @State 装饰，实现输入内容与 UI 的实时同步：

ets

// 1. 定义@State状态变量（初始值为空字符串）
@State name: string = '';
@State password: string = '';

// 2. 用户名输入框：输入变化时更新状态变量
TextInput({ placeholder: '请输入用户名' })
  .onChange((value) => {
    this.name = value;  // 输入内容变化 → 更新name变量
  })

// 3. 密码输入框：简化写法（箭头函数直接赋值）
TextInput({ placeholder: '请输入密码' })
  .onChange((value) => this.password = value)  // 输入内容变化 → 更新password变量

核心逻辑：当用户在输入框中打字时，onChange 回调会实时获取输入值并更新 @State 变量；变量值变化后，系统会自动重新渲染输入框（无需手动操作），确保 UI 与状态一致。

三、组件复用：自定义可复用模块

鸿蒙支持将常用界面片段（如头部导航、按钮组）封装为「独立组件」，通过 export struct 导出后，其他组件可直接导入使用，大幅提升代码复用性和维护效率。

示例 1：通用头部组件（ListHader.ets）

ets

// ListHader.ets（通用头部组件，可复用）
@Component
export struct ListHader {  // export关键字：允许其他文件导入该组件
  build() {
    Column() {
      // 头部核心区域（包含Logo、标题、搜索框）
      Column() {
        // 1. Logo + 标题（水平布局Row）
        Row() {
          Image($r("app.media.log"))  // 引用Logo图片
            .width(40)  // Logo宽度固定40
          Text('智慧校园')  // 头部标题
            .fontColor('#fff')  // 字体颜色为白色
        }

        // 2. 搜索框（水平布局Row，确保搜索框居中）
        Row() {
          Search({ placeholder: '搜索课程、通知、新闻' })  // 系统内置搜索组件
            .backgroundColor('#fff')  // 搜索框背景色为白色
            .width('95%')  // 宽度占父容器95%，留少量边距
        }
      }
      .backgroundColor('#498fe0')  // 头部整体背景色（蓝色）
      .height('17%')  // 高度占父容器17%，适配不同屏幕
    }
  }
}

示例 2：在首页中复用头部组件（HomeComponent.ets）

只需通过 import 导入组件，即可直接在 build() 方法中调用：

ets

// HomeComponent.ets（首页组件）
// 1. 导入自定义的ListHader组件（路径需与实际文件位置匹配）
import { ListHader } from "./ListHader"

@Component
struct HomeComponent {
  build() {
    Column() {
      // 2. 直接调用复用组件（无需重复编写头部代码）
      ListHader()

      // 3. 首页其他内容（如轮播图、通知列表等）
      // ...（省略其他布局代码）
    }
  }
}

四、页面跳转：路由（Router）的使用

鸿蒙通过 router 模块实现「页面导航」，支持跳转到新页面、返回上一页等常见场景，需提前在项目配置中注册页面路径。

示例：点击通知跳转到详情页

在 HomeComponent 中，点击「开学通知」文本时，跳转到「通知详情页（TzPage）」：

ets

// HomeComponent.ets
// 1. 导入router模块（需提前配置依赖）
import router from '@ohos.router';

@Component
struct HomeComponent {
  build() {
    Column() {
      // ...（其他布局：头部、轮播图等）

      // 2. 通知文本（点击触发跳转）
      Row() {
        Text('2025年春季开学通知')
          .fontColor('#999')  // 字体颜色为浅灰色
          .onClick(() => {  // 点击事件回调
            // 跳转到TzPage（路径需与pages.json中注册的一致）
            router.push({ url: 'pages/TzPage' })
          })
      }
    }
  }
}

路由核心方法

方法	作用	场景
`router.push({ url: '页面路径' })`	跳转到新页面，当前页面保留在「页面栈」中	从首页→详情页、登录页→首页
`router.back()`	返回上一页，当前页面从页面栈中移除	从详情页→首页、设置页→个人中心页

五、常用 UI 组件：输入框与轮播图

鸿蒙提供丰富的「内置 UI 组件」，覆盖表单输入、图片展示、列表等常见场景，以下介绍「文本输入框（TextInput）」和「轮播图（Swiper）」的核心用法（TextInput 已在登录页示例中展示，此处重点讲 Swiper）。

示例：首页轮播图（Swiper 组件）

在 HomeComponent 中，使用 Swiper 组件实现自动轮播的图片展示：

ets

// HomeComponent.ets
@Component
struct HomeComponent {
  build() {
    Column() {
      // 1. 复用头部组件
      ListHader()

      // 2. 轮播图（Swiper容器，子组件为轮播图片）
      Swiper() {
        Image($r('app.media.xue3'))  // 轮播图1
        Image($r('app.media.xue2'))  // 轮播图2
        Image($r('app.media.xue1'))  // 轮播图3
      }
      .autoPlay(true)  // 开启自动轮播
      .width('100%')  // 轮播图宽度占满父容器
      .height('60%')  // 轮播图高度占父容器60%
      // 顶部圆角：topLeft和topRight设为4%，优化视觉效果
      .border({ radius: { topLeft: '4%', topRight: '4%' } })
    }
  }
}

Swiper 关键属性：

autoPlay(true)：开启自动轮播（默认关闭，需手动滑动）。
border({ radius: ... })：设置圆角，提升界面美观度。
indicatorStyle：可自定义轮播指示器（如圆点颜色、大小），默认显示底部圆点。

总结：鸿蒙声明式 UI 核心与实践步骤

鸿蒙声明式 UI 的核心是「组件 + 状态」—— 通过 @Component 定义界面模块，通过 @State 等装饰器管理状态，实现界面与逻辑的解耦。结合「智慧校园」项目，初学者可按以下步骤实践：

掌握基础装饰器：理解 @Component（定义组件）、@Entry（入口组件）、@State（状态管理）的作用，能写出简单的单页面组件（如登录页）。
封装复用组件：尝试将通用模块（如头部、按钮、列表项）封装为独立组件，通过 export/import 实现复用（如本文的 ListHader）。
实践页面跳转：使用 router 模块实现多页面导航，掌握 router.push（跳转）和 router.back（返回）的用法。
熟悉常用组件：练习 TextInput（输入）、Swiper（轮播）、List（列表）等内置组件，完成一个包含「登录页→首页→详情页」的完整流程。