frefresh

助你以最简单的方式实现下拉刷新和上拉加载。

虽然前所未有的简单，但效果却很惊艳。它还支持配置刷新和加载的元素。完整的控制器，可以帮助你控制整个动态过程。

指南

⚙️ 参数 & 接口

? FRefresh 参数

⌨️ FRefreshController

? 参数

? 接口

• void refresh({Duration duration = const Duration(milliseconds: 300)})

主动触发下拉刷新。

[duration] 下拉效果的时长。默认为300ms

• finishRefresh()

结束下拉刷新。

• finishLoad()

结束上拉加载。

• void setOnStateChangedCallback(OnStateChangedCallback callback)

设置状态监听器。例如。

controller.setOnStateChangedCallback((state){
  if (state is RefreshState) {

  }
  if (state is LoadState) {

   }
})

• void setOnScrollListener(OnScrollListener onScrollListener)

设置滚动监听器。接收[ScrollMetrics]。

• void scrollTo(double position, {Duration duration = const Duration(milliseconds: 300)})

滚动到指定位置。

• void scrollBy(double offset, {Duration duration = const Duration(milliseconds: 300)})

滚动指定距离。

• void jumpTo(double position)

跳转到指定位置。

? RefreshState

? LoadState

? 示例

? 刷新示例

这是我们日常开发中最常见的下拉刷新示例了 ?. 相信我，如果你想实现这样的效果，将非常困难！

但是，如果你使用了FRefresh，情况将完全不同。

接下来，我们只需要几行代码就可以完成这个效果的构建。

1. 创建FRefreshController

/// Create a controller
FRefreshController controller = FRefreshController()

2. 创建FRefresh

FRefresh(

  /// Set up the controller
  controller: controller,

  /// create Header
  header: buildRefreshView(),

  /// Need to pass the size of the header area
  headerHeight: 75.0,

  /// Content area widget
  child: ListView.builder(
      physics: NeverScrollableScrollPhysics(),
      shrinkWrap: true,
      ...
  ),

  /// This function will be called back after entering Refreshing
  onRefresh: () {

     /// End refresh via controller
     controller.finishRefresh();
  },
);

完成 ?！

这就是创建下拉刷新所需要做的全部工作。

FRefresh 已经为你处理好了一切，开发者只需要专注于 **Header区域** 和 **内容区域** 的构建。

⚠️ 注意，在FRefresh 中使用ListView、GridView，需要配置它们的physics: NeverScrollableScrollPhysics ()、shrinkWrap: true，否则会影响滚动的效果和布局效果。

? HeaderBuilder 示例

FRefresh(
  controller: controller,

  /// Build the header area with headerBuilder
  headerBuilder: (setter, constraints) {
    return FSuper(

       /// Get the available space in the current header area
       width: constraints.maxWidth,
       height: constraints.maxHeight,
       ...
       onClick:{
          setter((){
             /// Refresh the header area
          })
       },
    );
  },
  headerHeight: 100.0,

  /// Build content area
  child: GridView.builder(),

  /// This function will be called back after entering the refreshing state
  onRefresh: () {

    /// finish refresh
    controller.finishRefresh();
  }
)

FRefresh 提供了非常灵活的 **Header** 区域构建方式，也就是通过 **HeaderBuilder** 函数来完成构建。

在 **HeaderBuilder** 函数中，开发者可以通过参数获取到用于局部刷新 **Header** 区域的刷新函数 **StateSetter** 和 **Header** 区域的实际尺寸。

这样，就给了 **Header** 区域更多的创意空间。

? 加载示例

对应于下拉刷新，上拉加载效果的构建同样非常简单。

1. 创建FRefreshController

/// Create a controller
FRefreshController controller = FRefreshController()

2. 创建FRefresh

FRefresh(

  /// Setup the controller
  controller: controller,

  /// create Footer area
  footer: LinearProgressIndicator(),

  /// need to setup Footer area height
  footerHeight: 20.0,

  /// create content area
  child: builderContent(),

  /// This function will be called back after entering the Loading state
  onLoad: () {
    
    /// End loading state
    controller.finishLoad();
  },
)

构建上拉同样足够简单，开发者只需要关注 **Footer** 区域和 **内容区域** 的构建，上拉加载过程中的状态改变和视觉效果控制，可以放心的交给 **FRefresh**。

? FooterBuilder 示例

FRefresh(
  controller: controller,

  /// Build Footer Area Widget by FooterBuilder
  footerBuilder: (setter) {

    /// Get refresh status, partially update the content of Footer area
    controller.setOnStateChangedCallback((state) {
      setter(() {
        ...
      });
    });
    return buildFooter();
  },
  footerHeight: 38.0,
  child: buildContent(),
  onLoad: () {
    controller.finishLoad();
  },
)

FRefresh 也提供了 **FooterBuilder** 构建函数，用于构建 **Footer** 区域。通过这个函数，你可以获取到仅刷新 **Footer** 区域的刷新函数 **StateSetter**。

这样，开发者就可以根据状态或者一些其他条件，轻松改变 **footer** 区域的视图，非常贴心 ?。

⚙️ FRefreshController

FRefresh 为开发者提供了贴心的控制器 **FRefreshController**，它支持了许多便捷的能力。

1. 为 FRefresh 添加控制器

/// Create Controller
FRefreshController controller = FRefreshController()

/// Configure controller for FRefresh
FRefresh(
  controller: controller,
)

开发者创建好控制器，再将其设置到 **FRefresh** 中，控制器便可以开始监听此 **FRefresh** 的状态并对其进行控制。

2. 停止刷新或加载

当触发刷新状态或加载状态时，通常会进行网络请求等数据处理任务，这些任务完成后，我们需要停止刷新状态或加载状态，如何做呢？

• controller.finishRefresh() 可以停止刷新

• controller.finishLoad() 可以停止加载

3. 状态变化监听

controller5.setOnStateChangedCallback((state) {
  /// Refresh status
  if (state is RefreshState) {
  }
  /// Loading state
  if (state is LoadState) {
  }
});

通过上面简单的代码，就可以监听到 **FRefresh** 的状态变化，无论是下拉刷新还是上拉加载。

4. 滚动监听

controller.setOnScrollListener((metrics) {
  /// Get scroll information
});

FRefreshController 添加滚动监听也是非常方便的，接收的参数为 [ScrollMetrics]，可以获取到非常全面的信息，如 **当前滚动距离**，**最大滚动距离**，**是否超出滚动范围** 等等。

5. 主动触发刷新

通过 **FRefreshController**，开发者也可以主动触发刷新，并且可以指定滑到刷新位置的时长。

controller.refresh(duration: Duration(milliseconds: 2000));

这个功能在很多场景下都很有用。

6. 滚动控制

FRefreshController 为开发者提供了多种贴心细致的滚动控制供选择。

/// Scroll to the specified position
controller.scrollTo(100.0, duration:Duration(milliseconds: 2000));

/// Scroll the specified distance
controller.scrollBy(20.0, duration:Duration(milliseconds: 800));

/// Jump to the specified position
controller.jumpTo(100.0);

这让很多漂亮的交互效果的构建更加容易。

? 如何使用？

在项目中添加依赖到 pubspec.yaml 文件

pub 依赖

dependencies:
  frefresh: ^<version number>

Git 依赖

dependencies:
  frefresh:
    git:
      url: '[email protected]:Fliggy-Mobile/frefresh.git'
      ref: '<Branch number or tag number>'

如何运行 Demo 项目?

1. 将项目clone到本地

2. 进入项目 example 目录，运行以下命令

flutter create .

3. 运行 example 中的 demo

GitHub

https://github.com/Fliggy-Mobile/frefresh