微信小程序的常用API ①

前言：什么是微信小程序的API？

（1）微信小程序的API是由宿主环境提供的。通俗来说API是一种接口函数，把函数封装起来给开发者使用，这样好多功能都无需开发者去实现，直接调用即可。

（2）通过这些API，开发者可以方便的调用微信提供的能力。如：获取用户信息、本地存储、支付功能等等

（3）小程序还提供了一系列在后端服务器使用HTTPS请求调用的API，帮助开发者在后台完成各类数据分析、管理、查询...操作

一、背景音频 API

（1）背景音频的使用

先在app.json中配置"requiredBackgroundModes": [“audio”]

再通过wx.getBackgroundAudioManage绑定方法

（2）背景音频的属性

1》src 背景音频的数据源，默认为空字符串，当设置了新的src时，会自动开始播放，目前支持的格式有M4A、AAC、MP3、WAV

2》startTime 背景音频开始播放的时间（单位：秒）

3》title 背景音频标题，用于原生音频播放器的背景音频标题

4》playbackRate 播放速率，范围0.5-2.0倍，默认1倍

5》duration 当前背景音频的长度（单位：秒），只有在合法src时有效（只读）

6》currentTime 当前背景音频的播放时间（单位：秒），只有在合法src时有效（只读）

7》paused 当前是否暂停或停止（只读）

（3）背景音频的方法

使用：getBackgroundAudioManage.方法名

1》play（）播放音频

2》pause（）暂停背景音频

3》seek（）跳转到指定位置

4》stop（）停止背景音频

5》onCanplay（）背景音频进入可以播放状态的事件（参数为回调函数）

6》onWaiting（）监听背景音频加载中事件，当背景音频因为数据不足需要停下来加载时会触发

7》onError（）监听背景音频播放错误事件

8》onPlay（）监听背景音频播放事件

9》onPause（）监听背景音频暂停事件

10》onSeeking（）监听背景音频开始跳转操作事件

11》onSeeked（）监听背景音频完成跳转操作事件

12》onEnded（）监听背景音频自然播放结束事件

13》onStop（）监听背景音频停止事件

14》onTimeUpdate（）监听背景音频播放进度更新事件，只有微信小程序在前台时会调用

（4）背景音频代码示例

4-1》先在vscode中配置好一个简单的服务器代码并且启动服务器运行

如图：我的音频文件全放在htdocs中，运行代码为index.js

index.js 运行代码：

var express = require('express');

var app = express();

app.use(express.static('./htdocs'));

app.listen(3000, res => {
  console.log('服务器启动成功，访问地址：http://127.0.0.1:3000/文件名');
});

4-2》在微信开发者工具的index.wxml页面搭建好页面框架

<navigation-bar title="Weixin" back="{{false}}" color="black" background="#FFF"></navigation-bar>
<scroll-view class="scrollarea" scroll-y type="list">
<!-- 一、背景音频 -->
  <button bind:tap="playBackMusic">播放背景音频</button>
</scroll-view>

4-3》在index.js里为其绑定的playBackMusic函数绑定相应的事件

Page({
playBackMusic:function(){
        // 背景音频配置
        var audio=wx.getBackgroundAudioManager();
        // 监听音乐开始播放
        audio.onPlay(function(){
            console.log('开始播放音乐');
        });
        // 设置标题
        audio.title="生日快乐";
        // 设置音源
        audio.src="http://127.0.0.1:3000/1.mp3"
    }
}）

4-4》点击按钮运行结果如下:

背景音频

二、音频 API

（1）音频的使用

音频通过wx.createInnerAudioContext()方法获取到。注意它没有title属性

（2）音频的主要属性

1》src 音频的数据源

2》startTime 音频开始播放的时间（单位：s）

3》autoplay 是否自动播放

4》loop 是否循环播放

5》obeyMuteSwitch 是否遵循系统静音开关。当此参数为 false 时，即使用户打开了微信的静音开关，音频也会继续播放。

6》volume 音量，范围0-1

7》duration 当前音频的长度（单位：s），只读。

8》currentTime 当前音频的播放时间（单位：s），只读。

9》paused 当前是否暂停或停止（只读）

10》buffered 音频已缓冲的时间，只读

11》srcType 设置音频的来源类型。有效值：'inner'（表示使用内置的音频管理器），'network'（表示网络上的音频资源）。

（3）音频的方法

使用：createInnerAudioContext.方法名

（方法和背景音频的方法一样）

1》play（）播放音频

2》pause（）暂停音频

3》stop（）停止音频

4》destroy（）释放音频资源

5》seek(position) 跳转到指定位置播放

6》onCanplay（）背景音频进入可以播放状态的事件（参数为回调函数）

7》onWaiting（）监听背景音频加载中事件，当背景音频因为数据不足需要停下来加载时会触发

8》onError（）监听音频播放错误事件

9》onPlay（）监听音频暂停事件

10》onPause（）监听音频暂停事件

......

（4）注意

1》InnerAudioContext 音频资源不会自动释放，因此如果不再需要使用音频，请及时调用 InnerAudioContext.destroy() 释放资源，避免内存泄漏。

2》音频与背景音频的区别：

* 功能差异：wx.createInnerAudioContext() 更多的是用于对单个音频文件进行更细粒度的控制，而 wx.getBackgroundAudioManager() 则用于管理整个小程序的背景音频播放。

* 背景音频允许后台播放，音频不允许

* 若音频和背景音频同时播放，则播放的是音频

（5）音频代码示例

5-1》先在vscode中配置好一个简单的服务器代码并且启动服务器运行

见背景音频的示例代码

5-2》在微信开发者工具的index.wxml页面搭建好页面框架

<navigation-bar title="Weixin" back="{{false}}" color="black" background="#FFF"></navigation-bar>
<scroll-view class="scrollarea" scroll-y type="list">
<!-- 一、背景音频 -->
  <button bind:tap="playBackMusic">播放背景音频</button>
<!-- 二、音频 -->
  <button bind:tap="playMusic">播放音频</button>
</scroll-view>

5-3》在index.js里为其绑定的playMusic函数绑定相应的事件

page({
// 二、创建音频
    playMusic:function(){
        // 创建音频实例
        var music=wx.createInnerAudioContext()
        // 绑定音源地址
        music.src="http://127.0.0.1:3000/2.mp3";
        // 监听开始播放
        music.onPlay(function(){
            console.log('开始播放音乐');
        });
        // 开始播放
        music.play();
    }
})

5-4》点击按钮运行结果如下:

20240417_215124

三、选择媒体 API

（1）选择媒体的作用

微信小程序的媒体API用于选择图片或视频。一般用于上传头像、上传照片和视频等功能

（2）选择媒体的使用

选择媒体通过wx.chooseMedia（）方法获取到

（3）常用选项

1》count 【number型】最多可以选择的文件个数，默认值为9

2》mediaType 【Array.<string>字符串数组】文件类型，默认值[’image‘，’video‘]

3》sourceType 【Array.<string>字符串数组】图片和视频选择的来源。默认值为 [’album‘，’camera‘],也就是图库，相机

4》maxDuration 【number型】拍摄视频最长拍摄时间，单位秒。时间范围为3-60秒之间。不限制相册，默认值为10

5》camera 【string型】仅在sourceType为camera时生效，可设置使用前置或后置

6》success 【function】接口调用成功的回调函数

7》fail 【function】接口调用失败的回调函数

8》complete 【function】接口调用结束的回调函数（成功、失败都会执行）

四、文件上传 API

（1）文件上传的使用

文件上传通过wx.unploadFile()方法获取到

注意：得先在vscode中配置好一个简单的服务器代码并且启动服务器运行

如图：我的图片文件全放在upfile中，运行代码为index.js

index.js 运行代码：

const express = require('express')
const formidable = require('formidable')
const path = require('path')

var app = express()
app.use(express.static('./htdocs'))

app.post('/upload', function (req, res) {
  var form = formidable({
    keepExtensions: true,
    uploadDir: path.resolve(__dirname, './htdocs/upfile')
  });
  form.parse(req, function (err, fields, files) {
    if (err) {
      console.log('上传失败：' + err)
    } else {
      console.log('上传成功：' + JSON.stringify(files))
    }
    var fileUrl = 'http://127.0.0.1:3000/upfile/';
    for (var i in files) {
      fileUrl += files[i].newFilename;
      break;
    }
    res.json({ success: true, file: fileUrl });
  });
})

app.listen(3000, () => {
  console.log('服务器启动成功 http://127.0.0.1:3000');
})

（2）常用属性

1》url 【string型】必填项。开发者服务器地址（上传接口路径）

2》header 【object型】 http请求的header。header中不能设置referer

3》timeout 【number型】超时时间（单位：毫秒）

4》name 【string型】必填项。文件对应的key，开发者在服务器端可以通过这个key获取文件的二进制内容

5》filePath 【string型】必填项。要上传的文件资源的路径（是指本地路径，可以通过输出res来查看。注意不是上传接口路径）

6》success 【function】接口调用成功的回调函数

7》fail 【function】接口调用失败的回调函数

8》complete 【function】接口调用结束的回调函数（成功、失败都会执行）

五、图片预览 API

（1）图片预览的使用

图片预览体通过wx.previewImage（）方法获取到

（2）常用属性

1》urls 【Array.<string>】需要预览的图片链接列表

2》current 【string】表示当前显示图片的链接，不填则默认为urls的第一张

（3）选择媒体、文件上传、图片预览代码示例

3-1》先在vscode中配置好一个简单的服务器代码并且启动服务器运行

见文件上传API的示例代码

3-2》在微信开发者工具的index.wxml页面搭建好页面框架

<navigation-bar title="Weixin" back="{{false}}" color="black" background="#FFF"></navigation-bar>
<scroll-view class="scrollarea" scroll-y type="list">
<!-- 一、背景音频 -->
  <button bind:tap="playBackMusic">播放背景音频</button>
<!-- 二、音频 -->
  <button bind:tap="playMusic">播放音频</button>
<!-- 三、选择媒体 -->
  <button bind:tap="choose">选择媒体</button>
<!-- 四、文件上传 -->
  <button bind:tap="upload">文件上传</button>
<!-- 五、图片显示与图片点击预览 -->
  <image bind:tap="preview" src="{{img}}" mode=""/> 
</scroll-view>

3-3》在index.js里为其绑定的choose、upload函数绑定相应的事件

Page({
 // 三、媒体API
    choose:function(){
        //chooseMedia 选择媒体
        wx.chooseMedia({
            // 最多可选的文件数量
            count:9,
            // 媒体类型
            mediaType:["image"],
            // 图库
            sourceType:['album','camera'],
            // 成功时的回调
            success:res=>{ //使用箭头函数来处理this指向问题
                //console.log(res); //可自己运行查看数据
                this.setData({
                    // url保存的是本地图片的临时地址
                    url:res.tempFiles[0].tempFilePath,
                })
            }
        })
    },
    //四、 文件上传 API
    upload:function(){
        wx.uploadFile({
        // url保存的是服务器的上传地址
          url:"http://127.0.0.1:3000/upload",
        // filePath是图片的本地路径
          filePath:this.data.url,
          name:'image1',
          success:res=>{
            this.setData({
         // img是图片上传后这个图片的服务器地址
                img:JSON.parse(res.data).file
            })
          }
        })
    },
    // 五、图片预览 API
    preview:function(){
        wx.previewImage({
          urls: [this.data.img],
 //   urls需要预览的图片链接列表
        })
    }
})

3-4》注意：

① 在三、选择媒体API中，我随机选择了一张图片，并且console.log输出res，结果如下。可以见得我选择的本地图片临时地址是保存在tempFiles数组下的tempFilePath属性中。于是我将url进行赋值操作方面进行后续的操作。

② 在四、文件上传API中，我随机选择了一张图片，并且console.log输出res，结果如下。可以见得我选择的本地图片上传后这个图片的服务器地址是保存在data下的file属性中。于是我将img进行赋值操作并且通过JSON.parse()方法来将一个 JSON 格式的字符串转换成 JavaScript 对象，方便进行后续的操作。