小程序文档整理之 -- API（界面）

最新推荐文章于 2024-07-10 14:41:33 发布

原创最新推荐文章于 2024-07-10 14:41:33 发布 · 1.1k 阅读

1 ·

CC 4.0 BY-SA版权

文章标签：

#api #小程序

小程序专栏收录该内容

25 篇文章

订阅专栏

本文详细介绍微信小程序中的界面交互方法，包括提示框、加载动画、模态弹窗等组件的使用方式及注意事项。此外还介绍了页面导航、动画效果、下拉刷新等功能的实现。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

界面

交互反馈

wx.showToast(OBJECT)

显示消息提示框

wx.showToast({
  title: '成功',//(必要)提示的内容
  icon: 'success',//图标，有效值 "success", "loading"
  img//自定义图标的本地路径，image 的优先级高于 icon
  duration: 2000//提示的延迟时间，单位毫秒，默认：1500
  mask//是否显示透明蒙层，防止触摸穿透，默认：false
  success/fail/complete: function (res) {//接口调用成功/失败/结束的回调函数
  }
})

wx.hideToast()

隐藏消息提示框

wx.showLoading(OBJECT)

显示 loading 提示框, 需主动调用 wx.hideLoading 才能关闭提示框

wx.showLoading({
  title: '加载中。。。',//(必要)提示的内容
  mask//是否显示透明蒙层，防止触摸穿透，默认：false
  success/fail/complete: function (res) {//接口调用成功/失败/结束的回调函数
  }
})

wx.hideLoading()

隐藏 loading 提示框

wx.showLoading({
  title: '加载中',
})

setTimeout(function(){
  wx.hideLoading()
},2000)

wx.showModal(OBJECT)

显示模态弹窗

wx.showModal({
  title: '提示',//(必要)提示的标题
  content: '这是一个模态弹窗',//(必要)提示的内容
  showCancel:'true'//是否显示取消按钮，默认为 true
  cancelText:'取消'//取消按钮的文字，默认为"取消"，最多 4 个字符
  cancelColor//取消按钮的文字颜色，默认为"#000000"
  confirmText//确定按钮的文字，默认为"确定"，最多 4 个字符
  confirmColor//确定按钮的文字颜色，默认为"#3CC51F"
  success: function(res) {
    res.confirm//为 true 时，表示用户点击了确定按钮
    res.cancel//为 true 时，表示用户点击了取消（用于 Android 系统区分点击蒙层关闭还是点击取消按钮关闭）
  },
  fail/complete: function (res) {//接口调用失败/结束的回调函数
  }
})

wx.showActionSheet(OBJECT)

显示操作菜单

wx.showActionSheet({
  itemList: ['A', 'B', 'C'],//(必要)按钮的文字数组，数组长度最大为6个
  itemColor:'red'//按钮的文字颜色，默认为"#000000"
  success: function(res) {
    res.tapIndex//用户点击的按钮，从上到下的顺序，从0开始
  },
  fail/complete: function (res) {//接口调用失败/结束的回调函数
  }
})

注意：
bug: Android 6.3.30，wx.showModal 的返回的 confirm 一直为 true；
tip: wx.showActionSheet 点击取消或蒙层时，回调 fail, errMsg 为 “showActionSheet:fail cancel”；
tip: wx.showLoading 和 wx.showToast 同时只能显示一个，使用 wx.hideToast/wx.hideLoading 都可以关闭提示框；
tip: iOS wx.showModal 点击蒙层不会关闭模态弹窗，所以尽量避免使用“取消”分支中实现业务逻辑

设置导航条

wx.setNavigationBarTitle(OBJECT)

动态设置当前页面的标题。

wx.setNavigationBarTitle({
  title: '当前页面'//(必要)页面标题
  success/fail/complete: function (res) {//接口调用成功/失败/结束的回调函数
  }
})

wx.showNavigationBarLoading()

在当前页面显示导航条加载动画。

wx.hideNavigationBarLoading()

隐藏导航条加载动画。

wx.setNavigationBarColor(OBJECT)

wx.setNavigationBarColor({
    frontColor: '#ffffff',//(必要)    前景颜色值，包括按钮、标题、状态栏的颜色，仅支持 #ffffff 和 #000000
    backgroundColor: '#ff0000',//(必要)背景颜色值，有效值为十六进制颜色
    animation: {//动画效果
        duration: 400,//动画变化时间，默认0，单位：毫秒
        timingFunc: 'easeIn'//动画变化方式，默认 linear动画从头到尾的速度是相同的,easeIn  动画以低速开始,easeOut 动画以低速结束,easeInOut 动画以低速开始和结束。
    },
    success/fail/complete: function (res) {//接口调用成功/失败/结束的回调函数
        res.errMsg//调用结果
    }
})

设置置顶信息

wx.setTopBarText(OBJECT)

动态设置置顶栏文字内容，只有当前小程序被置顶时能生效，如果当前小程序没有被置顶，也能调用成功，但是不会立即生效，只有在用户将这个小程序置顶后才换上设置的文字内容。注意：调用成功后，需间隔 5s 才能再次调用此接口，如果在 5s 内再次调用此接口，会回调 fail，errMsg：”setTopBarText: fail invoke too frequently”

wx.setTopBarText({
  text: 'hello, world!'//(必要)置顶栏文字内容
  success/fail/complete: function (res) {//接口调用成功/失败/结束的回调函数
  }
})

wx.navigateTo({
  url: 'test?id=1'//(必要)需要跳转的应用内非 tabBar 的页面的路径 , 路径后可以带参数。参数与路径之间使用?分隔，参数键与参数值用=相连，不同参数用&分隔；如 'path?key=value&key2=value2'
  success/fail/complete: function (res) {//接口调用成功/失败/结束的回调函数
  }
})
//test.js
Page({
  onLoad: function(option){
    console.log(option.query)
  }
})

注意：为了不让用户在使用小程序时造成困扰，我们规定页面路径只能是五层，请尽量避免多层级的交互方式。

wx.redirectTo(OBJECT)

关闭当前页面，跳转到应用内的某个页面

wx.redirectTo({
  url: 'test?id=1'//(必要)需要跳转的应用内非 tabBar 的页面的路径 , 路径后可以带参数。参数与路径之间使用?分隔，参数键与参数值用=相连，不同参数用&分隔；如 'path?key=value&key2=value2'
  success/fail/complete: function (res) {//接口调用成功/失败/结束的回调函数
  }
})

wx.reLaunch(OBJECT)

关闭所有页面，打开到应用内的某个页面

wx.reLaunch({
  url: 'test?id=1'//(必要)需要跳转的应用内页面路径 , 路径后可以带参数。参数与路径之间使用?分隔，参数键与参数值用=相连，不同参数用&分隔；如 'path?key=value&key2=value2'，如果跳转的页面路径是 tabBar 页面则不能带参数
  success/fail/complete: function (res) {//接口调用成功/失败/结束的回调函数
  }
})
//test.js
Page({
  onLoad: function(option){
    console.log(option.query)
  }
})

wx.switchTab(OBJECT)

跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面

wx.switchTab({
  url: '/index'//(必要)需要跳转的 tabBar 页面的路径（需在 app.json 的 tabBar 字段定义的页面），路径后不能带参数
})

wx.navigateBack(OBJECT)

关闭当前页面，返回上一页面或多级页面。可通过 getCurrentPages()) 获取当前的页面栈，决定需要返回几层。

// 此处是A页面
wx.navigateTo({
  url: 'B?id=1'
})

// 此处是B页面
wx.navigateTo({
  url: 'C?id=1'
})

// 在C页面内 navigateBack，将返回A页面
wx.navigateBack({
  delta: 2//返回的页面数，如果 delta 大于现有页面数，则返回到首页
})

注意：返回的页面数，如果 delta 大于现有页面数，则返回到首页

动画

wx.createAnimation(OBJECT)
创建一个动画实例animation。调用实例的方法来描述动画。最后通过动画实例的export方法导出动画数据传递给组件的animation属性。

注意: export 方法每次调用后会清掉之前的动画操作

var animation = wx.createAnimation({
  transformOrigin: "50% 50% 0",//设置transform-origin
  duration: 400,//动画持续时间，单位ms
  timingFunction: "linear",//定义动画的效果,ease/ease-in/ease-in-out/ease-out/step-start/step-end
  delay: 0//动画延迟时间，单位 ms
})

animation

动画实例可以调用以下方法来描述动画，调用结束后会返回自身，支持链式调用的写法。

调用动画操作方法后要调用 step() 来表示一组动画完成，可以在一组动画中调用任意多个动画方法，一组动画中的所有动画会同时开始，一组动画完成后才会进行下一组动画。step 可以传入一个跟 wx.createAnimation() 一样的配置参数用于指定当前组动画的配置

<view animation="{{animationData}}"></view>
view{
    opacity//透明度，参数范围 0~1
    background:red;//颜色值
    height/width/top/bootom/left/right//长度值
}
Page({
  data: {
    animationData: {}
  },
  onShow: function(){
    var animation = wx.createAnimation({
      duration: 1000,
      timingFunction: 'ease',
  })

  this.animation = animation

  animation.scale(2,2).rotate(45).step()

  this.setData({
      animationData:animation.export()
  })

  setTimeout(function() {
      animation.translate(30).step()
      this.setData({
        animationData:animation.export()
      })
    }.bind(this), 1000)
  },
  rotateAndScaleThenTranslate: function () {
    // 先旋转同时放大，然后平移
    this.animation.rotate(45).step()
    //rotate(deg)从原点顺时针旋转一个deg角度
    //rotateX(deg)/rotateY(deg)/rotateZ(deg)/rotate3d(x,y,z)
    this.animation.scale(2, 2).step()
    //scale(sx,sy)一个参数时，表示在X轴、Y轴同时缩放sx倍数；两个参数时表示在X轴缩放sx倍数，在Y轴缩放sy倍数
    //scaleX(sx)/scaleY(sy)/scaleZ(sz)/scale3d(sx,sy,sz)
    this.animation.translate(100, 100).step({ duration: 1000 })
    //translate(tx,ty)从原点顺时针旋转一个deg角度
    //translateX(tx)/translateY(ty)/translateZ(tz)/translate3d(tx,ty,tz)
    this.animation.skew(100, 100).step({ duration: 1000 })
    //skew(ax,ay)从原点顺时针旋转一个deg角度
    //skewX(ax)/skewY(ay)
    this.animation.matrix(a,b,c,d,tx,ty).step({ duration: 1000 })
    //matrix3d
    this.setData({
      animationData: this.animation.export()
    })
  }
})

位置

wx.pageScrollTo(OBJECT)

将页面滚动到目标位置

wx.pageScrollTo({
  scrollTop: 0//(必要)滚动到页面的目标位置（单位px）
})

下拉刷新

onPullDownRefresh

在 Page 中定义 onPullDownRefresh 处理函数，监听该页面用户下拉刷新事件。

需要在 config 的window选项中开启 enablePullDownRefresh。
当处理完数据刷新后，wx.stopPullDownRefresh可以停止当前页面的下拉刷新。

wx.startPullDownRefresh(OBJECT)

开始下拉刷新，调用后触发下拉刷新动画，效果与用户手动下拉刷新一致

wx.startPullDownRefresh()

wx.stopPullDownRefresh()

停止当前页面下拉刷新。

wx.stopPullDownRefresh()