一、引言
手机里装着一堆传感器:判断朝向的罗盘 、感知晃动和倾斜的加速计 、检测旋转的陀螺仪 。小程序把它们都封装成了成对的 API------启动 → 监听 → 停止,三步就能拿到实时数据。
本文以「案例 5.9 传感器」为主线,做一个能同时演示三类传感器的小程序,并完成作业扩展:在页面底部用 Canvas 画出加速度的实时波形,x /y/z 三个分量各一条曲线,晃动手机波形随之起伏。
二、项目结构
小程序项目根目录
├── app.json 全局配置
├── app.wxss 全局样式
└── pages
└── index
├── index.json
├── index.wxml
├── index.wxss
└── index.js
三、三类传感器的 API 对照
每类传感器都是 "三件套":
表格
| 传感器 | 启动 | 监听 | 停止 |
|---|---|---|---|
| 罗盘(方向) | wx.startCompass |
wx.onCompassChange |
wx.stopCompass |
| 加速计(加速度) | wx.startAccelerometer |
wx.onAccelerometerChange |
wx.stopAccelerometer |
| 陀螺仪(角速度) | wx.startGyroscope |
wx.onGyroscopeChange |
wx.stopGyroscope |
回调数据长什么样
表格
| 传感器 | 回调字段 | 含义 |
|---|---|---|
| 罗盘 | direction |
面对方向,相对正北的角度,0~360 |
| 罗盘 | accuracy |
精度等级:high / medium / low / no / unreliable |
| 加速计 | x / y / z |
三轴加速度,单位 g(1g ≈ 9.8 m/s²)。手机平放静止时 z ≈ -1 或 1 |
| 陀螺仪 | x / y / z |
三轴角速度,单位 rad/s |
采样频率 interval
startAccelerometer / startGyroscope 支持 interval 参数控制回调频率:
表格
| 值 | 间隔 |
|---|---|
'game' |
约 20ms(最快) |
'ui' |
约 60ms |
'normal' |
约 200ms(最省电) |
做波形用
'ui'比较合适;要更细腻就'game',但重绘压力会变大。
四、页面布局
1. 自定义顶部导航栏
<view class="nav-bar" style="padding-top: {{statusBarHeight}}px;">
<text class="nav-title">传感器API</text>
</view>
.nav-bar {
position: fixed;
top: 0; left: 0; right: 0;
height: 88rpx;
background: #ffffff;
display: flex;
align-items: center;
justify-content: center;
box-shadow: 0 2rpx 8rpx rgba(0, 0, 0, 0.08);
z-index: 999;
}
2. 三组按钮 + 三块数值区 + 底部波形
<view class="box">
<view class="title">{{title}}</view>
<view class="btn-layout">
<button type="primary" size="mini" bind:tap="startCompass">启动罗盘监听</button>
<button type="primary" size="mini" bind:tap="stopCompass">停止罗盘监听</button>
</view>
<view class="txt-layout">
<view>罗盘方位角:{{resCompass.direction}}</view>
<view>罗盘精度:{{resCompass.accuracy}}</view>
</view>
<!-- 加速计、陀螺仪两组结构相同,略 -->
<!-- 扩展:加速度实时波形 -->
<view class="title">加速度实时波形</view>
<canvas type="2d" id="wave-canvas" class="wave-canvas" />
<view class="legend">
<text class="legend-x">X轴</text>
<text class="legend-y">Y轴</text>
<text class="legend-z">Z轴</text>
</view>
</view>
.btn-layout {
display: flex;
justify-content: center;
}
.txt-layout {
display: flex;
flex-direction: column;
margin: 10rpx;
padding: 10rpx;
border: 2rpx dashed burlywood;
}
.wave-canvas {
width: 100%;
height: 320rpx;
background-color: #ffffff;
border: 1rpx solid #cccccc;
}
.txt-layout用虚线边框圈出数值区,视觉上把三组传感器数据分块,和作业图一致。
五、罗盘的启动与停止
startCompass() {
wx.startCompass({
success: (res) => {
// 启动成功后再注册监听
wx.onCompassChange((result) => {
this.setData({
resCompass: result,
title: '启动罗盘传感器监听功能'
})
})
},
fail: (err) => {
this.setData({ title: '启动罗盘监听功能失败' })
}
})
},
stopCompass() {
wx.stopCompass({
success: (res) => {
this.setData({ title: '停止罗盘传感器监听功能' })
},
fail: (err) => {
this.setData({ title: '停止罗盘传感器监听功能失败' })
}
})
}
关键顺序 :先
start成功,再在success里on注册监听。这样能保证 "没启动成功就不会收到回调",逻辑更干净。stop之后回调不再触发,数值自然定格。
六、加速计的启动与停止
startAcc() {
wx.startAccelerometer({
interval: 'ui', // 回调频率约 60ms
success: (res) => {
wx.onAccelerometerChange((result) => {
this.setData({
resAcc: result,
title: '启动加速度传感器监听功能'
})
// 扩展:把最新数据推进波形缓冲区
this.pushWave(result)
})
},
fail: (err) => {
this.setData({
resAcc: '',
title: '启动加速度传感器监听功能失败'
})
}
})
},
stopAcc() {
wx.stopAccelerometer({
success: () => {
this.setData({ title: '停止加速度计传感器监听功能' })
},
fail: () => {
this.setData({ title: '停止加速度计传感器监听功能失败' })
}
})
}
相比 PPT 原版,这里多了一行
this.pushWave(result)------ 这就是把数值接到波形绘制上的那一根 "导线"。
七、陀螺仪:结构与加速计完全同构
startGyroscope() {
wx.startGyroscope({
interval: 'ui',
success: (res) => {
wx.onGyroscopeChange((result) => {
this.setData({
resGyroscope: result,
title: '启动陀螺仪传感器监听功能'
})
})
},
fail: (err) => {
this.setData({
resGyroscope: '',
title: '启动陀螺仪监听功能失败'
})
}
})
},
stopGyroscope() {
wx.stopGyroscope({
success: () => {
this.setData({ title: '停止陀螺仪监听功能' })
},
fail: () => {
this.setData({ title: '停止陀螺仪监听功能失败' })
}
})
}
三类传感器代码几乎一样,只是接口名和数据字段不同。掌握一组,另外两组就能照着抄。
八、作业扩展:加速度实时波形
这是本案例最有意思的部分。整体思路分三步:采数据 → 存窗口 → 画曲线。
1. 数据缓冲区
const MAX_POINTS = 120 // 横轴最多保留的数据点
let waveX = []
let waveY = []
let waveZ = []
三条数组分别存 x、y、z 的采样值,长度为固定窗口 120 点。
2. 采集 + 滑动窗口 + 节流
pushWave(result) {
waveX.push(result.x)
waveY.push(result.y)
waveZ.push(result.z)
// 超过最大点数就从头部丢掉最老的数据
if (waveX.length > MAX_POINTS) {
waveX.shift()
waveY.shift()
waveZ.shift()
}
// 绘制节流:约 30ms 重绘一次,避免 60Hz 采样把画布刷爆
const now = Date.now()
if (this.lastDrawTime && now - this.lastDrawTime < 30) {
return
}
this.lastDrawTime = now
this.drawWave()
}
两个要点:
- 滑动窗口 :
push进队尾、shift出队头,长度恒定。新数据不断把旧数据从左侧挤出去,视觉上就是波形在向左滚动 ------ 这是做示波器类界面的标准做法。 - 节流:采样约 60Hz(每 16ms 一个点),如果每个点都重绘一次,CPU 会瞬间打满、界面发卡。限制到 30ms 重绘一次(约 33 帧 / 秒),肉眼足够流畅,性能也安全。
3. 画布初始化
onReady() {
const query = wx.createSelectorQuery()
query.select('#wave-canvas')
.fields({ node: true, size: true })
.exec((res) => {
const canvas = res[0].node
const ctx = canvas.getContext('2d')
const dpr = wx.getWindowInfo().pixelRatio
canvas.width = res[0].width * dpr // 物理像素
canvas.height = res[0].height * dpr
ctx.scale(dpr, dpr) // 适配高清屏
this.waveCanvas = canvas
this.waveCtx = ctx
this.waveWidth = res[0].width // 逻辑像素,绘制时用
this.waveHeight = res[0].height
this.drawWave()
})
}
和 Canvas 绘图案例一样:画布物理尺寸 = 逻辑尺寸 × dpr ,再
ctx.scale(dpr, dpr),这样线条在高清屏上不发虚。
4. 重绘整幅波形
drawWave() {
const ctx = this.waveCtx
if (!ctx) return
const w = this.waveWidth
const h = this.waveHeight
// 清空画布(这一步千万不能漏)
ctx.clearRect(0, 0, w, h)
// 中间基准线(加速度为 0 的位置)
ctx.beginPath()
ctx.strokeStyle = '#f0f0f0'
ctx.lineWidth = 1
ctx.moveTo(0, h / 2)
ctx.lineTo(w, h / 2)
ctx.stroke()
// 三条分量曲线
this.drawLine(waveX, '#e64340')
this.drawLine(waveY, '#09bb07')
this.drawLine(waveZ, '#576b95')
}
最容易踩的坑 :每帧绘制前必须
clearRect。漏了它,上一帧的线留在画布上,新线再叠上去,几秒钟就变成一团墨疙瘩。
5. 画一条曲线
drawLine(data, color) {
const ctx = this.waveCtx
const w = this.waveWidth
const h = this.waveHeight
const n = data.length
if (n < 2) return
ctx.beginPath()
ctx.strokeStyle = color
ctx.lineWidth = 2
for (let i = 0; i < n; i++) {
// 横坐标:按最大点数等分
const x = (w / (MAX_POINTS - 1)) * i
// 纵坐标:0 在中线,值域限制在 -1 ~ 1 避免画出画布
let v = data[i]
if (v > 1) v = 1
if (v < -1) v = -1
const y = h / 2 - v * (h / 2 - 6)
if (i === 0) {
ctx.moveTo(x, y)
} else {
ctx.lineTo(x, y)
}
}
ctx.stroke()
}
坐标映射原理:
y = h/2 - v * (h/2 - 6)
- 加速度
v = 0→y = h/2,落在中线; v = 1(正向最大)→ 接近顶部;v = -1→ 接近底部;- 预留 6px 边距防止线贴边被裁。
因为晃动手机时加速度可能超过 ±1,所以先 clamp 到 ±1,否则线会画到画布外面。
6. 颜色约定
表格
| 分量 | 颜色 | 色值 |
|---|---|---|
| X 轴 | 红 | #e64340 |
| Y 轴 | 绿 | #09bb07 |
| Z 轴 | 蓝 | #576b95 |
页面底部还有一行图例,颜色和曲线一一对应。
7. 离开页面要停监听
onUnload() {
wx.stopCompass({})
wx.stopAccelerometer({})
wx.stopGyroscope({})
}
传感器监听如果不停,用户退出页面后回调还在跑,非常耗电。
onUnload里统一 stop 掉是必须的良好习惯。
九、完整代码清单
app.json
{
"pages": ["pages/index/index"],
"window": {
"navigationBarTextStyle": "black",
"navigationStyle": "custom"
},
"style": "v2",
"sitemapLocation": "sitemap.json"
}
app.wxss
.box {
margin: 20rpx;
padding: 20rpx;
border: 2rpx solid silver;
}
.title {
font-size: 40rpx;
font-weight: bolder;
text-align: center;
margin-bottom: 30rpx;
color: pink;
}
pages/index/index.wxml
<view class="nav-bar" style="padding-top: {{statusBarHeight}}px;">
<text class="nav-title">传感器API</text>
</view>
<scroll-view class="scrollarea" scroll-y type="list">
<view class="page-content">
<view class="box">
<view class="title">{{title}}</view>
<view class="btn-layout">
<button type="primary" size="mini" bind:tap="startCompass">启动罗盘监听</button>
<button type="primary" size="mini" bind:tap="stopCompass">停止罗盘监听</button>
</view>
<view class="txt-layout">
<view>罗盘方位角:{{resCompass.direction}}</view>
<view>罗盘精度:{{resCompass.accuracy}}</view>
</view>
<view class="btn-layout">
<button type="primary" size="mini" bind:tap="startAcc">启动加速度计</button>
<button type="primary" size="mini" bind:tap="stopAcc">停止加速度计</button>
</view>
<view class="txt-layout">
<view>X轴方向加速度:{{resAcc.x}}</view>
<view>Y轴方向加速度:{{resAcc.y}}</view>
<view>Z轴方向加速度:{{resAcc.z}}</view>
</view>
<view class="btn-layout">
<button type="primary" size="mini" bind:tap="startGyroscope">启动陀螺仪</button>
<button type="primary" size="mini" bind:tap="stopGyroscope">停止陀螺仪</button>
</view>
<view class="txt-layout">
<view>X轴的角速度:{{resGyroscope.x}}</view>
<view>Y轴的角速度:{{resGyroscope.y}}</view>
<view>Z轴的角速度:{{resGyroscope.z}}</view>
</view>
<view class="title">加速度实时波形</view>
<canvas type="2d" id="wave-canvas" class="wave-canvas" />
<view class="legend">
<text class="legend-x">X轴</text>
<text class="legend-y">Y轴</text>
<text class="legend-z">Z轴</text>
</view>
</view>
</view>
</scroll-view>
pages/index/index.wxss
page {
height: 100vh;
display: flex;
flex-direction: column;
}
.nav-bar {
position: fixed;
top: 0; left: 0; right: 0;
height: 88rpx;
background: #ffffff;
display: flex;
align-items: center;
justify-content: center;
box-shadow: 0 2rpx 8rpx rgba(0, 0, 0, 0.08);
z-index: 999;
}
.nav-title {
font-size: 34rpx;
color: #000000;
font-weight: 500;
}
.scrollarea {
flex: 1;
overflow-y: hidden;
}
.page-content {
padding-top: 200rpx;
}
.btn-layout {
display: flex;
justify-content: center;
}
button {
margin: 10rpx;
}
.txt-layout {
display: flex;
flex-direction: column;
margin: 10rpx;
padding: 10rpx;
border: 2rpx dashed burlywood;
}
.wave-canvas {
width: 100%;
height: 320rpx;
background-color: #ffffff;
border: 1rpx solid #cccccc;
}
.legend {
display: flex;
justify-content: space-around;
margin: 10rpx;
font-size: 26rpx;
}
.legend-x { color: #e64340; }
.legend-y { color: #09bb07; }
.legend-z { color: #576b95; }
pages/index/index.js
// index.js
// ===== 波形相关参数 =====
const MAX_POINTS = 120
let waveX = []
let waveY = []
let waveZ = []
Page({
data: {
statusBarHeight: 20,
title: '传感器API应用示例'
},
onLoad() {
const info = wx.getWindowInfo()
this.setData({ statusBarHeight: info.statusBarHeight })
},
onReady() {
const query = wx.createSelectorQuery()
query.select('#wave-canvas')
.fields({ node: true, size: true })
.exec((res) => {
const canvas = res[0].node
const ctx = canvas.getContext('2d')
const dpr = wx.getWindowInfo().pixelRatio
canvas.width = res[0].width * dpr
canvas.height = res[0].height * dpr
ctx.scale(dpr, dpr)
this.waveCanvas = canvas
this.waveCtx = ctx
this.waveWidth = res[0].width
this.waveHeight = res[0].height
this.drawWave()
})
},
startCompass() {
wx.startCompass({
success: () => {
wx.onCompassChange((result) => {
this.setData({
resCompass: result,
title: '启动罗盘传感器监听功能'
})
})
},
fail: () => {
this.setData({ title: '启动罗盘监听功能失败' })
}
})
},
stopCompass() {
wx.stopCompass({
success: () => { this.setData({ title: '停止罗盘传感器监听功能' }) },
fail: () => { this.setData({ title: '停止罗盘传感器监听功能失败' }) }
})
},
startAcc() {
wx.startAccelerometer({
interval: 'ui',
success: () => {
wx.onAccelerometerChange((result) => {
this.setData({
resAcc: result,
title: '启动加速度传感器监听功能'
})
this.pushWave(result)
})
},
fail: () => {
this.setData({
resAcc: '',
title: '启动加速度传感器监听功能失败'
})
}
})
},
stopAcc() {
wx.stopAccelerometer({
success: () => { this.setData({ title: '停止加速度计传感器监听功能' }) },
fail: () => { this.setData({ title: '停止加速度计传感器监听功能失败' }) }
})
},
startGyroscope() {
wx.startGyroscope({
interval: 'ui',
success: () => {
wx.onGyroscopeChange((result) => {
this.setData({
resGyroscope: result,
title: '启动陀螺仪传感器监听功能'
})
})
},
fail: () => {
this.setData({
resGyroscope: '',
title: '启动陀螺仪监听功能失败'
})
}
})
},
stopGyroscope() {
wx.stopGyroscope({
success: () => { this.setData({ title: '停止陀螺仪监听功能' }) },
fail: () => { this.setData({ title: '停止陀螺仪监听功能失败' }) }
})
},
pushWave(result) {
waveX.push(result.x)
waveY.push(result.y)
waveZ.push(result.z)
if (waveX.length > MAX_POINTS) {
waveX.shift()
waveY.shift()
waveZ.shift()
}
const now = Date.now()
if (this.lastDrawTime && now - this.lastDrawTime < 30) {
return
}
this.lastDrawTime = now
this.drawWave()
},
drawWave() {
const ctx = this.waveCtx
if (!ctx) return
const w = this.waveWidth
const h = this.waveHeight
ctx.clearRect(0, 0, w, h)
ctx.beginPath()
ctx.strokeStyle = '#f0f0f0'
ctx.lineWidth = 1
ctx.moveTo(0, h / 2)
ctx.lineTo(w, h / 2)
ctx.stroke()
this.drawLine(waveX, '#e64340')
this.drawLine(waveY, '#09bb07')
this.drawLine(waveZ, '#576b95')
},
drawLine(data, color) {
const ctx = this.waveCtx
const w = this.waveWidth
const h = this.waveHeight
const n = data.length
if (n < 2) return
ctx.beginPath()
ctx.strokeStyle = color
ctx.lineWidth = 2
for (let i = 0; i < n; i++) {
const x = (w / (MAX_POINTS - 1)) * i
let v = data[i]
if (v > 1) v = 1
if (v < -1) v = -1
const y = h / 2 - v * (h / 2 - 6)
if (i === 0) {
ctx.moveTo(x, y)
} else {
ctx.lineTo(x, y)
}
}
ctx.stroke()
},
onUnload() {
wx.stopCompass({})
wx.stopAccelerometer({})
wx.stopGyroscope({})
}
})
十、运行与调试要点
- 波形要在「启动加速度计」之后才有 :数据来自
onAccelerometerChange,没启动只有一条空的基准线。 - 模拟器只能手动造数据:开发者工具「传感器 → 加速计」面板可拖数值看波形;真实晃动要用手机微信预览。
- 每帧必须
clearRect:否则线条层层叠加,很快糊成一片。 - 必须做节流 :60Hz 采样直接重绘会卡死,
Date.now()判断 30ms 是最简单的限流方案。 - 加速度要 clamp:晃动时可能超过 ±1,不限幅会画出画布。
interval三档 :'game'/'ui'/'normal',做波形推荐'ui'。- 离页必停监听 :
onUnload里 stop 三类传感器,否则后台持续回调耗电。 - 部分机型无陀螺仪 :
startGyroscope在少数老旧设备会 fail,代码里要有fail兜底。
十一、总结
通过案例 5.9传感器,我掌握了:
- 三类传感器统一的「启动 / 监听 / 停止」三件套模式和各自的数据字段
interval采样频率的意义与取舍- 加速度波形的完整实现链路:滑动窗口缓冲 → 节流 → Canvas 坐标映射 → 三条曲线
onUnload停止监听的良好习惯