微信小程序开发全攻略·文章版｜05 路由·交互·网络与音乐播放器实战

微信小程序开发全攻略·文章版｜05 路由·交互·网络与音乐播放器实战

微信小程序路由·交互·网络实战：从五种页面跳转到底层音乐播放器，一篇打通数据驱动开发

目录

• 1. 页面路由入门：navigateTo 保留当前页跳转

• 2. redirectTo：替换当前页，不可返回

• 3. reLaunch：清空整个页面栈

• 4. switchTab：跳转到底部 tabBar 页

• 5. 五种路由 API 对比：一张表说清怎么选

• 6. 原生交互一：showToast 轻提示

• 7. 原生交互二：showLoading 加载遮罩

• 8. 原生交互三：showModal 模态确认框

• 9. 原生交互四：showActionSheet 底部菜单

• 10. 动态设置导航栏

• 11. 网络请求 wx.request：发起 HTTPS 请求

• 12. wx.request 常用参数与返回值

• 13. 封装网络请求：Promise + async/await

• 14. 下拉刷新：开启、监听与收起

• 15. 下拉刷新实战：配合分页重置

• 16. 上拉加载：触底加载下一页

• 17. 完整分页列表：下拉刷新 + 上拉加载

• 18. 音乐播放器实战一：搜索音乐

• 19. 音乐播放器实战二：渲染音乐列表

• 20. 音乐播放器实战三：InnerAudioContext 播放

• 21. 常见报错与易错点汇总

• 22. 本模块视频清单

• 23. 常用路由·交互·网络 API 速查表

• 24. 学习打卡清单

• 25. 知识图谱

知识图谱

本模块是一条"从页面跳转 → 用户反馈 → 拉数据 → 分页 → 出成品"的完整链路：

五种路由的选型决策：

你想要的效果

用哪个

分页加载的状态流转：

进入页面 onLoad
└─ fetchList(1) 覆盖式 list = songs

下拉刷新 onPullDownRefresh
└─ fetchList(1) 覆盖式 list = songs → stopPullDownRefresh

触底 onReachBottom
└─ hasMore && !loading ? fetchList(page+1) : 不动
└─ list = list.concat(songs)

到这里，你已经走完了小程序"从前端静态页面"到"真实数据应用"的关键一跃：会跳转、会反馈、会请求、会分页、会播放音频。把这五块串起来，再配上模块六要讲的登录鉴权和本地缓存，你就具备了独立开发一个完整小程序的全部基础能力。建议照着文末打卡清单，把那个音乐播放器从搜索到播放完整跑一遍——亲手跑通一遍，比看十遍笔记都管用。

📊 交互式知识图谱在线版：https://mcnj5s80gkfh.doubaoapps.com/app/app_17fv07wzj0u

摘要：这是《2026 最全微信小程序开发全攻略》的第五篇笔记，对应课程第 42-60 集（约 183 分钟）。前面你已经会写交互、会渲染列表，这一篇把小程序"做一个真实业务页面"所需的四块能力一次性补齐：页面路由（navigateTo / redirectTo / reLaunch / switchTab / navigateBack 五种跳转到底怎么选）、原生交互反馈（showToast / showLoading / showModal / showActionSheet 四种弹窗的区别与用法）、网络请求（wx.request 的完整参数、合法域名前提、以及如何把它封装成 Promise 用 async/await 调用）、分页加载（下拉刷新重置第一页、上拉触底追加下一页的标准实现）。最后用这些能力完成一个简易音乐播放器实战：用 wx.request 搜索音乐、用 wx:for 渲染列表、用 InnerAudioContext 播放音频。学完本文，你应当能独立开发一个带后端数据、能分页、能播放音频的完整业务页面。本文适合：已经掌握事件与渲染、想做出"真能跑数据"的小程序的进阶学习者。

相关延伸阅读

• 李沐《动手学深度学习》191集课程全解析：模块拆解与学习路径

• 吴恩达《面向开发者的提示词工程》精读

• 吴恩达《Model Context Protocol (MCP) 教程》精读（一）

• 多模态大模型教程笔记：ViT·CLIP·SAM·Stable Diffusion

1. 页面路由入门：navigateTo 保留当前页跳转

📝 小程序是多页面应用，页面之间的跳转叫路由。理解路由之前，先理解一个核心数据结构——页面栈。你可以把它想象成一摞盘子：每打开一个新页面，就往盘子堆上再放一个（入栈）；用户点返回，就从最上面拿走一个（出栈）。微信规定这摞盘子最多叠 10 层。

wx.navigateTo 是最常用的跳转方式：它保留当前页、再打开一个新页。跳转后当前页留在栈里，用户点返回或调用 navigateBack 都能回到原页。典型场景就是"列表页 → 详情页"，看完详情能返回列表。

基本用法和传参：

// 保留当前页，跳转到 detail 页；url 后面用 ?key=value 传参
wx.navigateTo({
url: '/pages/detail/detail?id=1001&name=music'
});

目标页在 onLoad 里接收参数：

Page({
onLoad(options) {
console.log(options.id); // "1001"
console.log(options.name); // "music"
}
});

要点

说明

这里补充一个传参的实际限制：url 上拼的 query 参数全都是字符串，而且不能太长。如果你要从列表跳到详情，通常只传一个 id，详情页再拿这个 id 重新请求完整数据——这是最干净的做法。千万别图省事把整个对象 JSON.stringify 后塞进 url，一是 url 长度有限，二是中文要编码、容易出乱码。需要传复杂对象时，用 getApp().globalData 或 wx.setStorageSync 中转，目标页在 onLoad/onShow 里读。

易错点：① 用 navigateTo 跳 tabBar 页会失败，tabBar 页必须用 switchTab；② 页面栈超过 10 层后 navigateTo 不再生效；③ 参数值是中文或特殊字符时要用 encodeURIComponent 编码。

2. redirectTo：替换当前页，不可返回

📝 wx.redirectTo 和 navigateTo 长得很像，但语义完全不同：它关闭当前页、再打开一个新页。因为当前页被关掉了，所以跳转后这一页不出现在返回栈里——用户无法再返回到刚才那一页。

wx.redirectTo({
url: '/pages/home/home' // 关闭当前登录页，打开首页，无法再返回登录页
});
wx.redirectTo({
url: '/pages/home/home' // 关闭当前登录页，打开首页，无法再返回登录页
});

什么场景需要"不能返回"？最典型的是登录后进入首页：用户登录成功，你不希望他点返回又退回到登录页（否则可能重复登录）。再比如"提交表单成功后跳到结果页"，也不希望用户返回重复提交。还有一种常见用法是"引导页"：第一次打开小程序展示几屏引导，看完点"进入"就用 redirectTo/reLaunch 替换掉引导页，防止用户滑回引导。它和 navigateTo 的区别一句话：navigateTo = 新开一页、可返回；redirectTo = 替换当前页、不保留原页。 注意 redirectTo 同样不能跳 tabBar 页。

3. reLaunch：清空整个页面栈

📝 wx.reLaunch 是最"霸道"的跳转：它会关闭所有页面，然后打开应用内任意一个页面——包括 tabBar 页。跳转后页面栈里只剩新页面孤零零一层，用户无论如何都返回不了。

wx.reLaunch({
url: '/pages/login/login' // 清空全部页面栈，回到登录页
});
wx.reLaunch({
url: '/pages/login/login' // 清空全部页面栈，回到登录页
});

它适合"推倒重来"的场景：退出登录回到启动页、强制重置一段流程。比如用户在一个多步表单里点了"取消"，你想让他彻底回到首页、把之前所有中间页都清掉，就用 reLaunch。和 redirectTo 对比一下就清楚了：redirectTo 只换当前这一页，下面还压着别的页；reLaunch 是把整个盘子掀了重摆，栈里只剩新页。正因为它能跳到 tabBar 页，退出登录后回首页这种"既要清栈又要去 tab"的需求，reLaunch 是唯一干净的选择。

4. switchTab：跳转到底部 tabBar 页

📝 wx.switchTab 是一个专门用途的 API：它只能跳转到你在 app.json 的 tabBar 里配置过的那几个底部导航页，并且会关闭其他所有非 tabBar 页面。

wx.switchTab({
url: '/pages/index/index' // 必须是 tabBar 页面
});
wx.switchTab({
url: '/pages/index/index' // 必须是 tabBar 页面
});

这里有一个非常容易踩的坑：switchTab 的 url 不能带 query 参数。也就是说你不能写 wx.switchTab({ url: '/pages/index/index?id=1' })。那要给 tabBar 页传数据怎么办？一般走两条路：一是写到全局的 getApp().globalData 里，二是写到本地缓存 wx.setStorageSync，目标 tabBar 页在 onShow 里去读。

5. 五种路由 API 对比：一张表说清怎么选

📝 到这里五种跳转 API 就齐了。这张对比表是整个模块五最重要的一张表，面试和实战都会反复用到，请务必背下来：

顺带说一下 tabBar 页接收全局数据的时机。因为 switchTab 切过去后，目标 tabBar 页往往早就被微信创建并缓存了，它的 onLoad 可能只在第一次进时执行一次。所以如果你刚往 globalData 写了东西再切 tabBar，目标页读全局数据要放在 onShow 里——这个生命周期每次页面显示都会触发，保证能读到最新值。这个细节在做"登录后跳到 tabBar 首页并显示用户头像昵称"时特别关键。

API

页面栈变化

能否跳 tabBar

典型场景

最后一个 navigateBack 是"往回走"的：

wx.navigateBack({
delta: 1
}); // 返回上一页；delta=2 返回上两页
wx.navigateBack({
delta: 1
}); // 返回上一页；delta=2 返回上两页

用一个"下单流程"的例子把五种路由串起来。用户从首页（tabBar）点商品进详情：用 navigateTo，栈变成 [首页, 详情]，能返回；详情页点"立即购买"进入确认订单：再 navigateTo，栈变成 [首页, 详情, 确认订单]；提交成功后跳到支付结果页，这时不希望用户返回订单页重复提交，用 redirectTo，栈变成 [首页, 详情, 支付结果]；支付结果页点"返回首页"，要把中间这些页都清掉，用 switchTab 切回首页，栈只剩 [首页]。整个过程你会发现：能不能返回、返回后停在哪，完全由你选的那个 API 决定，这就是为什么这张表要背熟。

路由相关的高频报错：① 跳 tabBar 页用错 API（用了 navigateTo/redirectTo）——这是最常见的报错，tabBar 页必须用 switchTab 或 reLaunch；② switchTab 偷偷带了参数，被微信拦下；③ navigateBack 在页面栈只有一页时调用，没有任何效果。

6. 原生交互一：showToast 轻提示

📝 从这一集开始进入"交互反馈"。wx.showToast 弹出一个轻量级提示，几秒钟后自动消失，用于"提交成功""已复制""加载中"这类不需要用户决策的反馈。

wx.showToast({
title: '提交成功', // 最多两行
icon: 'success', // success / error / none / loading
duration: 2000, // 时长 ms，默认 1500
mask: false // 是否显示透明蒙层防止穿透
});
wx.showToast({
title: '提交成功', // 最多两行
icon: 'success', // success / error / none / loading
duration: 2000, // 时长 ms，默认 1500
mask: false // 是否显示透明蒙层防止穿透
});

参数

说明

需要提前关掉时用 wx.hideToast()。关于 mask 参数再多说一句：如果一个 toast 弹出来时你不希望用户还能点到它下面的按钮（比如"提交中，请勿重复点击"），就把 mask 设为 true，加上一层透明蒙层把下层挡住；反之只是提示一句"已复制"，mask 用默认 false 就行，不影响用户继续操作。这个小参数在防止重复提交时很有用。

7. 原生交互二：showLoading 加载遮罩

📝 wx.showLoading 显示带转圈的加载提示。它和 toast 最大的区别是：它不会自动消失，必须你主动调用 wx.hideLoading 关闭。 正因为如此，它非常适合包在网络请求外面。

wx.showLoading({
title: '加载中…',
mask: true
});

wx.request({
url: 'https://example.com/api',
success(res) {
/* 处理数据 */
},
complete() {
wx.hideLoading(); // 无论成功失败都要关闭
}
});
wx.showLoading({
title: '加载中…',
mask: true
});

wx.request({
url: 'https://example.com/api',
success(res) {
/* 处理数据 */
},
complete() {
wx.hideLoading(); // 无论成功失败都要关闭
}
});

易错点：showLoading 和 showToast 的 icon:'loading' 其实是同一套弹窗，二者同时只能显示一个；loading 一定要配对 hideLoading，并且最好放在 complete 里调用，否则请求一报错、页面就永远卡在转圈上。

8. 原生交互三：showModal 模态确认框

📝 wx.showModal 弹出模态对话框，有标题、内容、确定/取消两个按钮，用于需要用户做决策的场景，比如"确认删除吗？""有新版本是否更新？"。

wx.showModal({
title: '提示',
content: '确定要删除这条记录吗？',
confirmText: '删除', // 自定义确定按钮文案，默认"确定"
cancelText: '取消',
confirmColor: '#e64340',
success(res) {
if (res.confirm) {
console.log('用户点了确定');
} else if (res.cancel) {
console.log('用户点了取消');
}
}
});

wx.showModal 的按钮颜色可以用 confirmColor 自定义，做"删除"这类危险操作时把确定按钮设成红色，能从视觉上提醒用户谨慎操作。

三个弹窗怎么区分，一句话记牢：Toast = 自动消失的轻提示（无需决策）；Loading = 手动关闭的加载态；Modal = 需用户点按钮的强提示。 实际开发里还有个小细节：showModal 的按钮颜色可以用 confirmColor 自定义，做"删除"这类危险操作时把确定按钮设成红色，能从视觉上提醒用户谨慎操作；而 cancelColor 一般不用动。需要用户输入内容时（比如给备注改名），还可以用它的 editable: true 让弹窗带一个输入框，省得你再单独做一个页面。

9. 原生交互四：showActionSheet 底部菜单

📝 wx.showActionSheet 从屏幕底部弹起一组选项，适合"分享到哪里""拍照还是从相册选"这种多选一操作。

wx.showActionSheet({
itemList: ['拍照', '从相册选择', '取消收藏'], // 最多 6 项，单项 ≤ 6 汉字
itemColor: '#333333',
success(res) {
// res.tapIndex 为点击项下标（从 0 开始）
if (res.tapIndex === 0) {
console.log('用户选择了拍照');
}
}
});

wx.showActionSheet 从屏幕底部弹起一组选项，适合"分享到哪里""拍照还是从相册选"这种多选一操作。

把四种原生弹窗放在一起做个终极对比，选 UI 时就不会纠结了：Toast 是"我告诉你一声"，用户不用做任何动作，适合反馈结果；Loading 是"我正在干活，你等着"，必须主动结束，适合等接口；Modal 是"我需要你拍板"，有确定取消两个按钮，适合危险操作二次确认；ActionSheet 是"你想选哪一个"，从底部弹一排选项，适合多选一。记住一个原则：能用 Toast 解决的就别上 Modal，因为 Modal 打断用户的程度最强，滥用会让人心烦。

注意 itemList 最多 6 项、每项文字别太长；用户点蒙层取消走 fail 回调，可以据此做取消逻辑。

10. 动态设置导航栏

📝 除了在页面 json 里静态配置导航栏，还能用 API 在运行时动态改。最常用的两个：wx.setNavigationBarTitle 改标题、wx.setNavigationBarColor 改导航栏颜色。

wx.setNavigationBarTitle({
title: '当前播放：七里香' // 进入页面/选中歌曲后动态改标题
});
wx.setNavigationBarTitle({
title: '当前播放：七里香' // 进入页面/选中歌曲后动态改标题
});
wx.setNavigationBarColor({
frontColor: '#ffffff', // 仅支持 #ffffff / #000000
backgroundColor: '#07c160', // 导航栏背景色
animation: {
duration: 300,
timingFunc: 'easeIn'
}
});
wx.setNavigationBarColor({
frontColor: '#ffffff', // 仅支持 #ffffff / #000000
backgroundColor: '#07c160', // 导航栏背景色
animation: {
duration: 300,
timingFunc: 'easeIn'
}
});

动态设置导航栏这件事看着不起眼，但对用户体验的影响很直接：一个列表页顶部写死"列表"，点进某首歌后标题还叫"列表"，用户会分不清自己身在何处。而用 setNavigationBarTitle 动态改成歌名，导航栏立刻就成了当前页面的"身份牌"。再配合 setNavigationBarColor 给播放页换一套主题色，整个播放器的沉浸感就出来了。这两个 API 调用都很轻，一个项目里用不了几次，却能明显提升完成度。

API

作用 / 关键参数

在后面的音乐播放器里，选中一首歌后把导航栏标题改成歌名，就是这个 API 的典型用法。

11. 网络请求 wx.request：发起 HTTPS 请求

📝 前面所有内容都是"前端自己玩"，从这一集开始，小程序要和你的服务器要数据了。wx.request 是小程序发起网络请求的核心 API，默认走 HTTPS，用于从服务器拉取列表、搜索结果等数据。

wx.request({
url: 'https://example.com/search', // 仅 https；需在后台配置合法域名
method: 'GET', // GET / POST / PUT / DELETE 等
data: { keyword: '七里香', page: 1 }, // 请求参数
header: { 'content-type': 'application/json' },
success(res) {
console.log(res.data);
}
});

wx.request({ url: 'https://example.com/search', // 仅 https；需在后台配置合法域名 method: 'GET', // GET / POST / PUT / DELETE 等 data: { keyword: '七里香', page: 1 }, // 请求参数 header: { 'content-type': 'application/json' }, success(res) { console.log(res.statusCode); console.log(res.data); // 服务器返回数据 }, fail(err) { console.error('请求失败', err); } });

但这里有一个正式上线前必须知道的硬门槛：合法域名。正式环境下，request 的 url 域名必须先在小程序后台"开发管理 → 开发设置 → 服务器域名"里配置为 request 合法域名，否则真机上请求会直接失败。开发阶段可以在开发者工具"详情 → 本地设置"里勾选"不校验合法域名"临时绕过——这也是为什么入门篇里那个"真机预览请求失败"的坑要勾这个选项。

关于合法域名，还要再强调一个上线时的流程：你在开发者工具里勾了"不校验合法域名"，只是在你自己电脑上的模拟器/预览里生效，用户手机上的正式版本是不吃这个勾的。所以项目真正要给别人用之前，必须回到小程序管理后台，把你的接口域名、图片域名、音频域名分别填到 request、downloadFile 等合法域名列表里，并且一个月内只能改有限次数。很多人开发时一切正常，一上传体验版让别人扫码就全挂了，十有八九就是忘了配合法域名。

易错点：① 只支持 HTTPS，不支持 HTTP；② 域名必须 ICP 备案并在后台配置，不能直接用 IP；③ 小程序虽然不像浏览器那样有同源限制，但受合法域名白名单约束。

12. wx.request 常用参数与返回值

📝 把 request 的常用配置和返回字段整理成表，照着查即可：

参数 / 字段

说明

GET 和 POST 怎么选？记住一个朴素原则：查数据用 GET，改数据用 POST。GET 的参数拼在 url 后面，会留在浏览器历史和服务器日志里，不适合传密码这类敏感信息；POST 的参数放在请求体里，相对安全，适合提交表单、登录、下单。另外 content-type 要和后端约定好：传 JSON 就用 application/json，传普通表单就用 application/x-www-form-urlencoded，不一致时后端解析 body 会拿到空对象，这又是一个新手常踩却看不出原因的坑。

POST 提交 JSON 数据的写法：

wx.request({
url: 'https://example.com/login',
method: 'POST',
data: { code: 'abc123' },
header: { 'content-type': 'application/json' },
success(res) {
console.log(res.data);
}
});
wx.request({
url: 'https://example.com/login',
method: 'POST',
data: { code: 'abc123' },
header: { 'content-type': 'application/json' },
success(res) {
console.log(res.data.token);
}
});

13. 封装网络请求：Promise + async/await

📝 如果每个请求都手写一遍 success/fail/loading，代码会非常啰嗦，而且 baseURL、token、错误提示散落在各处很难维护。真实项目的标准做法是：把 wx.request 封装成一个返回 Promise 的函数，统一处理 baseURL、loading、错误提示和 token 注入，业务代码里用 async/await 调用。

新建 utils/request.js：

const BASE_URL = 'https://example.com';

function request(options) {
return new Promise((resolve, reject) => {
if (options.loading !== false) {
wx.showLoading({ title: '加载中…', mask: true });
}
wx.request({
url: BASE_URL + options.url,
method: options.method || 'GET',
data: options.data || {},
header: {
'content-type': 'application/json',
token: wx.getStorageSync('token') || ''
},
success(res) {
if (res.statusCode === 200) {
resolve(res.data);
} else {
reject(res);
}
},
fail: reject,
complete() {
if (options.loading !== false) {
wx.hideLoading();
}
}
});
});
}

module.exports = {
get(url, data) {
return request({ url, data, method: 'GET' });
},
post(url, data) {
return request({ url, data, method: 'POST' });
}
};

const BASE_URL = 'https://example.com'; function request(options) { return new Promise((resolve, reject) => { if (options.loading !== false) { wx.showLoading({ title: '加载中', mask: true }); } wx.request({ url: BASE_URL + options.url, method: options.method || 'GET', data: options.data || {}, header: { 'content-type': 'application/json', 'Authorization': wx.getStorageSync('token') || '' }, success(res) { if (res.statusCode === 200) { resolve(res.data); } else { wx.showToast({ title: '请求错误', icon: 'none' }); reject(res); } }, fail(err) { wx.showToast({ title: '网络异常', icon: 'none' }); reject(err); }, complete() { if (options.loading !== false) wx.hideLoading(); } }); }); } module.exports = { get(url, data) { return request({ url, data, method: 'GET' }); }, post(url, data) { return request({ url, data, method: 'POST' }); } };

业务页面里这样调用，扁平又清爽：

const { get } = require('../../utils/request.js');

Page({
data: {
list: []
},
async onLoad() {
const res = await get('/search', { keyword: '七里香', page: 1 });
this.setData({ list: res.songs });
}
});

const { get } = require('../../utils/request.js'); Page({ data: { list: [] }, async onLoad() { const res = await get('/search', { keyword: '七里香', page: 1 }); this.setData({ list: res.result.songs }); } });

为什么非要包一层 Promise？因为原始的 wx.request 用的是 success/fail 回调风格，一旦请求里还要套请求（比如先登录拿 token，再带 token 拉数据），就会写出一层套一层的"回调地狱"。包成 Promise 之后，业务代码可以写成线性的：先 await 拿 token，再 await 拉列表，谁先谁后一目了然。另外把 token 注入、错误提示这些"每个请求都要做一遍"的事收口到封装函数里，以后要改接口地址、要统一加版本号、要统一处理 401 跳登录，都只改 request.js 一个文件，不用全项目搜一遍。

封装的收益总结成五点：统一 baseURL、统一 loading、统一错误提示、统一 token 头、业务代码扁平化为 await。 后面音乐播放器实战会直接复用这个 get 方法。

14. 下拉刷新：开启、监听与收起

📝 网络数据回来了，用户想刷新怎么办？小程序提供了原生的下拉刷新。它需要三步配合：① 在页面 json 开启 enablePullDownRefresh；② 在页面 js 定义 onPullDownRefresh 生命周期函数；③ 刷新完必须调用 wx.stopPullDownRefresh 手动收起刷新动画，否则那个转圈会一直转。

页面 json 开启下拉刷新：

{
"enablePullDownRefresh": true,
"backgroundColor": "#f6f6f6",
"backgroundTextStyle": "dark"
}

{ "enablePullDownRefresh": true, "backgroundColor": "#f6f6f6", "backgroundTextStyle": "dark" }

页面 js 处理下拉刷新：

Page({
data: {
list: []
},
async onPullDownRefresh() {
// 重新请求第一页数据
const res = await get('/songs', { page: 1 });
this.setData({ list: res.songs });
// 数据回来后手动收起刷新动画
wx.stopPullDownRefresh();
}
});

Page({ data: { list: [] }, async onPullDownRefresh() { // 重新请求第一页数据 const res = await get('/songs', { page: 1 }); this.setData({ list: res.songs }); // 数据回来后手动收起刷新动画 wx.stopPullDownRefresh(); } });

有同学会问：我明明配了 enablePullDownRefresh，怎么下拉没反应？按顺序排查三点：第一，这个配置写在页面自己的 json 里，不是 app.json；第二，页面 js 里确实定义了 onPullDownRefresh；第三，数据回来后有没有调 stopPullDownRefresh——如果上一次刷新忘了收起，下一次可能看起来像"卡住不动"。另外，下拉刷新默认只在页面本身滚动时生效，如果你把内容放在了一个 scroll-view 里，页面级下拉刷新是不会触发的，那种情况要用 scroll-view 自己的 refresher 属性。

配置 / API

作用

15. 下拉刷新实战：配合分页重置

📝 下拉刷新通常和分页一起用。这里有个关键逻辑：刷新时要把页码重置回第 1 页、用新数据覆盖旧列表，而不是追加。如果刷新还往后面堆数据，就会和旧数据混在一起，出现重复条目。

Page({
data: {
list: [],
page: 1
},
async loadData(page) {
const res = await get('/songs', { page });
this.setData({ list: res.songs, page });
},
onPullDownRefresh() {
// 下拉刷新：重置回第 1 页，用新数据覆盖旧列表
this.loadData(1).then(() => {
wx.stopPullDownRefresh();
});
}
});
Page({
data: {
list: [],
page: 1
},
async loadData(page) {
const res = await get('/songs', { page });
this.setData({ list: res.songs, page });
},
onPullDownRefresh() {
// 下拉刷新：重置回第 1 页，用新数据覆盖旧列表
this.loadData(1).then(() => {
wx.stopPullDownRefresh();
});
}
});

易错点：刷新后一定要 stopPullDownRefresh；刷新应当覆盖而不是追加列表，否则旧数据残留。

16. 上拉加载：触底加载下一页

📝 一个列表可能有成百上千条，一次全拉下来太慢，于是要做分页：第一屏只加载前 20 条，用户滚动到底部时再加载下一页。上拉加载（触底加载更多）靠页面 js 的 onReachBottom() 生命周期触发；onReachBottomDistance 配置距底部多少像素就提前触发，让加载更跟手。

{
"onReachBottomDistance": 80
}

{ "onReachBottomDistance": 80 }

Page({
data: {
list: [],
page: 1,
hasMore: true
},
async onReachBottom() {
if (!this.data.hasMore) return; // 没有更多就不请求
const nextPage = this.data.page + 1;
const res = await get('/songs', { page: nextPage });
this.setData({
list: this.data.list.concat(res.songs),
page: nextPage,
hasMore: res.songs.length > 0
});
}
});

配置 / 生命周期

作用

17. 完整分页列表：下拉刷新 + 上拉加载

📝 这是把前两集合成的"分页三件套"，也是几乎所有信息流列表（朋友圈、商品流、聊天记录）的标准实现，建议直接背下来：

Page({
data: {
list: [],
page: 1,
pageSize: 20,
hasMore: true,
loading: false
},
async fetchList(page) {
if (this.data.loading) return; // 防重复请求
this.setData({ loading: true });
const res = await get('/songs', { page, pageSize: this.data.pageSize });
this.setData({
list: page === 1 ? res.songs : this.data.list.concat(res.songs),
page,
hasMore: res.songs.length === this.data.pageSize,
loading: false
});
},
async onPullDownRefresh() {
await this.fetchList(1);
wx.stopPullDownRefresh();
},
async onReachBottom() {
if (!this.data.hasMore || this.data.loading) return;
await this.fetchList(this.data.page + 1);
}
});

除了 JS 里的分页逻辑，一个"看起来专业"的列表页还应该在底部给用户明确的状态反馈。通常会在 wxml 里加一行：正在加载下一页时显示"加载中…"，没有更多数据时显示"—— 已经到底啦 ——"。这样用户就不会对着停住的列表疑惑"是不是卡住了"。配合上面的 loading、hasMore 两个标志位，这段底部提示也能做条件渲染。

<view class="load-status">
<text wx:if="{{loading}}">加载中…</text>
<text wx:elif="{{!hasMore && list.length > 0}}">—— 已经到底啦 ——</text>
</view>

分页三件套的三个关键变量：① hasMore 判断还有没有下一页，没有了就别再请求；② loading 防止快速滚动时 onReachBottom 被反复触发造成重复请求；③ 下拉刷新重置 page=1、上拉加载 page+1 并用 concat 追加。这套组合拳，做列表页永远不会错。

18. 音乐播放器实战一：搜索音乐

📝 从这里开始是模块五的收官实战——一个简易音乐播放器。整个项目分三步：搜索音乐 → 渲染音乐列表 → 播放音乐。本集做"搜索框 + 调用接口取回歌曲数据"，正好把前面封装的 get 和 input/confirm 事件用起来。

搜索页结构：

<view class="search-bar">
<input placeholder="输入歌曲名搜索" value="{{keyword}}" bindinput="onKeyword" bindconfirm="doSearch" />
<button bindtap="doSearch">搜索</button>
</view>

搜索逻辑：

const { get } = require('../../utils/request.js');

Page({
data: {
keyword: '',
result: []
},
onKeyword(e) {
this.setData({ keyword: e.detail.value });
},
async doSearch() {
if (!this.data.keyword.trim()) return;
wx.showLoading({ title: '搜索中…', mask: true });
try {
const res = await get('/search', { keyword: this.data.keyword });
this.setData({ result: res.songs });
} finally {
wx.hideLoading();
}
}
});

这里有个体验优化点值得提一下：示例里是点"搜索"按钮或敲回车才发请求（bindconfirm / bindtap），这是最省接口的做法。如果你想做"边打字边出结果"的实时搜索，就不能在 bindinput 里每次都请求——那样用户打三个字会发三个请求。正确做法是加一个防抖：每次 input 先清掉上一个定时器，500 毫秒没新输入才真正发请求，既能实时又不打爆接口。学习阶段先用按钮/回车触发，跑通后再升级成防抖搜索。

注意这里把 loading 放在 finally 里关闭，无论成功失败都会执行，这是最稳的写法。

19. 音乐播放器实战二：渲染音乐列表

📝 搜到歌曲后，用 wx:for 把结果渲染成列表，每项显示封面、歌名、歌手，并在点击时携带歌曲 id。这里把模块四学的列表渲染、条件渲染、事件传参又复习了一遍。

列表渲染的 wxml 结构：

<view wx:if="{{result.length === 0}}" class="empty">
输入歌曲名开始搜索吧
</view>

<view wx:for="{{result}}" wx:key="id" class="song-item"
data-id="{{item.id}}" data-url="{{item.url}}"
bindtap="onPlay">
<image class="song-cover" src="{{item.cover}}" mode="aspectFill" />
<view class="song-info">
<text class="song-name">{{item.name}}</text>
<text class="song-singer">{{item.singer}}</text>
</view>
</view>

点击列表项的处理：

Page({
data: {
result: []
},

onPlay(e) {
const { id } = e.currentTarget.dataset;

// 方式一：把当前歌曲 id 存全局，播放页读取
getApp().globalData.currentSongId = id;
wx.navigateTo({
url: '/pages/player/player'
});

// 方式二：把整首歌信息存全局，播放页直接取用
// const song = this.data.result.find(item => item.id === id);
// getApp().globalData.currentSong = song;
// wx.navigateTo({ url: '/pages/player/player' });
}
});

这里其实藏着一个设计选择：示例里是把歌曲 id 存到 globalData 再跳播放页。为什么不直接把整首歌的信息通过 url 传过去？因为一首歌的信息不止 id——还有歌名、歌手、封面、播放地址，全拼进 url 又长又要编码，很不划算。更合理的做法就是：列表页点中某首歌时，把"整个播放列表"和"当前播到第几首"一起存进 globalData，播放页拿到后既能播当前这首，又能做上一首、下一首的切换。

实战提醒：音乐、图片等资源域名同样要在后台配置为对应合法域名（request / downloadFile）；真实音乐接口可能有鉴权与版权限制，学习时可用自己的测试数据或开放 API。

20. 音乐播放器实战三：InnerAudioContext 播放

📝 终于到了"出声"的一步。小程序用 wx.createInnerAudioContext() 创建一个音频上下文来播放音乐：设置 src（音频地址）、调用 play() / pause() / stop()，并监听 onPlay / onPause / onEnded / onError 等事件来回更新播放按钮的 UI。

let audioCtx = null;

Page({
data: {
playing: false,
songName: ''
},
onLoad(options) {
// 1. 创建音频实例（页面内单例）
audioCtx = wx.createInnerAudioContext();
audioCtx.src = 'https://example.com/audio/qilixiang.mp3';
audioCtx.title = this.data.songName; // 建议设置标题，锁屏可见

// 2. 监听事件
audioCtx.onPlay(() => this.setData({ playing: true }));
audioCtx.onPause(() => this.setData({ playing: false }));
audioCtx.onEnded(() => this.setData({ playing: false }));
audioCtx.onError((err) => {
console.error('播放失败', err);
wx.showToast({ title: '播放失败', icon: 'none' });
});

// 3. 自动播放
audioCtx.play();
},
togglePlay() {
if (this.data.playing) {
audioCtx.pause();
} else {
audioCtx.play();
}
},
onUnload() {
// 4. 离开页面释放资源
if (audioCtx) {
audioCtx.stop();
audioCtx.destroy();
audioCtx = null;
}
}
});

如果你希望锁屏或切到后台也能继续播放、并在系统通知栏显示，就要用全局唯一的 wx.getBackgroundAudioManager()（BackgroundAudioManager），它是 InnerAudioContext 的后台增强版，必须设置 title 和 src：

const bgm = wx.getBackgroundAudioManager();
bgm.title = '七里香'; // 后台播放必填
bgm.singer = '周杰伦';
bgm.coverImgUrl = 'https://example.com/cover.jpg';
bgm.src = 'https://example.com/audio/qilixiang.mp3'; // 设置 src 后自动播放

如果想做进度条，还可以监听 audioCtx.onTimeUpdate，它会在播放过程中周期性回调，带上当前播放位置 currentTime 和总时长 duration，你拿这两个值就能算出播放进度百分比，驱动一个进度条。真实音乐 App 的进度条、拖动进度、上一首下一首，都是在 InnerAudioContext 这层能力上扩展出来的。学习阶段先把播放/暂停/切换歌曲这三个动作跑通，进度条作为进阶练习自己加上去。

音频相关 API 速查：

API / 方法

作用

InnerAudioContext 最容易被忽略的一点是资源释放。它创建出来是一个实实在在的音频播放实例，如果用户点了好几首歌、又退了好几个页面，每次新建一个却不销毁，就会出现"切到别的页面还在出声"或者"多个音频叠在一起播放"的诡异现象。所以务必记住配对：onLoad 里 create、onUnload 里 destroy。这也是为什么示例代码把 audioCtx 声明成页面级变量、并在 onUnload 里 stop() + destroy()——离开播放页就彻底把麦克风"交出去"。

前台播放和后台播放怎么选？一句话：只在用户停留在播放页时才出声、不需要锁屏控制，用 InnerAudioContext 就够轻；一旦你想做"真·音乐 App"那种切后台、锁屏也能继续听、通知栏能切歌的体验，就必须换成 BackgroundAudioManager，并且老老实实把 title、singer、coverImgUrl、src 都配齐——少了 title，后台播放直接不工作。

整个音乐播放器的实战闭环就是：搜索（wx.request）→ 列表（wx:for + data-id）→ 播放（InnerAudioContext/BackgroundAudioManager）。这正是一个真实数据驱动的小程序的最小可用闭环，配合模块六要讲的登录和缓存，可以继续完善成完整产品。

21. 常见报错与易错点汇总

把本模块高频踩坑集中再强调一遍：

22. 本模块视频清单

本模块共 19 集，总时长约 183 分钟，全部为 B 站合集 BV18VTW6TEwE 的分 P：

集

章节标题

时长

链接

注：本批除全局第 1 集外均无视频内嵌字幕与 AI 总结，正文依据集标题与微信官方标准 API 补全（标 📝）；音乐实战所用第三方接口域名需在后台配置 request 合法域名，实际行为以官方文档为准。

23. 常用路由·交互·网络 API 速查表

名称

作用

关键参数 / 备注

24. 学习打卡清单

• 完成第 42 集：路由_navigateTo

• 完成第 43 集：路由_redirectTo

• 完成第 44 集：路由_reLaunch

• 完成第 45 集：路由_switchTab

• 完成第 46 集：交互_消息提示框

• 完成第 47 集：交互_loading提示框

• 完成第 48 集：交互_模态对话框

• 完成第 49 集：交互_操作菜单

• 完成第 50 集：动态设置导航栏

• 完成第 51 集：网络请求

• 完成第 52 集：网络请求_常用参数

• 完成第 53 集：封装网络请求

• 完成第 54 集：下拉刷新

• 完成第 55 集：下拉刷新应用

• 完成第 56 集：上拉加载

• 完成第 57 集：上拉加载应用

• 完成第 58 集：简易音乐播放器_搜索音乐

• 完成第 59 集：简易音乐播放器_音乐列表

• 完成第 60 集：简易音乐播放器_播放音乐

• 能口述五种路由 API 的页面栈差异与各自适用场景

• 已封装一个返回 Promise 的 request 工具并用 async/await 调用

• 已写出"下拉刷新重置 + 上拉加载追加"的完整分页列表

• 已用 InnerAudioContext 跑通搜索 → 列表 → 播放的最小音乐播放器闭环

• 路由层：页面栈（最多 10 层） → navigateTo（保留/可返回） / redirectTo（替换/不可返回） / reLaunch（清空栈） / switchTab（仅 tabBar） / navigateBack（出栈）

• 交互层：showToast（自动消失轻提示） / showLoading（手动关加载态） / showModal（需决策确认框） / showActionSheet（底部多选菜单） / 动态导航栏

• 网络层：wx.request（HTTPS + 合法域名） → 常用参数 url/method/data/header → Promise 封装（统一 baseURL/loading/token/错误） → async/await 业务调用

• 分页层：下拉刷新（enablePullDownRefresh + onPullDownRefresh + stopPullDownRefresh，重置 page=1） → 上拉加载（onReachBottom + onReachBottomDistance，page+1 concat） → hasMore + loading 防重

• 实战闭环：搜索（wx.request） → 列表（wx:for + data-id） → 播放（InnerAudioContext 前台 / BackgroundAudioManager 后台）

到这里，模块五「路由·交互·网络与音乐播放器实战」的全部内容就结束了。你从五种页面跳转（navigateTo / redirectTo / reLaunch / switchTab / navigateBack）一路走到原生交互反馈（showToast / showLoading / showModal / showActionSheet）、网络请求（wx.request + Promise 封装）、分页加载（下拉刷新 + 上拉加载），最后用 InnerAudioContext 跑通了一个「搜索 → 列表 → 播放」的完整音乐播放器闭环。

建议你按文末的打卡清单，把那个音乐播放器从搜索到播放完整跑一遍——亲手跑通一遍，比看十遍笔记都管用。下一模块将进入登录鉴权和本地缓存，届时你就能把这一篇学到的路由、交互、网络、分页能力，组合成一个真正可上线的完整小程序。

一篇学到的路由、交互、网络、分页能力，组合成一个真正可上线的完整小程序。