微信小程序入门学习教程，从入门到精通，微信小程序常用API（上）——知识点详解 + 案例实战(4）

📚 微信小程序常用API（上）——知识点详解 + 案例实战

---

✅ 一、scroll-view 组件

🔍 知识点说明：

<scroll-view> 是微信小程序中用于实现滚动区域的组件，支持横向和纵向滚动，常用于列表、轮播图、长页面等场景。关键属性包括：

• scroll-y：是否允许纵向滚动
• scroll-x：是否允许横向滚动
• scroll-top / scroll-left：设置滚动位置
• bindscroll：滚动事件监听
• enable-back-to-top：开启返回顶部功能

---

💡 案例：实现一个纵向滚动的音乐歌单列表

📄 WXML 文件（index.wxml）

<!-- scroll-view 纵向滚动示例 -->
<scroll-view scroll-y="true" class="song-list" bindscroll="onScroll"enable-back-to-top="true"><view wx:for="{{songs}}" wx:key="id" class="song-item">{{item.name}} - {{item.artist}}</view>
</scroll-view>

📄 WXSS 文件（index.wxss）

.song-list {height: 300rpx;border: 1px solid #ccc;padding: 20rpx;overflow-y: auto;
}.song-item {padding: 20rpx;border-bottom: 1px solid #eee;font-size: 32rpx;
}

📄 JS 文件（index.js）

Page({data: {songs: [{ id: 1, name: '晴天', artist: '周杰伦' },{ id: 2, name: '七里香', artist: '周杰伦' },{ id: 3, name: '夜曲', artist: '周杰伦' },{ id: 4, name: '告白气球', artist: '周杰伦' },{ id: 5, name: '稻香', artist: '周杰伦' },{ id: 6, name: '双截棍', artist: '周杰伦' },{ id: 7, name: '简单爱', artist: '周杰伦' },{ id: 8, name: '以父之名', artist: '周杰伦' }]},// 滚动监听onScroll(e) {console.log('当前滚动位置:', e.detail.scrollTop);if (e.detail.scrollTop > 100) {wx.showToast({title: '已滚动超过100px',icon: 'none'});}}
});

✅ 提示：scroll-view 必须设置固定高度才能生效！

---

✅ 二、slider 组件

🔍 知识点说明：

<slider> 是滑块组件，常用于音量控制、进度调节等。主要属性：

• min / max：最小/最大值
• step：步长
• value：当前值
• show-value：是否显示当前值
• bindchange：值改变时触发

---

💡 案例：音乐播放器音量调节滑块

📄 WXML

<view class="volume-control"><text>音量：</text><slider min="0" max="100" step="1" value="{{volume}}" show-value="true" bindchange="onVolumeChange" />
</view>

📄 WXSS

.volume-control {display: flex;align-items: center;margin: 30rpx;padding: 20rpx;background-color: #f5f5f5;border-radius: 10rpx;
}

📄 JS

Page({data: {volume: 50 // 初始音量50%},// 音量改变事件onVolumeChange(e) {const newVolume = e.detail.value;this.setData({ volume: newVolume });console.log('当前音量：', newVolume);// 实际项目中可调用背景音频API设置音量// wx.getBackgroundAudioManager().volume = newVolume / 100;}
});

✅ 注意：滑块值是整数，如需小数可自行处理（如乘除）

---

✅ 三、 标签

🔍 知识点说明：

<include> 用于在当前页面引入其他 WXML 文件片段，实现代码复用。不能传递数据，但可通过 data 或全局变量共享。

---

💡 案例：复用“播放控制按钮”组件

📄 创建公共组件文件：components/play-button.wxml

<!-- components/play-button.wxml -->
<view class="play-btn" bindtap="togglePlay">{{isPlaying ? '暂停' : '播放'}}
</view>

📄 在主页面 index.wxml 中引入

<!-- 引入播放按钮组件 -->
<include src="../components/play-button.wxml" /><!-- 注意：需要在JS中定义 togglePlay 方法 -->

📄 JS 中定义方法（index.js）

Page({data: {isPlaying: false},togglePlay() {this.setData({isPlaying: !this.data.isPlaying});console.log(this.data.isPlaying ? '开始播放' : '暂停播放');}
});

⚠️ 注意：<include> 只能引入静态结构，动态数据需通过 Page 数据或自定义组件实现。

---

✅ 四、背景音频 API（wx.getBackgroundAudioManager）

🔍 知识点说明：

用于播放后台音频（即使切换页面也能继续播放），适用于音乐播放器。关键方法：

• src：设置音频源
• title：标题（iOS锁屏显示）
• epname：专辑名
• singer：歌手
• coverImgUrl：封面图
• play() / pause() / stop()
• onTimeUpdate()：时间更新事件
• onEnded()：播放结束事件

---

💡 案例：实现音乐播放器核心功能

📄 WXML

<view class="player"><text>当前播放：{{currentSong.name}}</text><button bindtap="playMusic">播放</button><button bindtap="pauseMusic">暂停</button><button bindtap="stopMusic">停止</button><slider min="0" max="{{duration}}" value="{{currentTime}}" bindchange="seekTo" show-value="true" />
</view>

📄 JS

Page({data: {currentSong: {name: '晴天',url: 'https://example.com/qingtian.mp3',singer: '周杰伦',cover: 'https://example.com/cover.jpg'},currentTime: 0,duration: 0},onLoad() {this.audioManager = wx.getBackgroundAudioManager();this.initAudio();},initAudio() {const { url, name, singer, cover } = this.data.currentSong;this.audioManager.src = url;this.audioManager.title = name;this.audioManager.singer = singer;this.audioManager.coverImgUrl = cover;// 监听播放进度this.audioManager.onTimeUpdate(() => {this.setData({currentTime: Math.floor(this.audioManager.currentTime),duration: Math.floor(this.audioManager.duration)});});// 监听播放结束this.audioManager.onEnded(() => {wx.showToast({ title: '播放结束', icon: 'success' });});},playMusic() {this.audioManager.play();},pauseMusic() {this.audioManager.pause();},stopMusic() {this.audioManager.stop();},seekTo(e) {const time = e.detail.value;this.audioManager.seek(time);}
});

✅ 重要：背景音频必须在用户交互后（如点击按钮）才能播放，否则会被静音。

---

✅ 五、录音 API（wx.startRecord / wx.stopRecord）

🔍 知识点说明：

用于录制音频，生成临时文件路径。常用于语音留言、语音搜索等。

• wx.startRecord() 开始录音
• wx.stopRecord() 停止录音
• success 回调返回临时文件路径
• 可配合 wx.playVoice() 播放录音

---

💡 案例：简易录音机

📄 WXML

<view class="recorder"><button bindtap="startRecord">开始录音</button><button bindtap="stopRecord">停止录音</button><button bindtap="playRecord" disabled="{{!recordPath}}">播放录音</button><text wx:if="{{recordPath}}">录音文件：{{recordPath}}</text>
</view>

📄 JS

Page({data: {recordPath: ''},startRecord() {wx.startRecord({success: (res) => {this.setData({ recordPath: res.tempFilePath });wx.showToast({ title: '录音开始', icon: 'loading' });},fail: (err) => {wx.showToast({ title: '录音失败', icon: 'none' });console.error(err);}});},stopRecord() {wx.stopRecord();wx.showToast({ title: '录音结束', icon: 'success' });},playRecord() {if (!this.data.recordPath) return;wx.playVoice({filePath: this.data.recordPath,complete: () => {wx.showToast({ title: '播放完毕', icon: 'none' });}});}
});

✅ 注意：录音权限需在 app.json 中声明 "scope.record"，且首次使用需用户授权。

---

✅ 六、选择媒体 API（wx.chooseImage / wx.chooseVideo）

🔍 知识点说明：

从相册或相机选择图片/视频，返回临时文件路径。

• count：最多选择数量
• sizeType：压缩/原图
• sourceType：来源（相册/相机）
• success：回调包含 tempFilePaths

---

💡 案例：头像上传 —— 选择图片

📄 WXML

<button bindtap="chooseAvatar">选择头像</button>
<image src="{{avatarUrl}}" mode="aspectFill" class="avatar" wx:if="{{avatarUrl}}" />

📄 JS

Page({data: {avatarUrl: ''},chooseAvatar() {wx.chooseImage({count: 1, // 最多选1张sizeType: ['original', 'compressed'], // 原图/压缩图sourceType: ['album', 'camera'], // 相册/相机success: (res) => {const tempFilePath = res.tempFilePaths[0];this.setData({ avatarUrl: tempFilePath });console.log('选择图片路径：', tempFilePath);}});}
});

---

✅ 七、图片预览 API（wx.previewImage）

🔍 知识点说明：

预览图片，支持多图切换、放大缩小。

• current：当前显示的图片索引或URL
• urls：所有图片URL数组

---

💡 案例：预览头像

📄 WXML

<button bindtap="previewAvatar">预览头像</button>

📄 JS

Page({data: {avatarUrl: 'https://example.com/avatar.jpg'},previewAvatar() {wx.previewImage({current: this.data.avatarUrl, // 当前显示图片urls: [this.data.avatarUrl]   // 所有可预览图片});}
});

✅ 可扩展为预览多张图片，如相册浏览功能。

---

✅ 八、文件上传 API（wx.uploadFile）

🔍 知识点说明：

将本地文件上传到服务器，常用于上传头像、录音、视频等。

• url：上传地址
• filePath：本地文件路径
• name：服务器接收字段名
• success：上传成功回调
• fail：失败回调

---

💡 案例：上传头像到服务器

📄 JS

Page({data: {avatarUrl: ''},uploadAvatar() {if (!this.data.avatarUrl) {wx.showToast({ title: '请先选择头像', icon: 'none' });return;}wx.uploadFile({url: 'https://your-server.com/upload-avatar', // 替换为你自己的接口filePath: this.data.avatarUrl,name: 'avatar', // 后端接收字段名success: (res) => {const data = JSON.parse(res.data);wx.showToast({ title: '上传成功', icon: 'success' });console.log('服务器返回：', data);},fail: (err) => {wx.showToast({ title: '上传失败', icon: 'none' });console.error(err);}});}
});

✅ 注意：服务器需支持 CORS 和文件接收逻辑。

---

✅ 九、文件下载 API（wx.downloadFile）

🔍 知识点说明：

从网络下载文件到本地，返回临时路径，可用于播放、展示等。

• url：下载地址
• success：下载成功回调，含 tempFilePath
• fail：失败回调

---

💡 案例：下载头像并预览

📄 JS

Page({downloadAndPreviewAvatar() {wx.downloadFile({url: 'https://example.com/avatar.jpg',success: (res) => {if (res.statusCode === 200) {const tempFilePath = res.tempFilePath;this.setData({ avatarUrl: tempFilePath });wx.previewImage({current: tempFilePath,urls: [tempFilePath]});}},fail: (err) => {wx.showToast({ title: '下载失败', icon: 'none' });console.error(err);}});}
});

---

✅ 十、canvas 组件 + 画布 API

🔍 知识点说明：

用于绘制图形、动画、图表等。核心对象：

• wx.createCanvasContext(canvasId) 获取上下文
• ctx.moveTo(x,y) / ctx.lineTo(x,y) 绘制线条
• ctx.stroke() / ctx.fill() 渲染
• ctx.rotate(angle) 旋转
• ctx.save() / ctx.restore() 保存/恢复状态

---

💡 案例：模拟时钟

📄 WXML

<canvas canvas-id="clockCanvas" style="width: 300px; height: 300px;"></canvas>

📄 JS

Page({onReady() {this.drawClock();setInterval(() => this.drawClock(), 1000); // 每秒刷新},drawClock() {const ctx = wx.createCanvasContext('clockCanvas');// 清空画布ctx.clearRect(0, 0, 300, 300);// 设置中心点const centerX = 150, centerY = 150;const radius = 100;// 绘制表盘ctx.beginPath();ctx.arc(centerX, centerY, radius, 0, 2 * Math.PI);ctx.stroke();// 获取当前时间const now = new Date();const hours = now.getHours() % 12;const minutes = now.getMinutes();const seconds = now.getSeconds();// 绘制时针this.drawHand(ctx, centerX, centerY, radius * 0.5, hours * 30 + minutes * 0.5, '#000', 8);// 绘制分针this.drawHand(ctx, centerX, centerY, radius * 0.7, minutes * 6, '#666', 4);// 绘制秒针this.drawHand(ctx, centerX, centerY, radius * 0.8, seconds * 6, '#f00', 2);// 绘制刻度for (let i = 0; i < 12; i++) {ctx.beginPath();ctx.moveTo(centerX + radius * 0.9 * Math.cos(i * 30 * Math.PI / 180), centerY + radius * 0.9 * Math.sin(i * 30 * Math.PI / 180));ctx.lineTo(centerX + radius * 0.8 * Math.cos(i * 30 * Math.PI / 180), centerY + radius * 0.8 * Math.sin(i * 30 * Math.PI / 180));ctx.stroke();}ctx.draw();},drawHand(ctx, x, y, length, angle, color, width) {ctx.beginPath();ctx.moveTo(x, y);ctx.strokeStyle = color;ctx.lineWidth = width;ctx.lineTo(x + length * Math.cos((angle - 90) * Math.PI / 180),y + length * Math.sin((angle - 90) * Math.PI / 180));ctx.stroke();}
});

✅ 提示：角度转换需注意：顺时针为正，0°指向右侧，需减90°转为标准数学坐标系。

---

🧩 综合性案例：多功能音乐播放器（整合以上多个API）

功能需求：

• 支持播放/暂停/停止
• 显示歌曲信息 & 进度条
• 音量调节滑块
• 选择本地歌曲（文件选择）
• 录音功能（可录一段语音并播放）
• 头像上传预览（装饰界面）

---

📄 WXML（简化版）

<view class="music-player"><!-- 歌曲信息 --><text>正在播放：{{currentSong.name || '无歌曲'}}</text><!-- 控制按钮 --><button bindtap="playMusic">▶️ 播放</button><button bindtap="pauseMusic">⏸️ 暂停</button><button bindtap="stopMusic">⏹️ 停止</button><!-- 进度条 --><slider min="0" max="{{duration}}" value="{{currentTime}}" bindchange="seekTo" show-value="true" /><!-- 音量调节 --><slider min="0" max="100" value="{{volume}}" bindchange="setVolume" show-value="true" /><!-- 选择歌曲 --><button bindtap="chooseSong">📁 选择歌曲</button><!-- 录音功能 --><button bindtap="startRecord">🎤 开始录音</button><button bindtap="stopRecord">⏹️ 停止录音</button><button bindtap="playRecord" disabled="{{!recordPath}}">🔊 播放录音</button><!-- 头像上传 --><button bindtap="chooseAvatar">🖼️ 上传头像</button><image src="{{avatarUrl}}" mode="aspectFit" class="avatar-preview" wx:if="{{avatarUrl}}" /></view>

📄 JS（部分核心逻辑）

Page({data: {currentSong: {},currentTime: 0,duration: 0,volume: 50,recordPath: '',avatarUrl: ''},audioManager: null,onLoad() {this.audioManager = wx.getBackgroundAudioManager();this.audioManager.onTimeUpdate(() => {this.setData({currentTime: Math.floor(this.audioManager.currentTime),duration: Math.floor(this.audioManager.duration)});});},// 播放音乐playMusic() {if (!this.data.currentSong.url) return;this.audioManager.src = this.data.currentSong.url;this.audioManager.title = this.data.currentSong.name;this.audioManager.play();},// 设置音量setVolume(e) {const vol = e.detail.value / 100;this.audioManager.volume = vol;this.setData({ volume: e.detail.value });},// 选择歌曲chooseSong() {wx.chooseMedia({count: 1,mediaType: ['audio'],success: (res) => {const file = res.tempFiles[0];this.setData({currentSong: {name: file.name,url: file.tempFilePath}});this.playMusic();}});},// 录音相关（同上）startRecord() { /* 同前 */ },stopRecord() { /* 同前 */ },playRecord() { /* 同前 */ },// 上传头像chooseAvatar() {wx.chooseImage({count: 1,success: (res) => {this.setData({ avatarUrl: res.tempFilePaths[0] });}});}
});

✅ 进阶建议：

• 使用 wx.setStorage 保存最近播放记录
• 添加歌词同步功能（结合 onTimeUpdate）
• 使用 wx.createInnerAudioContext() 实现多音频管理

---

📘 本章小结

API 类别	核心组件/API	主要用途
滚动容器	<scroll-view>	长列表、内容滚动
滑块控件	<slider>	音量、进度调节
代码复用	<include>	引入公共WXML片段
背景音频	wx.getBackgroundAudioManager	音乐播放器
录音	wx.startRecord	语音录制
图片选择	wx.chooseImage	上传头像、图片
图片预览	wx.previewImage	查看大图
文件上传	wx.uploadFile	上传至服务器
文件下载	wx.downloadFile	下载资源
画布绘图	canvas + ctx	自定义图形、时钟、图表

---

✅ 学习建议：

• 每个API独立练习 → 再组合成完整项目
• 使用真机调试，注意权限申请（录音、摄像头等）
• 结合官方文档：https://developers.weixin.qq.com/miniprogram/dev/api/