三、鸿蒙开发-常用组件二(文本输入、进度条、弹框、组件编程技巧)

提示：本文根据b站尚硅谷2024最新鸿蒙开发HarmonyOS4.0+鸿蒙NEXT星河版零基础教程课整理

链接指引 => 尚硅谷2024最新鸿蒙开发HarmonyOS4.0+鸿蒙NEXT星河版零基础教程

一、文本输入

1.1 参数

TextInput组件的参数定义如下

TextInput(value?:{placeholder?: string|Resource , text?: string|Resource})

placeholder
placeholder属性用于设置无输入时的提示文本，效果如下
text
text用于设置输入框当前的文本内容，效果如下
1.2 常用属性
1.2.1 输入框类型
可通过type()方法设置输入框的类型，该方法的参数为InputType枚举类型，可选的枚举值有

名称	描述
InputType.Normal	基本输入模式
InputType.Password	密码输入模式
InputType.Number	纯数字输入模式

1.2.2 光标样式

可通过caretColor()方法设置光标的颜色

1.2.3 placeholder样式

可通过placeholderFont()和placeholderColor()方法设置 placeholder 的样式，其中placeholderFont()用于设置字体，包括字体大小、字体粗细等，placeholderColor()用于设置字体颜色

1.2.4 文本样式

输入文本的样式可通过fontSize()、fontWeight()、fontColor()等通用属性方法进行设置。

1.3 常用事件

change事件
每当输入的内容发生变化，就会触发 change 事件，开发者可使用onChange()方法为TextInput组件绑定 change 事件，该方法的参数定义如下
```
onChange(callback: (value: string) => void)
```
其中value为最新内容。
焦点事件
焦点事件包括获得焦点和失去焦点两个事件，当输入框获得焦点时，会触发 focus 事件，失去焦点时，会触发 blur 事件，开发者可使用onFocus()和onBlur()方法为 TextInput 组件绑定相关事件，两个方法的参数定义如下
```
onFocus(event: () => void)    
```
```
onBlur(event: () => void)
```

二、进度条

2.1 参数

Progress组件的参数定义如下

Progress(options: {value: number, total?: number, type?: ProgressType})

value
value属性用于设置当前进度值。
total
total属性用于设置总值。
type
type属性用于设置进度条类型，可通过ProgressType枚举类型进行设置，可选的枚举值如下

名称	描述	效果
ProgressType.Linear	线性样式
ProgressType.Ring	环形无刻度样式
ProgressType.Eclipse	月食样式
ProgressType.ScaleRing	环形有刻度样式
ProgressType.Capsule	胶囊样式

2.2 常用属性

2.2.1 进度条样式

可通过style()调整进度条的样式，例如进度条的宽度，该方法的参数类型定义如下

style({strokeWidth?: string|number|Resource,scaleCount?: number,scaleWidth?: string|number|Resource})

strokeWidth
strokeWidth属性用于设置进度条的宽度，默认值为4vp。该属性可用于Linear、Ring、ScaleRing三种类型，效果如下
scaleCount
scaleCount属性用于设置ScaleRing的刻度数，默认值为120。效果如下
scaleWidth
scaleCount属性用于设置ScaleRing的刻度线的宽度，默认值为2vp。效果如下
2.2.2 进度条颜色
进度条的颜色可通过color()和backgroundColor()方法进行设置，其中color()用于设置前景色，backgroundColor()用于设置背景色，例如

三、弹窗

3.1 消息提示

3.1.1 使用说明

可使用@ohos.promptAction模块中的showToast()方法显示 Toast 提示，使用时需要先导入@ohos.promptAction模块，如下

import promptAction from '@ohos.promptAction'

showToast()方法的参数定义如下

showToast(options: { message: string | Resource,duration?: number,bottom?: string | number})

message
message属性用于设置提示信息
duration
duration属性用于设置提示信息停留时长，单位为毫秒，取值范围是[1500,10000]
bottom
bottom属性用于设置提示信息到底部的距离

3.2 警告对话框

3.2.1 使用说明

可使用全局方法AlertDialog.show()显示警告对话框

3.3 操作列表弹框

3.3.1 使用说明

可使用全局方法ActionSheet.show()显示操作列表弹窗，

3.4 选择器弹窗

3.3.1 使用说明

类型	文档地址
TextPickerDialog（文本滑动选择器弹窗）	官方文档
DatePickerDialog（日期滑动选择期弹窗）	官方文档
TimePickerDialog（时间滑动选择器弹窗）	官方文档

3.5 自定义弹窗

3.5.1 使用说明

显示自定义弹窗需要使用CustomDialogController，具体用法可参考相关案例或者官方文档。

四、组件编程技巧

4.1 样式复用

4.1.1 @Styles方法

@Styles方法可定义在组件内或者全局，具体语法如下

组件内

@Entry
@Component
struct StylesPage {
  build() {
    Column() {
      Row({ space: 50 }) {
        Button('确认')
          .type(ButtonType.Normal)
          .backgroundColor(Color.Green)
          .compButtonStyle() //复用样式
          .onClick(() => console.log('确认'))
        Button('取消')
          .type(ButtonType.Normal)
          .backgroundColor(Color.Gray)
          .compButtonStyle() //复用样式
          .onClick(() => console.log('取消'))
      }
    }.width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }

  //组件内样式定义
  @Styles compButtonStyle() {
    .width(100)
    .height(40)
    .borderRadius(10)
  }
}

全局

@Entry
@Component
struct StylesPage {
  build() {
    Column() {
      Row({ space: 50 }) {
        Button('确认')
          .type(ButtonType.Normal)
          .backgroundColor(Color.Green)
          .globalButtonStyle() //复用样式
          .onClick(() => console.log('确认'))
        Button('取消')
          .type(ButtonType.Normal)
          .backgroundColor(Color.Gray)
          .globalButtonStyle() //复用样式
          .onClick(() => console.log('取消'))
      }
    }.width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

//全局样式定义
@Styles function globalButtonStyle() {
  .width(100)
  .height(40)
  .borderRadius(10)
}

注意

1. 组件内的@Styles方法只能在当前组件中使用，全局的@Styles方法目前只允许在当前的.ets文件中使用
2. 组件内定义@Styles方法时不需要使用function关键字，全局的@Styles方法需要使用function关键字
3. @Styles方法中只能包含通用属性方法和通用事件方法
4. @Styles方法不支持参数

4.1.2 @Extend方法

@Extend装饰的方法同样可用于组件样式的复用，与@Styles不同的是，@Extend方法只能定义在全局。并且@Extend方法只能用于指定类型的组件，例如以下方法只能用于Button组件（可以理解为是Button组件的扩展样式）

@Extend(Button) function buttonStyle(){
  ...
}

由于@Extend方法只能用于指定类型的组件，因此方法中可包含指定组件的专有属性方法和专有事件方法。另外，@Extend方法还支持参数，具体语法如下

@Entry
@Component
struct ExtendPage {
  build() {
    Column() {
      Row({ space: 50 }) {
        Button('确认')
          .buttonExtendStyle(Color.Green, () => console.log('确认')) //复用样式
        Button('取消')
          .buttonExtendStyle(Color.Gray, () => console.log('取消')) //复用样式
      }
    }.width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

//样式定义
@Extend(Button) function buttonExtendStyle(color: Color, callback: () => void) {
  .width(100)
  .height(40)
  .borderRadius(10)
  .type(ButtonType.Normal)
  .backgroundColor(color)
  .onClick(callback)
}

总结

1. @Extend方法只能定义在全局，使用范围目前只限于当前的.ets文件
2. @Extend方法用于特定类型的组件，因此可包含该组件的专有属性方法和专有事件方法
3. @Extend方法支持参数

4.2 UI结构复用

4.2.1 概述

当页面有多个相同的UI结构时，若每个都单独声明，同样会有大量重复的代码。为避免重复代码，可以将相同的UI结构提炼为一个自定义组件，完成UI结构的复用。
除此之外，ArkTS还提供了一种更轻量的UI结构复用机制@Builder方法，开发者可以将重复使用的UI元素抽象成一个@Builder方法，该方法可在build()方法中调用多次，以完成UI结构的复用。

4.2.2 语法说明

@Builder方法同样可以定义在组件内或者全局，具体语法如下

组件内

@Entry
@Component
struct BuilderPage {
  build() {
    Column() {
      Row({ space: 50 }) {
        //复用UI结构
        this.compButtonBuilder($r('app.media.icon_edit'), '编辑', () => console.log('编辑'))
        this.compButtonBuilder($r('app.media.icon_send'), '发送', () => console.log('发送'))
      }
    }.width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }

  //定义UI结构
  @Builder compButtonBuilder(icon: Resource, text: string, callback: () => void) {
    Button() {
      Row({ space: 10 }) {
        Image(icon)
          .width(25)
          .height(25)
        Text(text)
          .fontColor(Color.White)
          .fontSize(25)
      }
    }.width(120)
    .height(50)
    .onClick(callback)
  }
}

全局

@Entry
@Component
struct BuilderPage {
  build() {
    Column() {
      Row({ space: 50 }) {
        //复用UI结构
        globalButtonBuilder($r('app.media.icon_edit'), '编辑', () => console.log('编辑'))
        globalButtonBuilder($r('app.media.icon_send'), '发送', () => console.log('发送'))
      }
    }.width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

//定义UI结构
@Builder function globalButtonBuilder(icon: Resource, text: string, callback: () => void) {
    Button() {
      Row({ space: 10 }) {
        Image(icon)
          .width(25)
          .height(25)
        Text(text)
          .fontColor(Color.White)
          .fontSize(25)
      }
    }.width(120)
    .height(50)
    .onClick(callback)
}

注意

1. 组件内的@Builder方法可通过this访问当前组件的属性和方法，而全局的@Builder方法则不能
2. 组件内的@Builder方法只能用于当前组件，全局的@Builder方法导出（export）后，可用于整个应用。

4.2.3 @Builder方法参数传递规则

@Builder方法具有两种参数传递机制——按值传递和按引用传递。当只有一个参数且参数为对象字面量时为按引用传递，其余情况均为按值传递。
按引用传递时，若传递的参数为状态变量，则状态变量的变化将会触发@Builder方法内部UI的刷新；按值传递时则不会。

4.2.4 @Builder方法和自定义组件的区别

@Builder方法和自定义组件虽然都可以实现UI复用的效果，但是两者还是有着本质的区别的，其中最为显著的一个区别就是自定义组件可以定义自己的状态变量，而@Builder方法则不能。以下案例中，每个待办事项的UI结构都相同，因此可考虑将其提炼为一个自定义组件或者@Builder方法，但是由于每个待办事项均有已完成和未完成两种状态，因此需要为每个待办事项都定义一个状态变量，所以此时就只能使用自定义组件而不能使用@Builder方法。

总结
若复用的UI结构没有状态，推荐使用@Builder方法，否则使用自定义组件。

4.2.5 @BuilderParam

@BuilderParam用于装饰自定义组件（struct）中的属性，其装饰的属性可作为一个UI结构的占位符，待创建该组件时，可通过参数为其传入具体的内容。（其作用类似于Vue框架中的slot）。

组件定义

@Component
struct Container {
   //@BuilderParam属性
  @BuilderParam content: () => void

  build() {
    Column() {
      Text('其他内容') //其他内容
      this.content(); //占位符
      Button('其他内容') //其他内容
    }
  }
}

UI结构定义

@Builder function contentBuilder1() {
  ...
}

@Builder function contentBuilder2() {
  ...
}

@Builder function contentBuilder3() {
  ...
}

组件创建

Container({ content: contentBuilder1 })

Container({ content: contentBuilder2 })

Container({ content: contentBuilder3 })

例子：

@Entry
@Component
struct BuilderParamPage {
  build() {
    Column({ space: 50 }) {
      //创建卡片组件（传参）
      Card({ content: imageBuilder })

      //创建卡片组件（"子组件"）
      Card() {
        Column({ space: 10 }) {
          Text('鸿蒙操作系统')
            .fontSize(25)
            .fontWeight(FontWeight.Bold)
          Text('鸿蒙操作系统是一款由华为公司开发的多设备统一操作系统，致力于实现无缝连接和协同工作。其采用分布式架构，支持多终端智能互联，提供高效、安全、流畅的用户体验。')
        }
      }
    }.width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

//卡片内容
@Builder function imageBuilder() {
  Column({ space: 10 }) {
    Image($r('app.media.img_harmony'))
      .width(300)
      .height(150)
    Text('鸿蒙操作系统')
  }
}

//卡片组件
@Component
struct Card {
  @BuilderParam content: () => void; //@BuilderParam属性

  build() {
    Column() {
      this.content(); //占位符
    }.width('90%')
    .padding(10)
    .borderRadius(10)
    .shadow({ radius: 20 })
  }
}

三、鸿蒙开发-常用组件二(文本输入、进度条、弹框、组件编程技巧)

一、文本输入

1.1 参数

1.2 常用属性

1.2.1 输入框类型

1.2.2 光标样式

1.2.3 placeholder样式

1.2.4 文本样式

1.3 常用事件

二、进度条

2.1 参数

2.2 常用属性

2.2.1 进度条样式

2.2.2 进度条颜色

三、弹窗

3.1 消息提示

3.1.1 使用说明

3.2 警告对话框

3.2.1 使用说明

3.3 操作列表弹框

3.3.1 使用说明

3.4 选择器弹窗

3.3.1 使用说明

3.5 自定义弹窗

3.5.1 使用说明

四、组件编程技巧

4.1 样式复用

4.1.1 @Styles方法

4.1.2 @Extend方法

4.2 UI结构复用

4.2.1 概述

4.2.2 语法说明

4.2.3 @Builder方法参数传递规则

4.2.4 @Builder方法和自定义组件的区别

4.2.5 @BuilderParam

玲小叮当

引用和评论

八、鸿蒙开发-网络请求、应用级状态管理

“一起学 HarmonyOS”第二弹来啦！

HarmonyOS Next 应用实战案例—“马背上的家乡”元服务

API接口设计的未来趋势：探索技术方向与实践方案

HarmonyOS 如何获取设备信息（系统、版本、网络连接状态）

构建安全护盾：HarmonyOS 应用的数据安全审计与日志管理实战

如何构建安全可靠的 HarmonyOS 应用