前言

HarmonyOS 鸿蒙应用开发核心语言为 ArkTS，基于 TypeScript 拓展，是一套声明式UI、数据驱动、高性能、轻量化的前端开发体系。与传统命令式开发不同，ArkTS 只需声明页面结构、样式与数据关系，系统自动完成渲染与刷新，极大提升移动端开发效率。

本文将系统化、全覆盖讲解鸿蒙 ArkTS 零基础核心知识点，包含：五大布局系统、全部基础UI组件、多媒体组件、轮播图Swiper、@State状态管理、交互事件、弹窗、页面路由，知识点层层递进、代码可直接运行、适配新手学习、可直接作为课程总结/技术博客发布。

一、ArkTS 核心开发基础认知

1.1 声明式UI核心思想

ArkTS 采用声明式编程：开发者只需要描述“页面长什么样”，不需要手动控制页面刷新、控件创建、视图更新。

核心特点：结构与行为分离、数据驱动UI、自动渲染更新。

1.2 标准页面结构（固定模板）

所有鸿蒙页面必须遵循统一结构：入口装饰器 + 组件结构体 + build渲染方法

@Entry // 页面入口 @Component // 自定义组件 struct DemoPage { // 状态变量、控制器定义区 build() { // 页面布局、组件、样式、事件全部写在这里 } }

1.3 页面开发完整流程

定义状态数据 → 选择布局搭建页面骨架 → 放置UI/多媒体组件 → 设置样式 → 绑定交互事件 → 实现动态UI效果

---

二、鸿蒙五大布局系统（页面骨架核心）

布局是页面的骨架，所有组件必须嵌套在布局容器内。鸿蒙基础布局共五类，覆盖线性排列、层叠堆叠、自由定位、弹性自适应所有场景。

2.1 Column 垂直布局（最常用根布局）

核心作用：子组件从上到下垂直排列，是项目90%页面的根布局。

适用场景：首页、表单、详情页、纵向流式页面。

Column({space:20}){ Text("页面标题") Button("功能按钮") } .width('100%') .height('100%') .padding(20)

常用属性：space（组件间距）、alignItems（对齐方式）、padding、margin、borderRadius

2.2 Row 水平布局

核心作用：子组件从左到右横向单行排列，不自动换行。

适用场景：按钮组、选项栏、横向功能区、轮播控制栏。

易错点：Row 内部子组件禁止设置 width('100%')，会挤占后续组件。

2.3 Stack 层叠/堆叠布局

核心作用：实现图层叠加，后写的组件覆盖在先组件上方，实现浮层效果。

适用场景：图片文字遮罩、轮播图角标、红点提示、视频播放浮层、水印。

Stack(){ Image($r("app.media.banner")).objectFit(ImageFit.Cover) Text("限时活动") .position({x:15,y:15}) .backgroundColor(Color.Red) .fontColor(Color.White) .padding(5) } .width('100%') .height(220)

2.4 RelativeContainer 相对布局

核心作用：组件通过 ID 互相约束位置，实现自由定位、不规则排版。

适用场景：登录页、复杂表单、自由布局卡片。

开发规则：

• 所有约束组件必须设置唯一 id()

• 通过 alignRules 绑定父容器或其他组件

• 禁止循环约束（A绑定B、B绑定A）

2.5 Flex 弹性布局（进阶万能布局）

核心作用：Row/Column 增强版，支持主轴切换、自动换行、弹性均分。

核心属性：

• direction：Row横向 / Column纵向

• wrap：Wrap 开启自动换行

• 子组件 flexGrow(1)：自动均分剩余空间

适用场景：底部导航、多标签、等分按钮、自适应流式布局。

Flex({direction:FlexDirection.Row,wrap:FlexWrap.NoWrap}){ Button("首页").flexGrow(1) Button("分类").flexGrow(1) Button("我的").flexGrow(1) } .width('100%')

2.6 五大布局选型总结

• 简单纵向页面 → Column

• 单行横向排版 → Row

• 图片叠加、浮层角标 → Stack

• 自由不规则表单 → RelativeContainer

• 均分、自适应、标签流 → Flex

---

三、ArkTS 全套基础UI与多媒体组件

3.1 Text 文本组件

用于展示静态文字、动态状态文字，支持字号、颜色、对齐、最大行数。

3.2 TextInput 输入框组件

核心录入组件，用于接收用户输入，搭配 onChange 实现实时数据同步。

3.3 Button 按钮组件

核心交互组件，绑定 onClick 点击事件，可动态切换文字、颜色、状态。

3.4 Image 图片组件

支持两种资源读取：

• 媒体资源：$r("app.media.xxx")

• 静态资源：$rawfile("xxx")

必备修饰符：objectFit(ImageFit.Cover) 防止拉伸变形。

3.5 Video 视频组件

播放本地视频，必须绑定 VideoController 控制器才能播放暂停。

3.6 Swiper 轮播图组件（重点）

首页 Banner、广告轮播核心组件，支持自动播放、循环滑动、指示器、手动切换。

核心属性：

• autoPlay：自动播放

• interval：切换毫秒间隔

• loop：循环播放

• indicator：显示底部圆点

• onChange：监听页码切换

手动控制：依赖 SwiperController 实现上一页、下一页、跳转指定页。

3.7 Toggle / Radio / Tabs 拓展组件

• Toggle：布尔开关组件，适配设置类功能

• Radio：单选组件，需配合 RadioGroup 使用

• Tabs：标签页切换，实现多页面分类切换

---

四、@State 响应式状态管理（动态UI核心）

4.1 核心原理

@State 是 ArkTS 最重要的装饰器，被修饰的变量具备响应式刷新能力：

数据改变 → 页面自动刷新绑定该数据的所有组件

4.2 三大常用数据类型

• 字符串 string：存储输入框内容、动态文本

• 布尔 boolean：开关状态、组件显隐

• 数字 number：轮播下标、计数、页码

4.3 开发规范

• 状态变量定义在 struct 内部、build 外部

• 使用必须加 this.xxx

• 普通变量无刷新能力，只有 @State 可驱动UI更新

---

五、交互事件系统（人机交互闭环）

5.1 onClick 点击事件

适用于所有可点击组件，用户点击触发自定义逻辑。

常用场景：状态切换、轮播切换、弹窗弹出、页面跳转。

5.2 onChange 数值监听事件

监听组件数值变化，实时同步数据到状态变量。

适用组件：TextInput、Swiper、Toggle、Radio。

常用场景：实时输入同步、轮播页码更新、开关状态同步。

5.3 完整交互闭环逻辑

用户操作 → 触发事件 → 修改状态数据 → UI自动刷新

这是所有鸿蒙动态页面的底层运行原理。

---

六、拓展核心能力

6.1 Dialog 弹窗提示

分为系统弹窗 AlertDialog 和自定义弹窗，用于消息提示、操作确认。

6.2 Router 页面路由

实现多页面跳转、返回、传参，是多页面项目必备技术。

---

七、综合实战整合（完整可运行架构）

完整项目开发规范：

1. 使用 Column 作为全局根布局

2. 顶部嵌套 Stack + Swiper 实现带角标的轮播图

3. 中部使用 Flex 实现均分功能按钮

4. 表单区域使用 RelativeContainer 自由排版

5. 通过 @State 实现全局动态数据联动

6. 通过 onClick / onChange 完成用户交互

---

八、学习总结与感悟

通过系统性学习 ArkTS 基础开发，我完整掌握了鸿蒙声明式UI的整套开发体系，理解了布局搭骨架、组件填内容、状态控动态、事件做交互的层级开发思想。

五大布局各司其职，覆盖静态排版、图层叠加、自由定位、自适应弹性所有场景；各类UI与多媒体组件满足图文展示、视频播放、轮播广告、表单录入等主流业务需求。

@State 响应式状态管理彻底实现了数据驱动UI的开发模式，摆脱传统手动刷新视图的繁琐操作，是鸿蒙开发的核心精髓。配合点击、监听两大事件，可实现完整的人机交互闭环。

整体知识点层层递进、逻辑闭环，掌握以上内容可独立开发完整的鸿蒙基础页面，为后续自定义组件、网络请求、列表开发、全栈项目实战打下坚实基础。