HarmonyOS应用开发实战（基础篇）Day06-《常见组件》

常见组件

• Image（图像组件）
  • 基本用法
  • 核心属性
  • 使用场景
  • 注意事项
• Text（文本组件）
  • 基本用法
  • 核心特性
  • 使用场景
  • 最佳实践
• TextInput（输入框组件）
  • 基本用法
  • 输入类型（`type` 属性）
  • 密码输入示例
  • 其他重要属性
  • 安全建议
• Button（按钮组件）
  • 基本用法
  • 类型与样式
  • 交互增强
  • 使用场景
• Swiper（轮播组件）
  • 基本结构
  • 核心属性
  • 注意事项
• List（列表组件）
  • 基本用法
  • 关键特性
  • 性能优化
  • 验证要点
• Scroll（滚动容器）
  • 使用条件
  • 嵌套限制
  • 行为验证
  • 总结

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 枚举值，系统会自动匹配对应的软键盘：

密码输入示例

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 为主）、空值安全、响应式布局等原则，即可构建出兼容多端、体验流畅的鸿蒙应用界面。