uni-app 之 下拉刷新

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

启用下拉刷新

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

pages.json 配置方式
json 复制代码
{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "enablePullDownRefresh": true,
        "backgroundTextStyle": "dark"
      }
    }
  ]
}
页面级配置(Vue 文件中)
javascript 复制代码
export default {
  onPullDownRefresh() {
    // 下拉刷新触发时执行
    this.refreshData();
  },
};

相关 API

1. uni.startPullDownRefresh()

主动触发下拉刷新

参数说明:

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

示例代码:

javascript 复制代码
// 主动触发下拉刷新
uni.startPullDownRefresh({
  success: function () {
    console.log("开始下拉刷新");
  },
});
2. uni.stopPullDownRefresh()

停止当前页面的下拉刷新

参数说明:

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

示例代码:

javascript 复制代码
// 停止下拉刷新
uni.stopPullDownRefresh();

完整实现示例

方法一:通过页面生命周期函数实现
javascript 复制代码
export default {
  data() {
    return {
      list: [],
    };
  },
  onPullDownRefresh() {
    // 下拉刷新触发
    this.refreshData();
  },
  methods: {
    refreshData() {
      // 模拟请求数据
      setTimeout(() => {
        this.list = this.getNewData();
        // 数据加载完成后停止下拉刷新
        uni.stopPullDownRefresh();
      }, 2000);
    },
    getNewData() {
      // 获取新数据的逻辑
      return ["新数据1", "新数据2", "新数据3"];
    },
  },
};
方法二:主动触发下拉刷新
javascript 复制代码
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 中的相关配置
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 提示提升用户体验

最佳实践

javascript 复制代码
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);
          },
        });
      });
    },
  },
};
相关推荐
csdn_aspnet30 分钟前
在 Docker 容器中本地运行 SQL Server
运维·docker·容器·sqlserver
叼烟扛炮1 小时前
[LangChain] 学习笔记(15):为什么你的重试没用——429、抖动、fallback 与熔断
java·服务器·前端
hi_ro_a1 小时前
Ext系列⽂件系统详解
linux·服务器·操作系统
Z21-X3 小时前
云原生运维学习笔记:Kubernetes Volume 与 Secret 实验
运维·笔记·学习·云原生·kubernetes
你住过的屋檐4 小时前
【SeaweedFS】Linux上搭建SeaweedFS文件存储服务完整教程
linux·运维·服务器
Decay__5 小时前
PostgreSQL 体系架构全解 —— 进程模型、共享内存、MVCC 与 WAL 预写日志深入
运维·数据库·sql·mysql·架构
分布式存储与RustFS5 小时前
桶里的文件想当目录使:用 ZeroFS 把 RustFS 挂成一棵 POSIX 树
运维·云原生·开源·对象存储·分布式存储·s3·性能基准
老余说AI5 小时前
跨境电商、课程出海:六款多语言视频翻译工具选型指南
大数据·运维·人工智能
分布式存储与RustFS6 小时前
向量表别堆本地盘:用 LanceDB 把数据集建在 RustFS 上
运维·云原生·开源·对象存储·分布式存储·s3·性能基准
2401_868534787 小时前
天融信网络安全面试题
服务器·网络