RefreshConfiguration class

控制子树中 SmartRefresher 组件的行为，用法类似于 ScrollConfiguration

核心功能：

  • 全局设置默认的 header 和 footer 指示器
  • 配置刷新和加载的行为参数
  • 调整弹簧动画效果
  • 控制二级刷新的行为

使用示例：

// 在应用根目录设置全局配置
MaterialApp(
  home: RefreshConfiguration(
    headerBuilder: () => ClassicHeader(),
    footerBuilder: () => ClassicFooter(),
    headerTriggerDistance: 80.0,
    footerTriggerDistance: 15.0,
    springDescription: SpringDescription(
      stiffness: 170,
      damping: 16,
      mass: 1.9,
    ),
    enableScrollWhenRefreshCompleted: true,
    enableLoadingWhenFailed: true,
    enableBallisticLoad: true,
    child: YourHomePage(),
  ),
);

// 局部覆盖全局配置
RefreshConfiguration.copyAncestor(
  context: context,
  headerTriggerDistance: 100.0,
  child: SmartRefresher(
    // 这里的 SmartRefresher 将使用局部配置
  ),
);

相关组件：

Inheritance

Constructors

RefreshConfiguration({Key? key, required Widget child, IndicatorBuilder? headerBuilder, IndicatorBuilder? footerBuilder, double dragSpeedRatio = 1.0, ShouldFollowContent? shouldFooterFollowWhenNotFull, bool enableLoadingWhenNoData = false, bool enableSmartPreload = true, bool enableBallisticRefresh = false, SpringDescription springDescription = const SpringDescription(mass: 1.0, stiffness: 364.72, damping: 35.2), bool enableScrollWhenRefreshCompleted = false, bool enableLoadingWhenFailed = true, double twiceTriggerDistance = 150.0, bool skipCanRefresh = false, double? maxOverScrollExtent, bool enableBallisticLoad = true, double? maxUnderScrollExtent, double headerTriggerDistance = 80.0, double footerTriggerDistance = 15.0, bool hideFooterWhenNotFull = false, bool enableRefreshVibrate = false, bool enableLoadMoreVibrate = false, double? topHitBoundary, double? bottomHitBoundary})
创建刷新配置
const
RefreshConfiguration.copyAncestor({Key? key, required BuildContext context, required Widget child, IndicatorBuilder? headerBuilder, IndicatorBuilder? footerBuilder, double? dragSpeedRatio, ShouldFollowContent? shouldFooterFollowWhenNotFull, bool? enableBallisticRefresh, bool? enableBallisticLoad, bool? enableLoadingWhenNoData, bool? enableSmartPreload, SpringDescription? springDescription, bool? enableScrollWhenRefreshCompleted, bool? enableLoadingWhenFailed, double? twiceTriggerDistance, bool? skipCanRefresh, double? maxOverScrollExtent, double? maxUnderScrollExtent, double? topHitBoundary, double? bottomHitBoundary, double? headerTriggerDistance, double? footerTriggerDistance, bool? enableRefreshVibrate, bool? enableLoadMoreVibrate, bool? hideFooterWhenNotFull})
复制祖先节点的 RefreshConfiguration，并可选择性覆盖部分属性

Properties

bottomHitBoundary → double?
位于底部边缘的边界，惯性滚动超过此距离时停止
final
child → Widget
子组件树
final
dragSpeedRatio → double
拖动过度滚动时的速度比例，计算公式：原始物理速度 * dragSpeedRatio
final
enableBallisticLoad → bool
是否通过 BallisticScrollActivity 触发加载
final
enableBallisticRefresh → bool
是否通过 BallisticScrollActivity 触发刷新
final
enableLoadingWhenFailed → bool
当 footer 处于 failed 状态时，是否允许触发加载
final
enableLoadingWhenNoData → bool
当 footer 处于 noMore 状态时，是否允许触发加载
final
enableLoadMoreVibrate → bool
是否启用加载更多震动反馈
final
enableRefreshVibrate → bool
是否启用刷新震动反馈
final
enableScrollWhenRefreshCompleted → bool
刷新完成回弹时，是否允许拖动视口
final
enableSmartPreload → bool
是否启用智能预加载（基于上一次加载高度的一半进行预加载）
final
footerBuilder → IndicatorBuilder?
全局默认 footer 构建器
final
footerTriggerDistance → double
触发加载的 extentAfter 距离
final
hashCode → int
The hash code for this object.
no setterinherited
headerBuilder → IndicatorBuilder?
全局默认 header 构建器
final
headerTriggerDistance → double
触发刷新的过度滚动距离
final
hideFooterWhenNotFull → bool
当列表数据不足一页时，是否隐藏 footer
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
maxOverScrollExtent → double?
超出边缘时的最大过度滚动距离
final
maxUnderScrollExtent → double?
超出边缘时的最大不足滚动距离
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
shouldFooterFollowWhenNotFull → ShouldFollowContent?
当列表数据不足一页时，footer 是否跟随内容
final
skipCanRefresh → bool
当达到触发距离时，是否立即进入刷新状态
final
springDescription → SpringDescription
自定义弹簧动画配置
final
topHitBoundary → double?
位于顶部边缘的边界，惯性滚动超过此距离时停止
final
twiceTriggerDistance → double
触发二级刷新的过度滚动距离
final

Methods

createElement() → InheritedElement
Inflates this configuration to a concrete instance.
inherited
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited
updateShouldNotify(covariant RefreshConfiguration oldWidget) → bool
Whether the framework should notify widgets that inherit from this widget.
override

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

of(BuildContext context) → RefreshConfiguration?