Image（图像组件）
Image 是 ArkUI 中用于显示静态或网络图片的核心组件，支持本地资源、网络 URL、Base64 编码等多种图像源格式。在鸿蒙应用开发中，图片资源通常存放在项目的 resources/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：控制网络图片加载策略（如懒加载）。
使用场景
- 应用图标、用户头像、商品展示图；
- 背景装饰图、引导页 Banner；
- 动态加载远程图片（需配置网络权限）。
注意事项
- 本地图片必须放入
resources目录，不能直接使用相对路径； - 网络图片需在
module.json5中声明ohos.permission.INTERNET权限； - 图片过大可能导致内存溢出，建议对高清图做压缩或使用
pixelMap分片加载。
Text（文本组件）
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 提供用户输入文本的能力，支持多种输入类型、提示文本、密码掩码、键盘类型等，是表单交互的关键组件。
基本用法
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（按钮组件）
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（轮播组件）
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：滑动动画时长。
注意事项
- 子组件数量建议 ≤ 5，过多会影响性能；
- 自动播放时应监听页面生命周期，进入后台时暂停；
- 可结合
onClick实现点击跳转详情页。
List（列表组件）
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的懒加载策略。
验证要点
- 初始加载 4 项符合预期；
- 文本格式统一；
- 项间距 10vp 由
space: 10控制。
Scroll（滚动容器）
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 为主）、空值安全、响应式布局等原则，即可构建出兼容多端、体验流畅的鸿蒙应用界面。
