uni-app 之 下拉刷新

下拉刷新是移动端常见的交互方式，用户通过下拉手势触发页面数据更新。uni-app 提供了完整的下拉刷新功能支持。

启用下拉刷新

在页面的配置中启用下拉刷新功能：

pages.json 配置方式

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "enablePullDownRefresh": true,
        "backgroundTextStyle": "dark"
      }
    }
  ]
}

页面级配置（Vue 文件中）

export default {
  onPullDownRefresh() {
    // 下拉刷新触发时执行
    this.refreshData();
  },
};

相关 API

1. uni.startPullDownRefresh()

主动触发下拉刷新

参数说明：

参数	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数

示例代码：

// 主动触发下拉刷新
uni.startPullDownRefresh({
  success: function () {
    console.log("开始下拉刷新");
  },
});

2. uni.stopPullDownRefresh()

停止当前页面的下拉刷新

参数说明：

参数	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数

示例代码：

// 停止下拉刷新
uni.stopPullDownRefresh();

完整实现示例

方法一：通过页面生命周期函数实现

export default {
  data() {
    return {
      list: [],
    };
  },
  onPullDownRefresh() {
    // 下拉刷新触发
    this.refreshData();
  },
  methods: {
    refreshData() {
      // 模拟请求数据
      setTimeout(() => {
        this.list = this.getNewData();
        // 数据加载完成后停止下拉刷新
        uni.stopPullDownRefresh();
      }, 2000);
    },
    getNewData() {
      // 获取新数据的逻辑
      return ["新数据1", "新数据2", "新数据3"];
    },
  },
};

方法二：主动触发下拉刷新

export default {
  data() {
    return {
      list: [],
    };
  },
  methods: {
    handleRefresh() {
      // 主动触发下拉刷新
      uni.startPullDownRefresh();
    },
    refreshData() {
      // 获取最新数据
      this.fetchData()
        .then((data) => {
          this.list = data;
          // 停止下拉刷新
          uni.stopPullDownRefresh();
        })
        .catch(() => {
          uni.stopPullDownRefresh();
        });
    },
    fetchData() {
      return new Promise((resolve) => {
        setTimeout(() => {
          resolve(["数据1", "数据2", "数据3"]);
        }, 2000);
      });
    },
  },
};

配置项说明

pages.json 中的相关配置

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        // 是否启用下拉刷新
        "enablePullDownRefresh": true,
        // 窗口的背景色
        "backgroundColor": "#ffffff",
        // 下拉 loading 的样式
        "backgroundTextStyle": "dark",
        // 下拉刷新控件的颜色（仅微信小程序）
        "backgroundColorTop": "#ffffff"
      }
    }
  ]
}

注意事项

1. 使用下拉刷新前必须在页面配置中设置 enablePullDownRefresh: true
2. 在 onPullDownRefresh 生命周期函数中处理刷新逻辑
3. 数据加载完成后必须调用 uni.stopPullDownRefresh() 停止刷新动画
4. 在自定义组件中无法触发页面的下拉刷新，需要通过事件传递处理
5. 下拉刷新会阻塞用户交互，建议给用户适当的加载提示
6. 对于复杂的数据加载场景，建议配合 loading 提示提升用户体验

最佳实践

export default {
  data() {
    return {
      list: [],
      loading: false,
    };
  },
  onPullDownRefresh() {
    this.loadData(true);
  },
  methods: {
    async loadData(isRefresh = false) {
      if (!isRefresh && this.loading) return;

      this.loading = true;

      try {
        const data = await this.fetchDataFromServer();

        if (isRefresh) {
          this.list = data; // 刷新时替换数据
          uni.stopPullDownRefresh(); // 停止下拉刷新
        } else {
          this.list = [...this.list, ...data]; // 加载更多时追加数据
        }
      } catch (error) {
        console.error("数据加载失败:", error);
        if (isRefresh) {
          uni.stopPullDownRefresh();
        }
      } finally {
        this.loading = false;
      }
    },

    fetchDataFromServer() {
      return new Promise((resolve, reject) => {
        uni.request({
          url: "https://api.example.com/data",
          success: (res) => {
            resolve(res.data);
          },
          fail: (err) => {
            reject(err);
          },
        });
      });
    },
  },
};