本文整理 HarmonyOS ArkTS 开发核心基础知识点，包含布局规范、常用 UI 组件、状态管理、弹窗、路由、事件回调等高频开发内容，新手可直接收藏作为开发速查手册。

一、布局系统核心规则（必踩坑重点）

核心硬性语法规范

    所有页面build()函数内，有且只能存在 1 个根布局容器 不允许多个布局容器同级并列，否则编译器直接报红报错；多个布局需要展示时，全部嵌套在唯一根布局内部。

五大常用布局分类

1.垂直布局 Column 

     子元素沿竖直方向从上到下依次排列，最常用页面根容器。 示例：

2.水平布局 Row

   子元素沿水平方向从左到右横向排列，多用于一行放多个按钮、标签。

3.相对布局 RelativeContainer

   通过锚点约束控制子组件位置，适配复杂错位排版，适合自定义弹窗、悬浮控件。

4.层叠布局 Stack

   件按书写顺序层层叠加，后写组件覆盖上层，适合轮播、遮罩弹窗、图片水印。

5.弹性布局 Flex

   自适应弹性伸缩布局，可自由切换横向 / 纵向，自动分配剩余空间，适配多端自适应页面。

布局嵌套逻辑

   唯一根布局 → 内部可无限嵌套 Column/Row/Stack/Flex/RelativeContainer，无嵌套层数限制，仅最外层不能并列多个根容器。

二、高频基础 UI 组件大全

1. 轮播图 Swiper

   实现图片自动轮播、左右滑动切换，支持指示器、自动播放、循环切换，首页 Banner 必备组件。

视频 Video

   本地 / 网络视频播放组件，支持播放、暂停、进度拖拽、全屏、静音等媒体能力。

3. 图片 Image

   加载本地资源图、网络图片，支持圆角、缩放、占位图、裁剪模式。

4. 选项卡 Tabs + TabContent

   顶部 / 底部标签栏，多页面切换（首页 / 我的 / 分类），APP 底部导航核心组件。

5. 文本 Text / 输入框 TextInput

     Text：静态文字展示，支持字体大小、颜色、行高、文字截断；

     TextInput：用户输入框，支持密码模式、输入监听、默认提示文字。

6. 按钮 Button

   点击交互基础组件，支持文字按钮、图片按钮、圆角、背景色、禁用状态。

7. 单选框 Radio + RadioGroup

   多选一选择器，常用于性别、单一选项问卷场景。

8. Toggle 开关组件

   布尔型开关，类似手机设置开关，开启 / 关闭二选一状态切换。

三、核心开发必学知识点

@State

响应式状态装饰器，变量变更自动刷新页面 UI；

弹窗

AlertDialog 系统弹窗、CustomDialog 自定义弹窗，配合 @State 控制显隐；

路由 Router

实现页面跳转、参数传递、页面返回；

事件回调：

onChange(()=>{})：监听组件数值变化（输入框、开关、单选框）

onClick(()=>{})：监听组件点击行为（按钮、图片、文本）

四、实操避坑提醒

1.build 根布局唯一，多布局禁止同级；

2.页面数据不刷新，优先检查是否添加 @State；

3.点击逻辑用 onClick，数据变化监听使用 onChange，不要混淆；

4.专用容器组件需搭配对应子组件使用（Swiper、Tabs）。