一、ArkUI 七大高频业务组件

布局搭建好了页面骨架，组件就是填充页面的血肉元素。日常鸿蒙项目开发中，90%以上的页面交互与内容展示，都只需要掌握以下7个官方原生组件。

下面逐个拆解每个组件：核心作用、常用原生属性、完整可运行代码、真实业务场景、新手避坑点，零基础直接复制代码就能运行，适配DevEco Studio最新版本。

1. 轮播图组件 Swiper

• 核心作用：实现页面自动轮播、手动左右滑动切换内容，是APP首页标配组件

• 常用属性：autoPlay（自动播放）、interval（轮播间隔时长）、indicator（是否开启底部指示器）、loop（是否循环轮播）

• 业务场景：电商首页广告、活动宣传图、APP引导页

• 避坑点：Swiper内部必须放置子容器（一般搭配Image），不能直接空使用

2. 视频播放组件 Video

• 核心作用：原生视频播放控件，无需引入第三方插件，支持本地视频、网络视频播放

• 常用属性：src（视频地址）、controls（是否展示原生播放控件）、autoPlay（自动播放）、loop（循环播放）

• 业务场景：短视频页面、商品详情视频、课程播放页

3. 图片组件 Image

• 核心作用：页面最基础组件，用于展示本地图片、网络图片、系统资源图片

• 常用属性：width/height（宽高）、objectFit（图片缩放模式）、borderRadius（圆角）、alt（加载失败兜底图）

• 资源路径区分：本地资源用$r('app.media.图片名')，网络资源直接填图片URL

• 避坑点：网络图片需要在module.json5中配置网络访问权限，否则图片无法加载

4. 选项卡组件 Tabs + TabContent

• 核心作用：顶部/底部标签栏，点击标签快速切换对应页面内容，实现多页面无缝切换

• 组成结构：Tabs为外层容器，TabBar为标签标题，TabContent为标签对应的页面内容

• 业务场景：首页/分类/我的底部导航、资讯推荐/热点/关注顶部标签

5. 文本组件Text + 输入框组件TextInput

5.1 静态文本 Text

• 作用：展示静态文字，不可编辑，用于标题、文案、提示文字

• 常用属性：fontSize字体大小、fontColor字体颜色、textAlign文字对齐、maxLines最大行数

5.2 输入框 TextInput

• 作用：接收用户手动输入内容，可绑定onChange事件实时监听输入

• 常用属性：placeholder占位提示文字、type输入类型（密码/手机号/文本）

6. 按钮组件 Button

• 核心作用：核心交互组件，接收用户点击行为，绑定onClick事件执行逻辑

• 三种常用样式：填充按钮（默认）、描边按钮、文字按钮

• 业务场景：登录、提交、确认、跳转页面、弹窗触发

7. 单选框 Radio + 开关组件 Toggle

7.1 单选框 Radio

• 核心作用：单选选择，同一组Radio只能选中一个选项，不可多选

• 业务场景：性别选择、支付方式单选、唯一选项选择

7.2 开关 Toggle

• 核心作用：布尔值开关，只有开启/关闭两种状态，搭配@State状态变量使用

• 业务场景：消息推送开关、夜间模式、自动播放开关

布局负责搭框架，组件负责展示内容，日常90%的业务页面，只要掌握以下7个核心组件，基本上能够覆盖图文、交互、表单全部场景。

1. 轮播图 Swiper

首页必备组件，自动循环播放多张图片，支持手动滑动、自定义指示器、自动播放时长配置，电商首页、活动页必用。

2. 视频组件 Video

原生视频播放组件，支持暂停/播放、进度条监听、全屏播放、本地/网络视频源加载，短视频、视频详情页专用。

3. 图片组件 Image

展示本地图片、网络图片，支持圆角、缩放、加载失败兜底图，页面最基础组件。

4. 选项卡 Tabs+TabContent

顶部标签切换栏，比如首页/分类/我的切换、资讯分类标签，点击标签切换对应页面内容。

5. 文本/输入框 Text + TextInput

• Text：静态文字展示，用于标题、说明文案

• TextInput：用户输入交互，用于账号密码输入、搜索框

6. 按钮 Button

核心交互组件，支持填充按钮、描边按钮、文字按钮，绑定点击事件完成提交、跳转、弹窗唤起等操作。

7. 单选框 Radio + 开关 Toggle

• Radio：单选选择，性别选择、唯一选项场景

• Toggle：开关按钮，设置页开启/关闭推送、夜间模式切换

七大组件快速选型口诀

1. 轮播广告用Swiper，播放视频选Video 2. 展示图片用Image，标签切换用Tabs 3. 静态文字Text，用户输入Input 4. 点击交互Button，单选Radio，开关Toggle

二、开发必掌握核心语法与API（交互核心）

前面我们学习了布局搭建页面骨架、各类组件填充页面内容，写出来的都是静态页面，只能看不能操作。想要实现点击跳转、输入实时响应、弹窗提示、页面数据自动更新等交互效果，就必须掌握本节核心知识点，这是鸿蒙开发实现页面动态逻辑的重中之重。

1. @State 响应式状态装饰器

注意新手常见笔误：不是 @status，官方标准写法为 @State

核心作用

用来定义响应式变量，被 @State 修饰的变量具备自动更新能力：只要变量的值发生修改，页面上所有绑定该变量的 UI 组件会自动重新渲染刷新，不需要开发者手动操作更新视图，是实现页面动态变化的基础语法。

完整示例代码

typescript

运行

日常开发适用场景

输入框文字双向同步、开关开启 / 关闭状态展示、点击计数器、按钮文字动态切换、列表数据刷新、表单内容实时回显等所有需要页面跟随数据变化的场景。

2. AlertDialog 系统弹窗

核心作用

鸿蒙官方提供的系统弹窗组件，无需自己使用布局封装弹层，一行代码即可快速唤起提示弹窗。多用于操作提醒、二次确认、消息通知，比如删除内容确认、登录成功提示、表单提交确认等场景。

完整示例代码（点击按钮唤起弹窗）

typescript

运行

3. Router 页面路由

核心作用

一个完整 App 会包含多个页面（登录页、首页、商品详情页、个人中心页等），路由 router 专门负责页面之间的跳转、页面返回、页面参数传递，是多页面项目必备 API。

三个最常用路由方法

1. router.pushUrl()：保留当前页面栈，跳转到新页面，支持返回上一页
2. router.back()：直接返回上一个页面
3. router.replaceUrl()：替换当前页面，销毁原页面，无法返回

基础跳转示例代码

typescript

运行

4. onChange 值改变事件

核心含义

绑定在会产生数据变化的表单组件上，只要组件内部的值发生改动，就会立刻执行回调函数内的代码逻辑。

支持绑定的组件

TextInput 输入框、Toggle 开关、Radio 单选框、Slider 滑动条、Picker 选择器等表单类组件。

代码详解（输入框监听案例）

typescript

运行

开发适用场景

搜索框实时联想、输入内容格式校验、同步保存用户输入文本、监听开关状态切换、选择框选中值获取。

5. onClick 点击事件

核心含义

所有可交互组件通用的点击回调，用户手指点击组件的瞬间，自动执行函数内部逻辑，是使用频率最高的事件。

支持绑定的组件

Button 按钮、Image 图片、Text 文本、Swiper 轮播项、布局容器等绝大多数 UI 组件。

基础使用示例

typescript

运行

开发适用场景

页面跳转、弹窗弹出、表单提交、计数器增减、打开设置面板、图片点击放大等所有点击交互需求。

整体知识点总结

布局、组件只能搭建静态展示页面，本节内容是让页面 “动起来、可交互” 的核心全套语法：

1. @State 负责管理动态数据，实现 UI 自动刷新；
2. 弹窗 AlertDialog、路由 Router 处理页面提示与多页面切换；
3. onClick 处理用户点击类操作；
4. onChange 监听输入、选择、开关等表单值变化操作。

掌握布局、组件、本节交互三大模块，就可以独立完成绝大多数鸿蒙基础业务页面开发。

---

三、总结

1. 组件按需选用：展示用静态组件，表单交互用输入框、单选框、开关

2. 交互三板斧：@State管UI刷新、onClick管点击、onChange管表单值变化

3. 页面跳转用路由，消息提示用弹窗，基础能力覆盖绝大部分鸿蒙应用开发