小程序文档整理之 -- API（媒体）

最新推荐文章于 2026-02-07 10:34:33 发布

原创最新推荐文章于 2026-02-07 10:34:33 发布 · 4.6k 阅读

0 ·

本内容遵循CC 4.0 BY-SA版权协议

标签

#api #小程序

小程序专栏收录该内容

25 篇文章

订阅专栏

本文详细介绍了小程序中与媒体相关的API，包括图片选择、预览、信息获取与保存，录音操作，音频播放控制，背景音频播放管理，以及视频选择与组件控制等，为开发者提供全面的媒体功能实现指南。

媒体

图片

wx.chooseImage(object)

从本地相册选择图片或使用相机拍照

wx.chooseImage({
  count: 1, // 最多可以选择的图片张数，默认9
  sizeType: ['original', 'compressed'], // 可以指定是原图还是压缩图，original 原图，compressed 压缩图，默认二者都有
  sourceType: ['album', 'camera'], // 可以指定来源是相册还是相机，album 从相册选图，camera 使用相机，默认二者都有
  success: function (res) {// 返回选定照片的本地文件路径列表，tempFilePath可以作为img标签的src属性显示图片
    res={
        tempFilePaths,//图片的本地文件路径列表
        tempFiles:{//图片的本地文件列表，每一项是一个 File 对象
            path//本地文件路径
            size//本地文件大小，单位：B
        }
    }
  },
  fail: function (res){//接口调用失败的回调函数
  },
  complete: function (res){//接口调用结束的回调函数（调用成功、失败都会执行）
  }
})

注：文件的临时路径，在小程序本次启动期间可以正常使用，如需持久保存，需在主动调用 wx.saveFile，在小程序下次启动时才能访问得到。

wx.previewImage(object)

预览图片

wx.previewImage({
  current: '', // 当前显示图片的http链接,默认为 urls 的第一张
  urls: [] // 需要预览的图片http链接列表
  success: function (res) {//接口调用成功的回调函数
  },
  fail: function (res){//接口调用失败的回调函数
  },
  complete: function (res){//接口调用结束的回调函数（调用成功、失败都会执行）
  }
})

wx.getImageInfo(object)

获取图片信息

//从本地相册选择图片或使用相机拍照
wx.chooseImage({
  success: function (res) {
  //获取图片信息
    wx.getImageInfo({
      src: 'images/a.jpg',//图片的路径，可以是相对路径，临时文件路径，存储文件路径，网络图片路径
      success: function (res) {//接口调用成功的回调函数
          res.width;//图片宽度，单位px
          res.height;//图片高度，单位px
          res.path;//返回图片的本地路径
      },
      fail: function (res){//接口调用失败的回调函数
      },
      complete: function (res){//接口调用结束的回调函数（调用成功、失败都会执行）
      }
    })
  }
})

wx.saveImageToPhotosAlbum(object)

保存图片到系统相册。需要用户授权 scope.writePhotosAlbum

wx.saveImageToPhotosAlbum({
    filePath: 'images/a.jpg',//图片文件路径，可以是临时文件路径也可以是永久文件路径，不支持网络图片路径
    success: function (res) {//接口调用成功的回调函数
        res.errMsg;//调用结果
    },
    fail: function (res){//接口调用失败的回调函数
    },
    complete: function (res){//接口调用结束的回调函数（调用成功、失败都会执行）
    }
})

录音

wx.startRecord(object)

开始录音。当主动调用wx.stopRecord，或者录音超过1分钟时自动结束录音，返回录音文件的临时文件路径。当用户离开小程序时，此接口无法调用。

需要用户授权 scope.record

wx.stopRecord( )

主动调用停止录音。

//开始录音
wx.startRecord({
  success: function(res) {//录音成功后调用
    res.tempFilePath //录音文件的临时路径
  },
  fail: function(res) {//录音失败
  },
complete: function (res){//接口调用结束的回调函数（调用成功、失败都会执行）
}
})
setTimeout(function() {
  //结束录音  
  wx.stopRecord()
},

音频播放控制

wx.playVoice(object)

开始播放语音，同时只允许一个语音文件正在播放，如果前一个语音文件还没播放完，将中断前一个语音播放。

wx.pauseVoice( )

暂停正在播放的语音。再次调用wx.playVoice播放同一个文件时，会从暂停处开始播放。如果想从头开始播放，需要先调用 wx.stopVoice。

wx.stopVoice( )

结束播放语音

wx.startRecord({
  success: function(res) {
      var tempFilePath = res.tempFilePath;//录音文件的临时文件路径
    //开始播放语音
      wx.playVoice({
        filePath: tempFilePath,//需要播放的语音文件的文件路径
        success/fail/complete: function (res) {//接口调用成功/失败/结束的回调函数
    }
    })

    setTimeout(function() {
    //暂停播放
      wx.pauseVoice()
    }, 5000)
    setTimeout(function(){
    //结束播放
      wx.stopVoice()
    }, 5000)
  }
})

音乐播放控制

wx.getBackgroundAudioPlayerState(object)

获取后台音乐播放状态

wx.getBackgroundAudioPlayerState({
    success: function (res) {//接口调用成功的回调函数
        var status = res.status;//播放状态（2：没有音乐在播放，1：播放中，0：暂停中）
        var dataUrl = res.dataUrl;//歌曲数据链接，只有在当前有音乐播放时返回
        var currentPosition = res.currentPosition;//选定音频的播放位置（单位：s），只有在当前有音乐播放时返回
        var duration = res.duration;//选定音频的长度（单位：s），只有在当前有音乐播放时返回
        var downloadPercent = res.downloadPercent;//音频的下载进度（整数，80 代表 80%），只有在当前有音乐播放时返回
    },
    fail: function (res){//接口调用失败的回调函数
    },
    complete: function (res){//接口调用结束的回调函数（调用成功、失败都会执行）
    }
})

wx.playBackgroundAudio(object)

使用后台播放器播放音乐，对于微信客户端来说，只能同时有一个后台音乐在播放。当用户离开小程序后，音乐将暂停播放；当用户点击“显示在聊天顶部”时，音乐不会暂停播放；当用户在其他小程序占用了音乐播放器，原有小程序内的音乐将停止播放。

wx.playBackgroundAudio({
    dataUrl: '',//(必要)音乐链接，目前支持的格式有 m4a, aac, mp3, wav
    title: '',//音乐标题
    coverImgUrl: '',//封面URL
    success/fail/complete: function (res) {//接口调用成功/失败/结束的回调函数
    }
})

wx.pauseBackgroundAudio()

暂停播放音乐

wx.pauseBackgroundAudio()

wx.seekBackgroundAudio(object)

控制音乐播放进度

wx.seekBackgroundAudio({
    position: 30,//音乐位置，单位：秒
    success/fail/complete: function (res) {//接口调用成功/失败/结束的回调函数
    }
})

wx.stopBackgroundAudio()

停止播放音乐

wx.stopBackgroundAudio()

wx.onBackgroundAudioPlay(callback)

监听音乐播放

wx.onBackgroundAudioPause(callback)

监听音乐暂停

wx.onBackgroundAudioStop(callback)

监听音乐停止

背景音频播放管理

wx.getBackgroundAudioManager()

获取全局唯一的背景音频管理器 backgroundAudioManager

backgroundAudioManager 对象的属性列表：
const backgroundAudioManager = wx.getBackgroundAudioManager()
const obj = backgroundAudioManager
obj.duration//当前音频的长度（单位：s），只有在当前有合法的 src 时返回
obj.currentTime//当前音频的播放位置（单位：s），只有在当前有合法的 src 时返回
obj.paused//当前是是否暂停或停止状态，true 表示暂停或停止，false 表示正在播放
obj.startTime//音频开始播放的位置（单位：s）
obj.buffered//音频缓冲的时间点，仅保证当前播放时间点到此时间点内容已缓冲
obj.webUrl//页面链接，原生音频播放器中的分享功能，分享出去的卡片简介，也将使用该值。
obj.title = '此时此刻'//音频标题，用于做原生音频播放器音频标题。原生音频播放器中的分享功能，分享出去的卡片标题，也将使用该值。
obj.epname = '此时此刻'//专辑名，原生音频播放器中的分享功能，分享出去的卡片简介，也将使用该值。
obj.singer = '汪峰'//歌手名，原生音频播放器中的分享功能，分享出去的卡片简介，也将使用该值。
obj.coverImgUrl = 'http://y.gtimg.cn/music/T00M03rsKF4Sk.jpg?max_age=2592000'//封面图url，用于做原生音频播放器背景图。原生音频播放器中的分享功能，分享出去的卡片配图及背景也将使用该图。
obj.src = 'http://ws.stream.qqmusic.qq.com/M500001VfvsJ21xFqb.mp3 // 音频的数据源，默认为空字符串，当设置了新的 src 时，会自动开始播放 ，目前支持的格式有 m4a, aac, mp3, wav

backgroundAudioManager 对象的方法列表（暂无）

音频组件控制

wx.createAudioContext(audioId)

创建并返回 audio 上下文 audioContext 对象

<!-- audio.wxml -->
<audio  src="{{src}}" id="myAudio" ></audio>
<button type="primary" bindtap="audioPlay">播放</button>
<button type="primary" bindtap="audioPause">暂停</button>
<button type="primary" bindtap="audio14">设置当前播放时间为14秒</button>
<button type="primary" bindtap="audioStart">回到开头</button>
// audio.js
Page({
  onReady: function (e) {
    // 使用 wx.createAudioContext 创建并返回 audio 上下文 audioContext（audioCtx） 对象
    this.audioCtx = wx.createAudioContext('myAudio')            
    this.audioCtx.setSrc(src)//参数src，音频的地址
    this.audioCtx.play()//播放
  },
  data: {
    src: ''
  },
  audioPlay: function () {
    this.audioCtx.play()
  },
  audioPause: function () {
    this.audioCtx.pause()//暂停
  },
  audio14: function () {
    this.audioCtx.seek(2/position)//参数position，跳转到指定位置，单位 s
  }
})

视频

wx.chooseVideo(object)

拍摄视频或从手机相册中选视频，返回视频的临时文件路径。

<view class="container">
    <video src="{{src}}"></video>
    <button bindtap="bindButtonTap">获取视频</button>
</view>

Page({
    bindButtonTap: function() {
        var that = this
        wx.chooseVideo({
            sourceType: ['album','camera'],//album 从相册选视频，camera 使用相机拍摄，默认为：['album', 'camera']
            maxDuration: 60,//拍摄视频最长拍摄时间，单位秒。最长支持 60 秒
            camera: 'back',//默认调起的为前置还是后置摄像头。front: 前置，back: 后置，默认 back
            success: function(res) {//接口调用成功，返回视频文件的临时文件路径
                that.setData({
                    res.tempFilePath//选定视频的临时文件路径
                    res.duration//选定视频的时间长度
                    res.size//选定视频的数据量大小
                    res.height//返回选定视频的长
                    res.width//返回选定视频的宽
                })
            },
            fail/complete: function (res) {//接口调用失败/结束的回调函数
            }
        })
    }
})

注：文件的临时路径，在小程序本次启动期间可以正常使用，如需持久保存，需在主动调用 wx.saveFile，在小程序下次启动时才能访问得到。

wx.saveVideoToPhotosAlbum(object)

保存视频到系统相册。需要用户授权 scope.writePhotosAlbum

wx.saveVideoToPhotosAlbum({
    filePath,//(必要)视频文件路径，可以是临时文件路径也可以是永久文件路径
    success(res) {
       res.errMsg//调用结果
    },
    fail/complete: function (res) {//接口调用失败/结束的回调函数
    }
})

视频组件控制

wx.createVideoContext(videoId)

创建并返回 video 上下文 videoContext 对象

videoContext
videoContext 通过 videoId 跟一个 video 组件绑定，通过它可以操作一个 video 组件。

<view class="section tc">
  <video id="myVideo" src="http://wxsnsdy.tc.qq.com/105/20210/snsdyvideodownload?filekey=302802010&bizid=1023&hy=SH&fileparam=30201000400"   enable-danmu danmu-btn controls></video>
  <view class="btn-area">
    <input bindblur="bindInputBlur"/>
    <button bindtap="bindSendDanmu">发送弹幕</button>
  </view>
</view>

function getRandomColor () {
  let rgb = []
  for (let i = 0 ; i < 3; ++i){
    let color = Math.floor(Math.random() * 256).toString(16)
    color = color.length == 1 ? '0' + color : color
    rgb.push(color)
  }
  return '#' + rgb.join('')
}

Page({
  onReady: function (res) {
  //创建并返回 video 上下文 videoContext 对象
    this.videoContext = wx.createVideoContext('myVideo')
    this.videoContext.play();//播放
  },
  inputValue: '',
  bindInputBlur: function(e) {
    this.inputValue = e.detail.value
  },
  bindSendDanmu: function () {
    this.videoContext.pause();//暂停
    this.videoContext.seek(position);//跳转到指定位置，单位 s
    this.videoContext.sendDanmu({//发送弹幕，danmu 包含两个属性 text, color。
      text: this.inputValue,
      color: getRandomColor()
    });
    this.videoContext.playbackRate(rate);//设置倍速播放，支持的倍率有 0.5/0.8/1.0/1.25/1.5;
    this.videoContext.requestFullScreen();//进入全屏
    this.videoContext.exitFullScreen();//退出全屏
  }
})