Image(图像组件)
是 ArkUI 中用于显示静态或网络图片的核心组件,支持本地资源、网络 URL、Base64 编码等多种图像源格式。在鸿蒙应用开发中,图片资源通常存放在项目的 目录下,通过 方式引用,确保多设备、多语言环境下的资源适配。
HarmonyOS ArkUI 包含 Image、Text、TextInput、Button、Swiper、List 及 Scroll 等常见组件。文章详解各组件的基础用法、核心属性、使用场景及注意事项,涉及资源引用、样式定制、交互实现与性能优化。掌握这些组件特性有助于构建兼容多端、体验流畅的鸿蒙应用界面。

是 ArkUI 中用于显示静态或网络图片的核心组件,支持本地资源、网络 URL、Base64 编码等多种图像源格式。在鸿蒙应用开发中,图片资源通常存放在项目的 目录下,通过 方式引用,确保多设备、多语言环境下的资源适配。
Imageresources/base/media/$r('app.media.xxx')Image($r('app.media.logo')).width(100).height(100).objectFit(ImageFit.Contain)// 保持宽高比缩放
💡 资源路径说明:
$r('app.media.xxx')中的xxx为图片文件名(不含扩展名);系统会根据设备分辨率自动选择media/下对应drawable-xxhdpi等子目录中的资源。
width / height:控制显示尺寸,推荐使用 vp 单位;objectFit:定义图片填充方式:
ImageFit.Fill:拉伸填满,可能变形;ImageFit.Contain:等比缩放,完整显示;ImageFit.Cover:等比裁剪,填满容器;borderRadius:实现圆角头像效果;alt:设置加载失败时的占位文本(辅助可访问性);loadingStrategy:控制网络图片加载策略(如懒加载)。resources 目录,不能直接使用相对路径;module.json5 中声明 ohos.permission.INTERNET 权限;pixelMap 分片加载。[图片]
Text 是 UI 开发中最基础、最频繁使用的组件,用于显示单行或多行静态文本。ArkTS 的 Text 组件支持丰富的样式定制,包括字体、颜色、对齐、换行、省略等,是构建信息展示类界面的核心元素。
Text('Hello, HarmonyOS!').fontSize(16).fontColor('#333333').fontWeight(FontWeight.Bold).textAlign(TextAlign.Center)
fontSize():字体大小(单位 vp);fontFamily():指定字体族;fontStyle():斜体(FontStyle.Italic);textCase():大小写转换(如全大写);textAlign():左/中/右对齐;maxLines():限制最大行数;textOverflow():超长文本处理(Ellipsis 显示'…');Span 组件实现局部样式差异(如关键词高亮)。$r('app.string.xxx') 引用国际化资源;maxLines(1).textOverflow(TextOverflow.Ellipsis) 防止布局错乱;fontColor 以保证可读性。[图片]
TextInput 提供用户输入文本的能力,支持多种输入类型、提示文本、密码掩码、键盘类型等,是表单交互的关键组件。
TextInput({ placeholder:'请输入用户名'}).type(InputType.Text).onChange((value)=>{console.log('输入内容:', value);})
type 属性)ArkTS 提供丰富的 InputType 枚举值,系统会自动匹配对应的软键盘:
| 类型 | 说明 |
|---|---|
Text | 普通文本 |
Email | 邮箱(键盘带 @ 和 .) |
Number | 数字(仅数字键盘) |
Password | 密码(自动掩码为 ●) |
Phone | 电话号码(带 + 和 -) |
DateTime | 日期时间(弹出日期选择器) |
[图片]
TextInput({ placeholder:'请输入密码'}).type(InputType.Password).passwordIcon(true)// 显示'眼睛'图标切换明文
此时输入内容会被自动替换为圆点符号,提升安全性。
[图片]
[图片]
placeholder:提示文字;maxLength:限制最大输入长度;onChange / onSubmit:监听输入变化或回车提交;caretColor:光标颜色;selectedBackgroundColor:选中文本背景色。Button 是触发操作的核心交互控件,常用于提交表单、跳转页面、触发功能等。ArkUI 的 Button 支持文本按钮、图标按钮、自定义样式等多种形态。
Button('点击登录').onClick(()=>{console.log('按钮被点击');// 可在此处跳转页面或调用 API}).width('100%').height(50).backgroundColor('#007DFF').fontColor(Color.White)
borderRadius(50) 实现;Image 组件使用;.enabled(false) 自动变灰且不可点击。onClick 中添加节流逻辑;Progress 组件;accessibilityText 供读屏软件识别。[图片]
Swiper 用于实现滑动切换的轮播效果,常用于首页 Banner、商品推荐、引导页等场景。它通过手势滑动或自动播放,在多个子页面间切换。
Swiper(){Image($r('app.media.banner1'))Image($r('app.media.banner2'))Image($r('app.media.banner3'))}.index(0)// 初始索引.autoPlay(true)// 自动播放.interval(3000)// 播放间隔(毫秒).loop(true)// 循环播放
index:当前显示项索引;autoPlay:是否自动轮播;interval:自动切换时间间隔;loop:是否循环(首尾相连);indicator:是否显示指示器(小圆点);duration:滑动动画时长。onClick 实现点击跳转详情页。[图片]
List 是用于展示大量垂直滚动数据的高性能组件,内部采用懒加载机制,仅渲染可视区域内的项,极大提升内存与渲染效率。
List({ space:10}){// space 设置项间距ForEach(this.items,(item:string)=>{ListItem(){Text(item).padding(10).width('100%')}},(item:string)=> item)}.height('100%')
space:统一设置列表项之间的间距;**ListItem**:每个列表项必须包裹在 ListItem 中;scroller:可绑定滚动控制器,实现滚动到指定位置;ListItemGroup 实现分组标题。ForEach 而非 for 循环,确保高效更新;ListItem 中嵌套复杂布局;Image 的懒加载策略。space: 10 控制。[图片]
Scroll 是一个通用的单方向滚动容器,适用于内容超出可视区域时的滚动需求。与 List 不同,Scroll 不具备数据驱动能力,更适合静态或少量动态内容的滚动。
Scroll 的高度;Scroll 只能直接包含一个子元素,若需多个,必须用 Column 或 Row 包裹。Scroll(){Column(){Text('Item 1')Text('Item 2')// ... 多个子项}.height(800)// 必须大于 Scroll 高度(如 400vp)}.height(400).scrollable(ScrollDirection.Vertical)
Scroll 内嵌 List 或 Grid,会导致手势冲突或滚动失效;NestedScroll 或将外层改为 Column + List。Scroll 自动禁用滚动;.scrollable() 显式指定;Scroller 控制器实现程序化滚动。以上六大组件——Image、Text、TextInput、Button、Swiper、List 与 Scroll——构成了鸿蒙应用 UI 的基础骨架。掌握它们的特性与适用边界,是高效开发高质量 ArkTS 应用的前提:
Text + Image;TextInput;Button;Swiper;List(优先);Scroll(谨慎嵌套)。合理组合这些组件,并遵循单位规范(vp 为主)、空值安全、响应式布局等原则,即可构建出兼容多端、体验流畅的鸿蒙应用界面。

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML转Markdown 互为补充。 在线工具,Markdown转HTML在线工具,online
将 HTML 片段转为 GitHub Flavored Markdown,支持标题、列表、链接、代码块与表格等;浏览器内处理,可链接预填。 在线工具,HTML转Markdown在线工具,online
通过删除不必要的空白来缩小和压缩JSON。 在线工具,JSON 压缩在线工具,online
将JSON字符串修饰为友好的可读格式。 在线工具,JSON美化和格式化在线工具,online