A professional-grade web step counting library with advanced anti-cheat mechanisms (GPS, Gyroscope, Rhythm Analysis).
npm install web-step-counter-proweb-step-counter 是一个专为移动端 Web 应用设计的高精度、防作弊步数统计组件。
``bash`如果发布到 npm (示例)
npm install web-step-counter
或者直接引入 JS 文件：
`javascript`
import { WebStepCounter } from './step-counter.js';
`javascript步数: ${steps}
const counter = new WebStepCounter({
onStep: (steps) => console.log(),状态: ${msg}
onStatus: (msg, type) => console.log(),
});
// 必须在用户交互（点击事件）中调用
document.getElementById('btn').onclick = () => {
counter.start();
};
`
---
初始化时可传入配置对象：new WebStepCounter(config)
默认参数基于市面上通用步行检测标准优化：
- 正常步行：60-120步/分钟（1-2步/秒），步间隔500-1000ms
- 快走/慢跑：120-180步/分钟（2-3步/秒），步间隔330-500ms
- 慢走场景：支持最慢0.67步/秒的步速
这些参数能够有效支持：
✅ 手机放在口袋里走路（任意姿态，包括平放）
✅ 手机拿在手里走路（竖握/平握/斜握）
✅ 室内/地下等弱GPS信号场景
✅ 快走、慢走、正常步行等多种步速
采用姿态变化检测算法，精准区分正常走路和作弊行为：
| 场景 | 姿态特征 | 判定结果 |
|------|---------|---------|
| 🚶 口袋走路 | 水平放置 + 姿态持续波动 | ✅ 正常计步 |
| 🤚 手持走路 | 任意角度 + 姿态持续波动 | ✅ 正常计步 |
| 🎯 拍桌子作弊 | 水平放置 + 姿态几乎静止 | ❌ 静默过滤 |
核心原理：真实走路时，即使手机水平放置，由于身体晃动也会产生持续的姿态变化；而拍桌子时手机姿态几乎不变。
| 属性 | 类型 | 默认值 | 说明 |
| :--- | :--- | :--- | :--- |
| sensitivity | Number | 12.0 | 加速度灵敏度阈值 (m/s²)。数值越小越灵敏，但也越容易误判。 |minStepInterval
| | Number | 300 | 最小步频间隔 (ms)。对应最快3.3步/秒，覆盖快走和慢跑场景。 |maxStepInterval
| | Number | 1500 | 最大步频间隔 (ms)。对应最慢0.67步/秒，适应慢走场景。 |minConsecutiveSteps
| | Number | 4 | 连续步数门槛。连续走满 N 步才开始计入总数，防止误触。 |cheatCheckInterval
| | Number | 15000 | 防作弊检查周期 (ms)。每隔15秒检查一次 GPS，减少对正常运动的干扰。 |gpsAccuracyLimit
| | Number | 150 | GPS 精度要求 (米)。兼容室内、地下等弱信号场景。 |accelerationThreshold
| | Number | 1.2 | 加速度变化阈值 (m/s²)。匹配正常步行的垂直加速度变化范围。 |maxSpeed
| | Number | 2.8 | 最大允许速度 (m/s)。约 10km/h，超过此速度不计步。 |orientationVarianceThreshold
| | Number | 3.0 | 姿态变化方差阈值。用于区分"拍桌子"和"口袋走路"，方差越小越可能是静止作弊。 |debug
| | Boolean | false | 是否在控制台打印详细调试日志。 |autoPauseOnBackground
| | Boolean | true | Capacitor 环境下切后台时自动暂停传感器以省电。 |onStep
| | Function | null | 步数更新回调 (steps) => void |onStatus
| | Function | null | 状态/作弊回调 (msg, type, code) => void |onSensorData
| | Function | null | 传感器原始数据回调 (acc, orient) => void |
---
表示启动成功，false 表示被拒绝或出错。$3
停止计步，移除所有传感器监听器，停止 GPS 轮询。$3
重置步数、防作弊历史数据和内部缓冲区。$3
手动请求设备方向权限的辅助方法。
* 用于解决 iOS 上某些情况下 Orientation 权限未被正确授予的问题。
* 建议在 UI 上提供一个"修复权限"按钮调用此方法。---
状态与防作弊代码 (Status & Cheating Types)
onStatus(msg, type) 回调会返回当前系统的运行状态或检测到的异常。$3
| 类型 (Type) | 说明 | 示例消息 |
| :--- | :--- | :--- |
|
'success' | 正常运行 | "正在运行", "GPS 验证正常" |
| 'info' | 一般信息 | "已停止", "已重置" |
| 'warning' | 警告/非阻断性问题 | "GPS 信号弱", "需手动授权 Orientation" |
| 'error' | 错误/阻断性问题 | "Motion 权限被拒绝", "必须使用 HTTPS" |
| 'cheating' | 检测到作弊行为 | 见下方作弊类型 |$3
| 消息内容 | 触发原因 | 算法逻辑 |
| :--- | :--- | :--- |
|
"检测到剧烈摇晃" | 陀螺仪检测到高频旋转 | RotationRate > 300 deg/s |
| "检测到机械节奏" | 步频方差极低 (摇步机) | 最近 20 步的时间间隔标准差 < 5ms |
| "检测到原地运动 (GPS)" | 步数增加但 GPS 未移动 | StepsDiff > 15 且 GPSDistance < 3m |
| "速度过快 (xx km/h)" | 移动速度超过阈值 | Speed > 10 km/h (判定为骑车/开车) |
| (静默丢弃) | 拍桌子作弊 | 水平放置 + 姿态方差 < 3.0 (姿态几乎静止) |---
最佳实践
1. HTTPS: 必须在 HTTPS 环境下使用，否则现代浏览器拒绝访问传感器。
2. iOS 权限: 务必设计引导 UI，提示用户在弹窗中点击"允许"。
3. UI 反馈: 当
type === 'cheating' 时，建议在 UI 上显示醒目的红色警告，提示用户"步数可能无效"。
4. 姿态检测: 智能姿态检测算法已内置，无需额外配置。它能自动区分"拍桌子"和"口袋走路"，支持手机在任意姿态下正常计步。
5. 参数调优: 若在特殊场景下出现误判，可适当调整 orientationVarianceThreshold` 参数（默认3.0）：