更新记录

1.0.0（2026-03-10） 下载此版本

• 【新增】yu-compass 首个版本发布，欢迎体验！
• 【新增】支持 Android、iOS 和 Web 多端运行。
• 【新增】通过 UTS 插件实现高性能、高精度的原生角度数据采集。
• 【新增】提供 startListener、stopListener API 和相关接口。

平台兼容性

uni-app x(4.81)

yu-compass 罗盘指南针插件

yu-compass 是一款基于原生系统 API 的高精度指南针/罗盘 UTS 插件。支持 Android、iOS 和 Web 平台，提供简单易用的实时方向角度监听功能。

平台兼容性

引入插件

由于本插件符合 uni_modules 规范，且是 UTS 插件，无需配置额外的依赖，安装后在需要使用的页面直接导入即可。

import { startListener, stopListener } from '@/uni_modules/yu-compass';

API 说明

插件暴露了两个核心方法用于控制罗盘的监听：

1. startListener(callback)

开启指南针传感器监听。

参数：

回调参数说明：

回调函数接收一个参数 degree (number 类型)，表示当前设备距离正北方向的角度。

• 范围：0 <= degree < 360
• 0 表示正北
• 90 表示正东
• 180 表示正南
• 270 表示正西

2. stopListener()

停止指南针传感器监听。由于传感器监听会产生一定的性能消耗，强烈建议在页面卸载或退到后台时调用此方法停止监听。

参数： 无

使用示例

以下是一个简单的 uvue 页面示例，演示如何获取设备旋转角度并将旋转角度应用到图片上：

<template>
    <view class="container">
        <text class="title">当前角度：{{ degree.toFixed(1) }}°</text>

        <!-- 罗盘图片，通过动态 style 控制旋转 -->
        <image 
            class="compass-img" 
            src="/static/compass.png" 
            mode="widthFix"
            :style="{ transform: 'rotate(' + (-degree) + 'deg)' }"
        ></image>

        <button @tap="startCompass">开始指南针</button>
        <button @tap="stopCompass">停止指南针</button>
    </view>
</template>

<script setup>
import { startListener, stopListener } from '@/uni_modules/yu-compass';

const degree = ref(0);

// 开启监听的方法
const startCompass = () => {
    startListener((newDegree: number) => {
        degree.value = newDegree;
    });
};

// 停止监听的方法
const stopCompass = () => {
    stopListener();
};

onMounted(() => {
    // 页面加载后自动开启
    startCompass();
});

onUnmounted(() => {
    // 页面卸载时务必停止监听，释放资源
    stopCompass();
});
</script>

<style>
.container {
    flex-direction: column;
    align-items: center;
    padding-top: 50px;
}

.title {
    font-size: 20px;
    margin-bottom: 30px;
    color: #333;
}

.compass-img {
    width: 300px;
    height: 300px;
    transition: transform 0.1s linear; /* 可以根据需要增加过渡动画使其更平滑 */
}

button {
    margin-top: 20px;
    width: 200px;
}
</style>

注意事项

1. Web 端限制：在 Web 浏览器中使用时，部分设备或浏览器可能由于安全限制（需要 HTTPS，或需要用户主动触发权限授权），无法正常获取方向信息。
2. 硬件要求：运行此插件的设备必须带有磁力计（指南针传感器）和加速度计，否则无法返回有效数据。
3. 确保在不需要指南针功能时调用 stopListener()，这不仅能节约性能，还能显著降低设备的电量消耗。
4. 在 Android 平台上，当应用 Activity 销毁时，插件已内置自动取消注册传感器的安全机制（通过 UTSAndroid.onAppActivityDestroy）。