HarmonyOS 应用开发实战：常见组件详解

基本用法

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