微信小程序入门学习教程，从入门到精通，微信小程序常用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/