harmony OS NEXT-Refresh 容器组件

鸿蒙Harmony-Refresh 容器组件笔记

1. 组件概述

• 作用：用于实现下拉刷新功能，通常包裹可滚动组件（如 Scroll/List/Grid），提供数据刷新的交互体验。
• 核心功能：监听下拉动作、触发刷新状态、自定义刷新 UI。

---

2. 导入方式

import { Refresh } from '@ohos.arkui.advanced'

---

3. 子组件

• 必须包含且只能包含一个子组件（通常为 Scroll/List/Grid 等滚动容器）。

• 示例：

  Refresh() {
    Scroll() {
      // 内容区域
    }
  }

---

4. 关键属性

属性名	类型	说明
refreshing	boolean	控制刷新状态（true 表示正在刷新，false 结束刷新）
offset	`number	string`	下拉触发刷新的阈值（单位：vp）
friction	`number	string`	下拉阻力系数（值越大，下拉越费力）
disabled	boolean	是否禁用下拉刷新功能（默认 false）

---

5. 事件说明

事件名	触发时机	回调参数
onStateChange(callback: (state: RefreshStatus) => void)	下拉状态变化时触发	state 表示当前状态： - Inactive（未激活） - Drag（拖动中） - OverDrag（超过阈值） - Refresh（刷新中） - Done（刷新完成）
onRefreshing(callback: () => void)	用户下拉超过阈值松手后触发	无

---

6. 使用示例

@Entry
@Component
struct RefreshExample {
  @State isRefreshing: boolean = false

  build() {
    Column() {
      Refresh({ refreshing: this.isRefreshing, offset: 120 }) {
        Scroll() {
          // 滚动内容
        }
      }
      .onStateChange((state: RefreshStatus) => {
        console.log(`Refresh state: ${state}`)
      })
      .onRefreshing(() => {
        // 模拟异步加载
        setTimeout(() => {
          this.isRefreshing = false // 结束刷新
        }, 2000)
      })
    }
  }
}

---

7. 注意事项

1. 层级关系：Refresh 必须是滚动容器的直接父组件。
2. 状态控制：刷新完成后需手动将 refreshing 设为 false。
3. 性能优化：避免在 onRefreshing 中执行耗时操作，建议使用异步任务。
4. 样式定制：可通过子组件自定义加