微信小程序-小程序 API

原创 2025-02-22 14:53:34 1.6k 阅读 AI写同款

收录于

微信小程序开发

铃昕之光

码龄11年墨衍会员 · AI 创作全网分发

883粉丝79篇原创

关注

微信小程序中常见API 1.界面API： wx.navigateTo：在当前页面打开新页面，新页面可以返回到原页面。 wx.redirectTo：关闭当前页面，打开新页面。 wx.reLaunch：关闭所有页面，打开新页面。 wx.switchTab：跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面。 wx.navigateBack：关闭当前页面，返回上一页面。 wx.setNavigationBarTitle：动态设置当前页面的标题。 wx.setNavigationBarColor：设置导航栏颜阅读详情

AI摘要

本文主要介绍了微信小程序的API使用方法，包括网络请求、界面交互、本地存储、路由与通信、上拉加载与下拉刷新以及scroll-view的拓展功能。详细说明了API的分类、异步调用方式、域名配置、界面交互组件的使用以及本地存储的注意事项。对于小程序开发者来说，这些API是实现小程序功能不可或缺的部分。

小程序开发框架提供丰富的微信原生 API，可以方便调起微信提供的能力，比如：获取用户信息、微信登录、微信支付等，小程序提供的 API 几乎都挂载在 wx 对象下，例如：wx.request()、wx.setStorage() 等，wx 对象上实际上就是小程序的宿主环境微信所提供的全局对象。
小程序API分类：

异步 API 支持 callback 和 Promise 两种调用方式：
1、当接口参数 Object 对象中不包含 success/fail/complete 时默认返回 Promise
2、部分接口如 request、uploadFile 本身就有返回值，因此不支持 Promise 风格的调用方式，它们的 promisify 需要开发者自行封装。

二、小程序 API -网络请求

发起网络请求获取服务器的数据，需要调用 wx.request() API。
wx.request 请求的域名必须在微信公众平台配置，否则控制台会有报错：
在这里插入图片描述

微信公众平台配置域名：

配置完成后，重新编辑若仍报错，则需要重启此项目。
如何跳过域名检验：
1、微信开发者工具->右上角[详情]按钮->点击[本地设置]->勾选[不检验合法域名…]

2、在真机上，点击小程序的胶囊区域的分析按钮，在弹框中选择[开发调试]，重启小程序即可。

注：以上两种方式只适用于开发者工具、小程序的开发版和体验版，正式版必须配合法域名。
wxml 文件代码示例：

 <button type="warn" bind:tap="getData">获取数据</button>

js 文件代码示例：

getData(){
    //发起网络请求获取服务器的数据，需要调用 wx.request() API
    wx.request({
      //接口地址
      url: 'https://gmall-prod.atguigu.cn/mall-api/index/findBanner',
      //请求方式
      method:'GET',
      //请求参数
      data:{},
      //请求头
      header:{},
      //API 调用成功后，执行的回调
      success:(res) => {
        console.log(res)
        if (res.data.code === 200){
          this.setData({
            dataList: res.data.data
          })
        }
      },
      //API 调用失败后，执行的回调
      fail:(err) => {
        console.log(err)
      },
      //不管 API 调用成功还是失败后，执行的回调
      complete:(res) => {
        console.log(res)
      }
    })

三、小程序 API -界面交互

1、loading 提示框

小程序提供一些用于界面交互的 API，例如：loading 提示框、消息提示框、模态对话框等 API。
Loading 提示框通常配合网络请求来使用，主要用来提升用户体验，对应的 API 有两个：

1.1、showLoading() 用来显示 loading 提示框
1.2、hideLoading() 用来关闭 loading 提示框

js 文件代码示例：

// 显示 loading 提示框 
    wx.showLoading({
      //提示的内容不会自动换行，如果内容过多超过一行，多出的内容会被隐藏
      title: 'loading...',
      //是否显示透明蒙层，防止触摸穿透
      mask:true
    })
 //关闭 loading 提示框
    wx.hideLoading()

2、模态对话框&消息提示框

2.1、wx.showModal：模态对话框，常用来询问用户是否执行一些操作，例如：用户是否退出登录等
2.2、wx.showToast：消息提示框，根据用户的某些操作来告知操作的结果，例如：退出用户给提示、删除成功给提示等
wxml 文件代码示例：

<button type="primary" bind:tap="deleteHandler">删除商品</button>

js 文件代码示例：

  async deleteHandler() {
    // 模态对话框，常用来询问用户是否执行一些操作
    const { confirm } =  await wx.showModal({
      title: '提示',
      content: '是否删除该商品？',
      // complete 是异步返回的方式
      // complete: (res) => {
      //   if (res.cancel) {}
      //   if (res.confirm) {}
      // }
    })
    if (confirm) {
      // showToast：消息提示框，根据用户的某些操作来告知操作的结果
      wx.showToast({
        title: '删除成功',
        icon: 'none',
        duration: 2000
      })
    } else {
      wx.showToast({
        title: '取消删除',
        icon: 'error',
        duration: 2000
      })
    }
  }

三、小程序 API -本地存储

小程序本地存储是指小程序使用 API 将数据存储在用户设备上，方便小程序运行时或下次启动时快速读取这些数据。
注意事项： 对象类型的数据，可以直接存储获取，无需使用 JSON.stringify()、JSON.parse() 转换

wxml 文件代码示例：

<view>----------- 同步本地存储 ----------- </view>
<button size="mini" plain type="warn" bind:tap="setStorageSync">存储</button>
<button size="mini" plain type="primary" bind:tap="getStorageSync">获取</button>
<button size="mini" plain type="warn" bind:tap="removeStorageSync">删除</button>
<button size="mini" plain type="primary" bind:tap="clearStorageSync">清空</button>
<view>------------ 异步本地存储 ------------- </view>
<button size="mini" plain type="warn" bind:tap="setStorage">存储</button>
<button size="mini" plain type="primary" bind:tap="getStorage">获取</button>
<button size="mini" plain type="warn" bind:tap="removeStorage">删除</button>
<button size="mini" plain type="primary" bind:tap="clearStorage">清空</button>

js 文件代码示例：

  // 将数据存储到本地-同步
  setStorageSync() {
    // 第一个参数：本地存储中指定的 key;第二个参数：需要存储的数据
    wx.setStorageSync('numSync', 1)
    // 如果存储的数据是对象类型，无需使用 JSON.stringify()、JSON.parse() 转换，直接存储或获取即可
    wx.setStorageSync('objSync', { name: 'tom', age: 10})
  },
  // 获取本地存储的数据-同步
  getStorageSync() {
    // 从本地存储的数据中获取指定 key 的数据内容
    const num = wx.getStorageSync('numSync')
    const obj = wx.getStorageSync('objSync')
    console.log(num)
    console.log(obj)
  },
  // 删除本地存储的数据-同步
  removeStorageSync() {
    // 从本地存储的数据中删除指定 key 的数据内容
    wx.removeStorageSync('numSync')
  },
  // 清空本地存储的全部数据-同步
  clearStorageSync() {
    wx.clearStorageSync()
  },
  // 将数据存储到本地-异步
  setStorage() {
    wx.setStorage({
      key: 'num',
      data: 10
    })
    wx.setStorage({
      key: 'obj',
      data: { name: 'jerry', age: 18}
    } )
  },
  // 获取本地存储的数据-异步
  // async、await 等待出现数据，否则获取到的数据可能是空的
  async getStorage() {
    const { data } = await wx.getStorage({
      key: 'obj'
    })    
    console.log(data)
  },
  // 删除本地存储的数据-异步
  removeStorage() {
    // 从本地存储的数据中删除指定 key 的数据内容
    wx.removeStorage({
      key: 'num'
    })
  },
  // 清空本地存储的全部数据-异步
  clearStorage() {
    wx.clearStorage()
  }

四、小程序 API -路由与通信

小程序实现页面的跳转，有两种方式：
1、声明式导航： navigator 组件，详情见：微信小程序开发-各组件
2、编程式导航：使用小程序提供的 API

2.1、路径后可以带参数，参数和路径之间用 ? 分隔，参数键和参数值用 = 相连，不同参数用 & 分隔，例如：path?key=value&key2=value2
2.2、参数需要在跳转到的页面的 onLoad 钩子函数中通过形参进行接收

wxml 文件代码示例：

<button type="warn" plain bind:tap="navigateTo">navigateTo</button>
<button type="primary" plain bind:tap="redirectTo">redirectTo</button>
<button type="warn" plain bind:tap="switchTab">switchTab</button>
<button type="warn" plain bind:tap="reLaunch">reLaunch</button>

js 文件代码示例：

  navigateTo(){
    // 保留当前页面，跳转到应用中其他页面，不能跳转到 tabbar 页面
    wx.navigateTo({
      url: '/pages/list/list?id=1&name=tom',
    })
  },
  redirectTo(){
    // 销毁当前页面，跳转到应用中其他页面，不能跳转到 tabbar 页面
    wx.redirectTo({
      url: '/pages/list/list?id=1&name=tom',
    })
  },
  switchTab(){
   // 隐藏当前页面，跳转到tabbar 页面，不能跳转到非 tabbar 页面，路径后面不能带参数
   wx.switchTab({
     url: '/pages/cart/cart',
   })
  },
  reLaunch(){
   // 关闭所有页面，然后跳转到应用内某一页面
   wx.reLaunch({
     url: '/pages/cart/cart?id=1&name=tom',
   })
  }

list.wxml 文件代码示例：

<button type="primary" plain bind:tap="navigateBack">navigateBack</button>

list.js 文件代码示例：

  navigateBack(){
    //关闭当前页面，返回上一页或返回多级页面，默认返回上一页
    wx.navigateBack({
      delta: 1
    })
  }

五、小程序 API -上拉加载 & 下拉刷新

上拉加载是小程序常见的一种加载方式，当用户滑到页面底部时，会自动加载更多的内容，方便用户继续浏览，小程序中实现上拉加载的方式：

1、在 app.json 的 window 选项中或 page.json 中配置距离页面底部的距离：onReachBottomDistance;默认 50 rpx
2、在 page.js 中定义 onReachBottom 事件监听用户上拉加载

下拉刷新是小程序中常见的一种刷新方式，当用户下拉页面时，页面会自动刷新，以便用户获取最新内容，小程序中实现下拉刷新的方式：

1、在 app.json 的 window 选项中或 page.json 中开启允许下拉，同时可配置窗口、loading 样式等
2、在 page.js 中定义 onPullDownRefresh 事件监听用户下拉动作

注意事项： onReachBottom 和onPullDownRefresh是项目创建时，小程序就自己给我们生成了，所以 js 页面后面的 onReachBottom 和onPullDownRefresh会覆盖掉我们前面写的 onReachBottom 和 onPullDownRefresh，导致最后无法出现效果
.json 文件代码示例：

{
  "usingComponents": {},
  "onReachBottomDistance": 100,
  "enablePullDownRefresh": true,
  "backgroundTextStyle":"light",
  "backgroundColor": "#efefef"
}

.js 文件代码示例：

data: {
    numList: [1, 2, 3]
  },
  onReachBottom() {
    console.log('监听用户上拉加载')
    wx.showLoading({
      title: '数据加载中',
    })
    setTimeout(()=>{
      // 用户上拉加载时，需要对数字进行累加，每次累加 3 个数字
      // 获取数组最后一项 n, n + 1, n + 2, n + 3
      const lastNum = this.data.numList[this.data.numList.length -   1]
      const newArr = [lastNum + 1,lastNum + 2,lastNum + 3]
      this.setData({
        numList:[...this.data.numList, ...newArr]
      })
      wx.hideLoading()
    },1500)
  },
  onPullDownRefresh() {
    console.log('监听用户下拉刷新')
    // 当用户上拉加载更多后，如果用户进行了下拉刷新，需要将数据重置
    this.setData({
      numList:[1, 2, 3]
    })
    // 在下拉刷新后，loading 效果有可能不会回弹回去，需要处理
    if (this.data.numList.length == 3){
      wx.stopPullDownRefresh()
    }
  }

.scss 文件代码示例：

view {
  height: 500rpx;
  display: flex;
  align-items: center;
  justify-content: center;
}
view:nth-child(odd){
  background-color: lightskyblue;
}
view:nth-child(even){
  background-color: lightcoral;
}

.wxml 文件代码示例：

<view wx:for="{{ numList }}" wx:key="*this">{{ item }}</view>

六、小程序 API -拓展-增强 scroll-view

使用 scroll-view 实现上拉加载和下拉刷新功能：

lower-threshold 是针对 scroll-view 的配置，onReachBottomDistance 是针对整个页面的配置，都是距离底部多少距离触发上拉加载
bindscrolltolower 是 scroll-view 配置上拉加载事件处理函数
enable-back-to-top 是 scroll-view 滚动条返回顶部的配置
refresher-enabled 是 scroll-view 是否允许下拉刷新配置
refresher-default-style 是 scroll-view 下拉刷新样式配置
refresher-background 是 scroll-view 下拉刷新背景颜色的配置
bindrefresherrefresh 是 scroll-view 下拉刷新事件处理函数
refresher-triggered 是 scroll-view 下拉刷新当前状态配置

.js 文件代码示例：

data: {
    numList:[1, 2, 3]
  },
  // scroll-view 上拉加载事件处理函数
  getMore() {
    console.log('scroll-view 监听用户上拉加载')
    wx.showLoading({
      title: '数据加载中',
    })
    setTimeout(()=>{
      // 用户上拉加载时，需要对数字进行累加，每次累加 3 个数字
      // 获取数组最后一项 n, n + 1, n + 2, n + 3
      const lastNum = this.data.numList[this.data.numList.length -   1]
      const newArr = [lastNum + 1,lastNum + 2,lastNum + 3]
      this.setData({
        numList:[...this.data.numList, ...newArr]
      })
      wx.hideLoading()
    },1500)
  },
  // scroll-view 下拉刷新事件处理函数
  refreshHandler() {
    console.log('监听用户下拉刷新')
    // 当用户上拉加载更多后，如果用户进行了下拉刷新，需要将数据重置
    wx.showToast({
      title: '下拉刷新',
    })
    this.setData({
      numList:[1, 2, 3],
      isTriggered: false
    })
  }

.scss 文件代码示例：

.scroll-y {
  height: 100vh;
  background-color: blanchedalmond;
}
view{
  height: 500rpx;
  display: flex;
  align-items: center;
  justify-content: center;
}
view:nth-child(odd) {
  background-color: skyblue;
}
view:nth-child(even) {
  background-color:pink;
}

.wxml 文件代码示例：

<scroll-view 
 scroll-y 
 class="scroll-y"
 lower-threshold="100"
 bindscrolltolower="getMore"
 enable-back-to-top
 refresher-enabled
 refresher-default-style="black"
 refresher-background="#efefef"
 bindrefresherrefresh="refreshHandler"
 refresher-triggered="{{ isTriggered }}"
>
 <view wx:for="{{ numList }}" wx:key="*this">{{ item }}</view>
</scroll-view>