更新记录

1.0.0（2025-07-08） 下载此版本

H5 陀螺仪插件 - 为 uni-app 提供 H5 平台的陀螺仪功能支持

平台兼容性

uni-app

其他

jz-h5-gyroscope

H5 陀螺仪插件 - 为 uni-app 提供 H5 平台的陀螺仪功能支持

📋 插件简介

uni-app 官方的陀螺仪 API 在 H5 平台不支持，本插件通过浏览器的 DeviceOrientationEvent API 实现了与官方 API 相同的接口，让您可以在 H5 环境中使用陀螺仪功能。

平台差异对比

🚀 快速开始

1. 安装使用

// 导入插件
import jzH5Gyroscope from '@/uni_modules/jz-h5-gyroscope/index.js'

2. 基本使用

export default {
  data() {
    return {
      gyroscopeData: { x: 0, y: 0, z: 0 }
    }
  },

  onLoad() {
    // 监听陀螺仪数据变化
    jzH5Gyroscope.onGyroscopeChange((data) => {
      this.gyroscopeData = data;
      console.log('陀螺仪数据:', data);
    });
  },

  methods: {
    startGyroscope() {
      jzH5Gyroscope.startGyroscope({
        interval: 200,
        success: (res) => {
          console.log('开始监听成功', res);
        },
        fail: (error) => {
          console.error('开始监听失败', error);
        }
      });
    },

    stopGyroscope() {
      jzH5Gyroscope.stopGyroscope({
        success: (res) => {
          console.log('停止监听成功', res);
        }
      });
    }
  },

  onUnload() {
    // 清理资源
    jzH5Gyroscope.stopGyroscope();
    jzH5Gyroscope.offGyroscopeChange();
  }
}

📖 API 文档

jzH5Gyroscope.startGyroscope(options)

开始监听陀螺仪数据。

参数说明

interval 参数对应关系

根据 uni-app 官方文档，微信小程序支持的 interval 参数：

• "game"：20ms/次（对应本插件：20）
• "ui"：60ms/次（对应本插件：60）
• "normal"：200ms/次（对应本插件：200）

示例

jzH5Gyroscope.startGyroscope({
  interval: 200,
  success(res) {
    console.log('开始监听陀螺仪成功', res);
  },
  fail(error) {
    console.log('开始监听陀螺仪失败', error);
  }
});

jzH5Gyroscope.stopGyroscope(options)

停止监听陀螺仪数据。

参数说明

示例

jzH5Gyroscope.stopGyroscope({
  success(res) {
    console.log('停止监听陀螺仪成功', res);
  }
});

jzH5Gyroscope.onGyroscopeChange(callback)

监听陀螺仪数据变化事件。

callback 参数说明

res 的结构

示例

jzH5Gyroscope.onGyroscopeChange((data) => {
  console.log('X轴（俯仰）:', data.x);
  console.log('Y轴（横滚）:', data.y);
  console.log('Z轴（偏航）:', data.z);
});

jzH5Gyroscope.offGyroscopeChange(callback)

取消监听陀螺仪数据变化事件。

参数说明

示例

// 取消指定回调
jzH5Gyroscope.offGyroscopeChange(myCallback);

// 取消所有回调
jzH5Gyroscope.offGyroscopeChange();

jzH5Gyroscope.getGyroscopeStatus()

获取当前陀螺仪状态（扩展方法）。

返回值

示例

const status = jzH5Gyroscope.getGyroscopeStatus();
console.log('监听状态:', status.isListening);
console.log('监听间隔:', status.interval);
console.log('最后数据:', status.lastData);

🎯 数据说明

坐标系说明

• X轴（俯仰角 Beta）: 设备绕 X 轴旋转的角度，当设备向前倾斜时为正值
• Y轴（横滚角 Gamma）: 设备绕 Y 轴旋转的角度，当设备向左倾斜时为正值
• Z轴（偏航角 Alpha）: 设备绕 Z 轴旋转的角度，表示设备水平面的方向

数据范围

• X轴: -180° ~ 180°
• Y轴: -90° ~ 90°
• Z轴: 0° ~ 360°

⚠️ 注意事项

1. 环境要求

• HTTPS: 现代浏览器要求在 HTTPS 环境下才能访问设备传感器
• 设备支持: 设备必须具有陀螺仪传感器
• 浏览器支持: 支持 DeviceOrientationEvent 的现代浏览器

2. 权限处理

• iOS 13+: 需要用户主动授权访问陀螺仪
• Android: 通常无需额外权限
• 桌面浏览器: 部分浏览器可能不支持

3. 最佳实践

// 1. 在页面 onLoad 中设置监听
onLoad() {
  this.setupGyroscopeListener();
},

// 2. 在页面 onUnload 中清理资源
onUnload() {
  jzH5Gyroscope.stopGyroscope();
  jzH5Gyroscope.offGyroscopeChange();
},

// 3. 错误处理
startGyroscope() {
  jzH5Gyroscope.startGyroscope({
    interval: 200,
    success: (res) => {
      console.log('成功启动陀螺仪');
    },
    fail: (error) => {
      if (error.errMsg.includes('权限')) {
        uni.showModal({
          title: '权限提示',
          content: '请在设置中允许访问陀螺仪',
          showCancel: false
        });
      } else {
        uni.showToast({
          title: '陀螺仪不可用',
          icon: 'none'
        });
      }
    }
  });
}

🔧 兼容性测试

推荐测试设备

• iOS: iPhone 6s+ / iPad Pro+
• Android: 支持陀螺仪的 Android 5.0+ 设备
• 浏览器: Chrome 50+、Safari 10+、Firefox 40+

测试方法

1. 在 HTTPS 环境下访问页面
2. 点击开始监听按钮
3. 旋转设备观察数据变化
4. 验证数据范围和精度

🆚 与官方 API 的差异

📝 更新日志

v1.0.0

• 初始版本发布
• 实现基本的陀螺仪监听功能
• 支持 iOS 权限请求
• 完整的错误处理机制

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

注意: 本插件仅在 H5 平台有效，其他平台请使用 uni-app 官方 API。