鸿蒙5.0版开发：ArkTS容器组件（Refresh）

本文链接：https://blog.csdn.net/m0_69424697/article/details/142566891

往期鸿蒙全套实战文章必看：

Refresh

可以进行页面下拉操作并显示刷新动效的容器组件。

说明：

该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

该组件从API Version 12开始支持与垂直滚动的Swiper和Web的联动。当Swiper设置loop属性为true时，Refresh无法和Swiper产生联动。

子组件

支持单个子组件。

从API version 11开始，Refresh子组件会跟随手势下拉而下移。

接口

Refresh(value: RefreshOptions)

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

参数：

参数名	参数类型	必填	参数描述
value	RefreshOptions	是	刷新组件参数。

RefreshOptions对象说明

参数	参数名	必填	参数描述
refreshing	boolean	是	当前组件是否正在刷新。默认值：false 该参数支持$$双向绑定变量。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
offset(deprecated)	string \| number	否	下拉起点距离组件顶部的距离。默认值：16，单位vp 从API version 11开始废弃，无替代接口说明： offset取值范围[0vp,64vp]。大于64vp按照64vp处理。不支持百分比，不支持负数。
friction(deprecated)	number \| string	否	下拉摩擦系数，取值范围为0到100。默认值：62 - 0表示下拉刷新容器不跟随手势下拉而下拉。 - 100表示下拉刷新容器紧紧跟随手势下拉而下拉。 - 数值越大，下拉刷新容器跟随手势下拉的反应越灵敏。从API version 11开始废弃，无替代接口
builder10+	CustomBuilder	否	下拉时，自定义刷新样式的组件。说明： API version 10及之前版本，自定义组件的高度限制在64vp之内。API version 11及以后版本没有此限制。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
promptText12+	ResourceStr	否	设置组件底部显示的用户自定义文本。说明：输入文本的限制参考Text组件，使用builder自定义刷新样式时，promptText不显示。

属性

支持通用属性外，还支持以下属性：

refreshOffset12+

refreshOffset(value: number)

设置触发刷新的下拉偏移量。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	number	是	下拉偏移量，单位vp。默认值：64vp 如果取值为0或负数的时候此接口采用默认值64vp。

pullToRefresh12+

pullToRefresh(value: boolean)

设置当下拉距离超过refreshOffset时是否触发刷新。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	boolean	是	是否触发刷新。默认值：true

事件

除支持通用事件外，还支持以下事件：

onStateChange

onStateChange(callback: (state: RefreshStatus) => void)

当前刷新状态变更时，触发回调。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
state	RefreshStatus	是	刷新状态。

onRefreshing

onRefreshing(callback: () => void)

进入刷新状态时触发回调。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

onOffsetChange12+

onOffsetChange(callback: Callback<number>)

下拉距离发生变化时触发回调。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	number	是	下拉距离。单位：vp

RefreshStatus枚举说明

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

名称	值	描述
Inactive	0	默认未下拉状态。
Drag	1	下拉中，下拉距离小于刷新距离。
OverDrag	2	下拉中，下拉距离超过刷新距离。
Refresh	3	下拉结束，回弹至刷新距离，进入刷新状态。
Done	4	刷新结束，返回初始状态（顶部）。

示例

示例1

刷新组件使用默认样式。

// xxx.ets
@Entry
@Component
struct RefreshExample {
  @State isRefreshing: boolean = false
  @State arr: String[] = ['0', '1', '2', '3', '4','5','6','7','8','9','10']

  build() {
    Column() {
      Refresh({ refreshing: $$this.isRefreshing}) {
        List() {
          ForEach(this.arr, (item: string) => {
            ListItem() {
              Text('' + item)
                .width('100%').height(100).fontSize(16)
                .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF)
            }
          }, (item: string) => item)
        }
        .onScrollIndex((first: number) => {
          console.info(first.toString())
        })
        .width('100%')
        .height('100%')
        .divider({strokeWidth:1,color:Color.Yellow,startMargin:10,endMargin:10})
        .scrollBar(BarState.Off)
      }
      .onStateChange((refreshStatus: RefreshStatus) => {
        console.info('Refresh onStatueChange state is ' + refreshStatus)
      })
      .onOffsetChange((value: number) => {
        console.info('Refresh onOffsetChange offset:' + value)
      })
      .onRefreshing(() => {
        setTimeout(() => {
          this.isRefreshing = false
        }, 2000)
        console.log('onRefreshing test')
      })
      .backgroundColor(0x89CFF0)
      .refreshOffset(64)
      .pullToRefresh(true)
    }
  }
}

示例2

自定义刷新组件。

// xxx.ets
@Entry
@Component
struct RefreshExample {
  @State isRefreshing: boolean = false
  @State arr: String[] = ['0', '1', '2', '3', '4','5','6','7','8','9','10']
  @Builder
  customRefreshComponent()
  {
    Stack()
    {
      Row()
      {
        LoadingProgress().height(32)
        Text("正在刷新...").fontSize(16).margin({left:20})
      }
      .alignItems(VerticalAlign.Center)
    }.width("100%").align(Alignment.Center)
  }

  build() {
    Column() {
      Refresh({ refreshing: $$this.isRefreshing,builder:this.customRefreshComponent()}) {
        List() {
          ForEach(this.arr, (item: string) => {
            ListItem() {
              Text('' + item)
                .width('100%').height(100).fontSize(16)
                .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF)
            }
          }, (item: string) => item)
        }
        .onScrollIndex((first: number) => {
          console.info(first.toString())
        })
        .width('100%')
        .height('100%')
        .divider({strokeWidth:1,color:Color.Yellow,startMargin:10,endMargin:10})
        .scrollBar(BarState.Off)
      }
      .onStateChange((refreshStatus: RefreshStatus) => {
        console.info('Refresh onStatueChange state is ' + refreshStatus)
      })
      .onRefreshing(() => {
        setTimeout(() => {
          this.isRefreshing = false
        }, 2000)
        console.log('onRefreshing test')
      })
      .backgroundColor(0x89CFF0)
      .refreshOffset(64)
      .pullToRefresh(true)
    }
  }
}