封面图片

自定义刷新指示器

轻松创建你自己的自定义刷新指示器小部件！

特性：

创建完全自定义的刷新指示器小部件。
快速更改材料刷新指示器的内容。
在水平列表上触发刷新指示器（在线示例）。
从前缘、后缘或两个滚动边缘触发刷新指示器。

简而言之；在线演示！

快速开始

CustomMaterialIndicator

如果你只想替换材料指示器的内容，可以使用 CustomMaterialIndicator 小部件，它构建了一个材料容器。除了内置的 RefreshIndicator 之外，它还支持水平列表和从两个边缘触发（参见 trigger 参数）。

CustomMaterialIndicator(
  onRefresh: onRefresh, // 你的刷新逻辑
  backgroundColor: Colors.white,
  indicatorBuilder: (context, controller) {
    return Padding(
      padding: const EdgeInsets.all(6.0),
      child: CircularProgressIndicator(
        color: Colors.redAccent,
        value: controller.state.isLoading ? null : math.min(controller.value, 1.0),
      ),
    );
  },
  child: child,
)

效果：

CustomRefreshIndicator

使用 CustomRefreshIndicator 小部件为你的 Flutter 应用程序升级定制刷新指示器。只需包裹你的可滚动列表，并设计你独特的指示器。就是这么简单！😏

CustomRefreshIndicator(
  onRefresh: onRefresh, // 你的刷新逻辑
  builder: (context, child, controller) {
    // 在这里放置你的自定义指示器。
    // 需要灵感？看看示例应用程序！
    return MyIndicator(
      child: child,
      controller: controller,
    );
  },
  child: ListView.builder(
    itemBuilder: (_, index) => Text('项目 $index'),
  ),
)

效果：可能性是什么？

你的创造力设定了界限！浏览我们的示例（只需向下滚动一点 👇）看看你可以构建什么。从微妙的动画到引人注目的视觉效果，让刷新动作成为一个愉悦的时刻。🚀

示例

所有这些示例都可以在示例应用程序中找到。

飞机指示器	冰淇淋	扭曲

[源代码] [演示]	[源代码] [演示]	[源代码] [演示]

完整状态	下拉获取更多	信封

[源代码] [演示]	[源代码] [演示]	[源代码] [演示]

可控制的	基于拖动细节	你的指示器
		你创建了一个很棒的刷新指示器吗？这个位置是为你准备的。
[源代码] [演示]	[源代码] [演示]	[打开拉取请求]

文档

使用方法
CustomRefreshIndicator 参数
指示器状态
处理状态变化
触发模式
IndicatorController 属性
IndicatorController 展示
支持

使用方法

这里是如何使用 CustomRefreshIndicator 的快速示例：

CustomRefreshIndicator(
  onRefresh: onRefresh,
  child: ListView(
    // 你的 ListView 内容在这里
  ),
  builder: (BuildContext context, Widget child, IndicatorController controller) {
    // 在这里返回你的自定义指示器小部件
  },
)

CustomRefreshIndicator 参数

基本

child (Widget): 将被下拉以触发刷新的滚动视图的内容。
builder (IndicatorBuilder): 返回将用作刷新指示器的小部件的函数。
onRefresh (AsyncCallback): 刷新开始时的回调。应返回一个 Future。
controller (IndicatorController?): 管理刷新指示器的状态和交互。

时间和持续时间

durations (RefreshIndicatorDurations)
- cancelDuration: 取消后隐藏指示器的持续时间。
- settleDuration: 释放后指示器稳定的持续时间。
- finalizeDuration: 刷新后隐藏指示器的持续时间。
- completeDuration: onRefresh 动作完成后指示器在完成状态保持可见的可选持续时间。如果未指定，指示器将跳过 complete 状态并直接过渡到 finalizing 状态，而不会保持在完成状态。

状态跟踪

onStateChanged (OnStateChanged?): 指示器状态变化时将被调用的回调。

自定义

notificationPredicate (ScrollNotificationPredicate): 确定哪些 ScrollNotifications 将触发指示器。
leadingScrollIndicatorVisible (bool): 前导滚动指示器的可见性。
trailingScrollIndicatorVisible (bool): 尾随滚动指示器的可见性。

触发行为

offsetToArmed (double?): 触发刷新的像素距离。
containerExtentPercentageToArmed (double?): 激活指示器的容器范围百分比。
trigger (IndicatorTrigger): 定义可以从哪个边缘触发刷新。
triggerMode (IndicatorTriggerMode): 配置触发刷新的条件。

性能

autoRebuild (bool): 是否在控制器更新时自动重建指示器。

指示器状态

CustomRefreshIndicator 管理各种状态以提供关于刷新过程的反馈。理解这些状态将帮助你自定义刷新指示器的行为和外观。

状态	值范围	描述
`idle`	`0.0`	默认状态，没有交互发生。指示器不可见。
`dragging`	`0.0` 到 `1.0`	用户正在下拉，但还未达到触发刷新的阈值。
`armed`	大于等于 `1.0`	下拉已超过阈值。现在释放将触发 onRefresh 回调。
`canceling`	动画回到 `0.0`	在达到阈值之前停止下拉；不会触发刷新，指示器收回。
`loading`	稳定在 `1.0`	onRefresh 回调处于活动状态，表示正在进行刷新操作。
`complete`	稳定在 `1.0`	刷新完成，如果设置了 completeDuration，指示器保持完全可见。
`finalizing`	`1.0` 到 `0.0`	刷新操作已完成，指示器正在动画回到初始状态。

每个状态转换都提供了一个机会来动画或调整 UI，为用户提供无缝和交互式的体验。

处理状态变化

要对状态变化做出反应，你可以这样设置 onStateChanged 回调：

CustomRefreshIndicator(
  onRefresh: onRefresh,
  // 使用 onStateChanged 回调跟踪状态变化。
  onStateChanged: (IndicatorStateChange change) {
    // 从拖动状态转换到准备状态时，做些事情：
    if (change.didChange(from: IndicatorState.dragging, to: IndicatorState.armed)) {
      // 处理准备状态，例如，播放声音，开始动画等。
    }
    // 从任何其他状态返回到空闲状态时，做些其他事情：
    else if (change.didChange(to: IndicatorState.idle)) {
      // 重置任何动画，更新 UI 元素等。
    }
    // 根据需要处理其他状态变化...
  }
  // 其他属性...
)

这种设置让你可以灵活地自定义用户与刷新指示器交互时的体验。例如，当状态从拖动变为准备时，你可以开始一个动画，向用户表明他们的动作将触发刷新。

触发模式

CustomRefreshIndicator 小部件提供了灵活的触发模式，定义了在可滚动列表中如何以及在哪里可以启动下拉刷新手势。

trigger (IndicatorTrigger)

这个属性决定了下拉刷新可以从列表的哪个边缘触发。它对于可以使用 reverse 参数反转的列表特别有用。

值	描述
`leadingEdge`	下拉刷新手势只能从列表的前缘触发。对于标准列表通常是顶部，但当列表反转时变成底部。
`trailingEdge`	下拉刷新只能从列表的后缘触发。通常是底部，但对于反转的列表则变成顶部。
`bothEdges`	手势可以从列表的前缘和后缘触发，无论用户从哪一端开始拖动都可以实现下拉刷新功能。

triggerMode (IndicatorTriggerMode)

此属性控制了 CustomRefreshIndicator 如何根据拖动开始时可滚动区域的位置来激活。其行为类似于内置 RefreshIndicator 小部件的 triggerMode。

值	描述
`anywhere`	可以从可滚动内容的任何位置触发刷新，而不仅仅是从边缘。
`onEdge`	只有当拖动手势开始时可滚动内容处于边缘位置，才会触发刷新。

默认情况下，triggerMode 设置为 onEdge，这意味着刷新操作通常在用户从内容的最顶部或最底部拖动时触发，具体取决于列表方向和 trigger 属性设置。

这些模式为开发者提供了对用户与刷新机制交互的控制，确保了适合应用功能上下文的流畅直观的用户体验。

IndicatorController 属性

CustomRefreshIndicator 小部件配备了一个控制器，让你可以访问刷新指示器的当前状态和行为。以下是对控制器属性的深入解析。

state (IndicatorState)

此属性表示指示器的当前状态。它反映了用户与下拉刷新手势的交互，以及指示器对这些交互的响应。

关于状态的更多信息可以在指示器状态部分找到。

edge (IndicatorEdge?)

此属性指示下拉刷新手势从列表的哪一端开始。

值	描述
`start`	手势从列表开始处（通常是顶部）开始。
`end`	手势从列表末端（通常是底部）开始。

当 trigger 设置为 bothEdges 时，edge 属性特别有用，允许从列表的起始或结束处识别手势。

side (IndicatorSide)

side 属性决定了指示器"应该"出现在可滚动区域的哪一侧。

值	描述
`top`	将指示器放置在可滚动内容的顶部。
`bottom`	将指示器放置在可滚动内容的底部。
`left`	将指示器放置在可滚动内容的左侧。
`right`	将指示器放置在可滚动内容的右侧。
`none`	指示器不会显示在任何一侧。

direction (AxisDirection)

此属性标识可滚动内容移动的轴向。可以是 up、down、left 或 right。

scrollingDirection (ScrollDirection)

这反映了用户当前在可滚动内容中滚动的方向。它有助于确定指示器对用户滚动操作的适当响应。

dragDetails (DragUpdateDetails?)

此属性提供了有关拖动更新事件的详细信息，包括拖动的位置和增量。

属性	描述
`globalPosition`	拖动更新发生时指针的全局位置。
`delta`	自上次更新事件以来指针移动的增量距离。
`primaryDelta`	沿主轴的增量距离（例如，对于垂直滚动列表来说是垂直方向）。

当你想根据用户拖动的精确移动实现自定义行为时，dragDetails 属性非常有价值，允许对刷新指示器的响应进行精细控制。