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

知识分享小能手2025-10-04 23:51

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

✅ 一、scroll-view 组件

🔍 知识点说明：

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

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

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

📄 WXML 文件（index.wxml）
xml 复制代码 
<!-- 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）
css 复制代码 
.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）
javascript 复制代码 
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
xml 复制代码 
<view class="volume-control">
  <text>音量：</text>
  <slider 
    min="0" 
    max="100" 
    step="1" 
    value="{{volume}}" 
    show-value="true" 
    bindchange="onVolumeChange" />
</view>
📄 WXSS
css 复制代码 
.volume-control {
  display: flex;
  align-items: center;
  margin: 30rpx;
  padding: 20rpx;
  background-color: #f5f5f5;
  border-radius: 10rpx;
}
📄 JS
javascript 复制代码 
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
xml 复制代码 
<!-- components/play-button.wxml -->
<view class="play-btn" bindtap="togglePlay">
  {{isPlaying ? '暂停' : '播放'}}
</view>
📄 在主页面 index.wxml 中引入
xml 复制代码 
<!-- 引入播放按钮组件 -->
<include src="../components/play-button.wxml" />

<!-- 注意：需要在JS中定义 togglePlay 方法 -->
📄 JS 中定义方法（index.js）
javascript 复制代码 
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
xml 复制代码 
<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
javascript 复制代码 
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
xml 复制代码 
<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
javascript 复制代码 
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
xml 复制代码 
<button bindtap="chooseAvatar">选择头像</button>
<image src="{{avatarUrl}}" mode="aspectFill" class="avatar" wx:if="{{avatarUrl}}" />
📄 JS
javascript 复制代码 
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
xml 复制代码 
<button bindtap="previewAvatar">预览头像</button>
📄 JS
javascript 复制代码 
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
javascript 复制代码 
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
javascript 复制代码 
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
xml 复制代码 
<canvas canvas-id="clockCanvas" style="width: 300px; height: 300px;"></canvas>
📄 JS
javascript 复制代码 
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（简化版）

xml 复制代码 
<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（部分核心逻辑）

javascript 复制代码 
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 自定义图形、时钟、图表

✅ 学习建议：

相关推荐
mustfeng3 分钟前
VCS & Verdi 2023安装
java·服务器·前端
执笔论英雄21 分钟前
【大模型推理】ScheduleBatch 学习
java·spring boot·学习
Mintopia23 分钟前
🌐 数据合规框架下的 WebAIGC 训练数据处理技术规范
前端·javascript·aigc
CRMEB系统商城30 分钟前
【新版发布】标准版PHP v5.6.4正式版，优化部分用户体验
java·大数据·小程序·php·ux
骥龙42 分钟前
2.6、Web漏洞挖掘实战（下）：XSS、文件上传与逻辑漏洞深度解析
前端·xss
用户6600676685391 小时前
从 var 到 let/const：JavaScript 变量声明的进化之路
javascript
用户433845375691 小时前
Promise深度解析，以及简易版的手写实现
前端
十年_H1 小时前
Cesium自定义着色器-片元着色器数据来源
javascript·cesium
梦之云1 小时前
state 状态相关
前端
梦之云1 小时前
effect 副作用相关
前端
热门推荐
01BongoCat - 跨平台键盘猫动画工具02GitHub 镜像站点03UV安装并设置国内源04Linux下V2Ray安装配置指南05jdk21下载、安装（Windows、Linux、macOS）06GitLab 零基础入门指南：从安装到项目管理全流程07NVIDIA显卡驱动、CUDA、cuDNN 和 TensorRT 版本匹配指南08Labelme从安装到标注：零基础完整指南09KGG转MP3工具|非KGM文件|解密音频10在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）