HarmonyOS 鸿蒙Next中List组件在滚动到顶部时如何实现“下拉刷新”动画？

【背景知识】

• Refresh是用于下拉刷新并显示动效的容器组件，入参RefreshOptions包含参数builder或refreshingContent，二者都是用于设置自定义刷新区域的显示内容，不可同时使用。builder参数的类型为CustomBuilder，结合@Builder自定义构建函数使用，refreshingContent参数的类型为ComponentContent，有关使用规格参考BuilderNode。这两个参数在Refresh中的使用可参考示例3（自定义刷新区域显示内容-builder）和示例4（自定义刷新区域显示内容-refreshingContent）。
• ComponentContent是组件内容的实体封装，其对象支持在非UI组件中创建与传递。使用时需要创建对应节点所需的UI上下文UIContext和WrappedBuilder封装的builder函数。

【解决方案】

开发者可以直接使用Refresh实现刷新，也可以通过设置自定义刷新区域显示内容，实现带箭头旋转和文字提示：

import { ComponentContent } from '@ohos.arkui.node';

const PULL_REFRESHING = '刷新中...';

@Entry
@Component
struct MainTab {
  @Builder
  barBars() {
    Text('BAR').margin({ top: 20, bottom: 20 }).fontSize(18).fontWeight('bold');
  }

  @Builder
  barContents() {
    Tabs() {
      TabContent() {
        RefreshExample();
      };
    }
    .layoutWeight(1)
    .width('100%')
    .barHeight(0)
    .barMode(BarMode.Scrollable)
    .barOverlap(false)
    .fadingEdge(false);
  }

  build() {
    Column() {
      TopSvBar({
        bars: this.barBars,
        content: this.barContents
      });
    }.width('100%').height('100%');
  }
}

@Component
struct TopSvBar {
  @BuilderParam bars: () => void = this.barContents;
  @BuilderParam content: () => void = this.barContents;

  @Builder
  barContents() {
  }

  build() {
    Column() {
      Text('标题').margin({ top: 20, bottom: 20 }).fontSize(18).fontWeight('bold');
      Column() {
        this.bars();
      }.height(50);

      Column() {
        this.content();
      }.layoutWeight(1);
    };
  }
}

class Params {
  angle: number = 0;

  constructor(angle: number) {
    this.angle = angle;
  }
}


@Builder
function customRefreshingContent(params: Params) {
  Row() {
    Text(){
      SymbolSpan($r('sys.symbol.arrow_clockwise'))
        .fontWeight(FontWeight.Lighter)
        .fontSize(20)
    }
      .rotate({ angle: params.angle })
      .width(20)
      .height(20);
    Text('刷新中').fontSize(16).margin({ left: 20 });
  }
  .alignItems(VerticalAlign.Center)
  .width('100%')
  .justifyContent(FlexAlign.Center)
  .constraintSize({ minHeight: 32 });
}


@Component
struct RefreshExample {
  @State isRefreshing: boolean = false;
  @State refreshString: string = '下拉刷新';
  private contentNode?: ComponentContent<Object> = undefined;
  private params: Params = new Params(0);
  maxRefreshingHeight: number = 200.0;
  @State ratio: number = 1;
  @State arr: String[] = ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '10'];
  colors: [ResourceColor | LinearGradient, number][] = []; // 组件进度条颜色配置


  // 设置进度条颜色
  setColors(percentage: number) {
    this.colors = [['#FF585E70', percentage], ['#ffffff', 1 - percentage]];
  }

  @State @Watch('valueChange') currentValue: number = 0; // 当前值

  // 计算当前值占总的百分比
  getPercentage(): number {
    return Math.min(this.currentValue / 100, 1);
  }

  // 当前值改变监听
  valueChange() {
    this.setColors(this.getPercentage());
  }

  aboutToAppear(): void {
    let uiContext = this.getUIContext();
    this.contentNode = new ComponentContent(uiContext, wrapBuilder(customRefreshingContent), this.params);
  }

  build() {
    Column() {
      Refresh({ refreshing: $$this.isRefreshing, refreshingContent: this.contentNode }) {
        List() {
          ForEach(this.arr, (item: string) => {
            ListItem() {
              Text('' + item)
                .width('70%')
                .height(80)
                .fontSize(16)
                .margin(10)
                .textAlign(TextAlign.Center)
                .borderRadius(10)
                .backgroundColor(0xFFFFFF);
            };
          }, (item: string) => item);
        }
        .onScrollIndex((first: number) => {
          console.info(first.toString());
        })
        .width('100%')
        .height('100%')
        .alignListItem(ListItemAlign.Center)
        .scrollBar(BarState.Off);
      }
      .pullDownRatio(this.ratio)
      .backgroundColor(0x89CFF0)
      .pullToRefresh(true)
      .refreshOffset(64)
      .onOffsetChange((offset: number) => {
        // 越接近最大距离，下拉跟手系数越小
        this.ratio = 1 - Math.pow((offset / this.maxRefreshingHeight), 3);
      })
      .onStateChange((refreshStatus: RefreshStatus) => {
        if (refreshStatus === 3) {
          this.refreshString = PULL_REFRESHING;
          this.getUIContext().animateTo({ curve: Curve.Linear, iterations: 5, duration: 1000 }, () => {
            this.params.angle = 360;
            // 更新自定义组件内容
            this.contentNode?.update(this.params);
          });
        }
      })
      .onRefreshing(() => {
        setTimeout(() => {
          this.isRefreshing = false;
          this.contentNode?.update(this.params.angle = 0);
        }, 5000);
        console.info('onRefreshing test');
      });
    };
  }
}

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

通过builder参数自定义刷新区域显示内容。可根据onStateChange回调参数RefreshStatus，在下拉过程中改变箭头方向和文字提示，以及刷新中动效。

// 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("Refreshing...").fontSize(16).margin({ left: 20 })
      }
      .alignItems(VerticalAlign.Center)
    }
    .align(Alignment.Center)
    .clip(true)
    // 设置最小高度约束保证自定义组件高度随刷新区域高度变化时自定义组件高度不会低于minHeight。
    .constraintSize({ minHeight: 32 })
    .width("100%")
  }

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