Cordova - 设备方向

Cordova - 设备方向（指南针）

设备方向（Device Orientation）插件（特别是其中的指南针部分）提供了访问设备指南针的功能，它指示设备指向的方向或朝向（heading），通常是相对于地理正北方向的。

步骤 1 - 安装设备方向插件

打开您的终端（terminal）或命令提示符（command prompt），导航到您的 Cordova 项目的根目录（root directory），然后运行以下命令：

your-cordova-project/ cordova plugin add cordova-plugin-device-orientation

步骤 2 - 添加 UI 元素（可选）

让我们添加一些按钮，用于获取当前朝向以及开始/停止监听朝向变化。将以下代码添加到您的 index.html 文件中：

<body>
    <button id="getCurrentHeadingBtn">Get Current Heading</button>
    <button id="watchHeadingBtn">Watch Heading</button>
    <button id="stopWatchHeadingBtn">Stop Watching</button>
    <div id="headingInfo">Compass heading will appear here.</div>
</body>

步骤 3 - 添加事件监听器

在 www/js/index.js 文件中，在 onDeviceReady 方法内，为这些按钮设置事件监听器（event listeners）：

// 在 www/js/index.js 的 onDeviceReady 方法内
document.getElementById("getCurrentHeadingBtn").addEventListener("click", getCurrentHeading);
document.getElementById("watchHeadingBtn").addEventListener("click", startWatchHeading);
document.getElementById("stopWatchHeadingBtn").addEventListener("click", stopWatchHeading);

步骤 4 - 实现指南针功能

定义与指南针交互的函数。navigator.compass 对象提供了必要的方法（methods）。

const headingDisplay = document.getElementById('headingInfo');
let watchCompassID = null;

function getCurrentHeading() {
    navigator.compass.getCurrentHeading(onCompassSuccess, onCompassError);
}

function startWatchHeading() {
    if (watchCompassID) { // 如果有之前的监听，先清除
        navigator.compass.clearWatch(watchCompassID);
    }
    // 监听朝向变化。本示例中每 3 秒更新一次。
    const compassOptions = { frequency: 3000 }; // 毫秒
    watchCompassID = navigator.compass.watchHeading(onCompassSuccess, onCompassError, compassOptions);
    headingDisplay.innerHTML = 'Watching compass heading...';
}

function stopWatchHeading() {
    if (watchCompassID) {
        navigator.compass.clearWatch(watchCompassID);
        watchCompassID = null;
        headingDisplay.innerHTML = 'Stopped watching compass.';
    } else {
        headingDisplay.innerHTML = 'Not currently watching compass.';
    }
}

function onCompassSuccess(heading) {
    // heading.magneticHeading 提供磁北方向的朝向，范围是 0-359.99 度
    // heading.trueHeading 提供真北方向的朝向（如果可用）
    // heading.headingAccuracy 表示报告朝向与真北朝向之间的偏差度数
    // heading.timestamp 是确定此朝向的时间戳
    headingDisplay.innerHTML =
        `Magnetic Heading: ${heading.magneticHeading.toFixed(2)}°<br/>` +
        (heading.trueHeading !== undefined ? `True Heading: ${heading.trueHeading.toFixed(2)}°<br/>` : '') +
        `Accuracy: ${heading.headingAccuracy}°<br/>` +
        `Timestamp: ${new Date(heading.timestamp).toLocaleTimeString()}`;
}

function onCompassError(error) {
    let errorMsg = 'Compass Error: ';
    switch (error.code) {
        case CompassError.COMPASS_INTERNAL_ERR:
            errorMsg += 'Internal error.';
            break;
        case CompassError.COMPASS_NOT_SUPPORTED:
            errorMsg += 'Compass not supported on this device.';
            break;
        // 旧版本可能使用数字代码
        // case 20: // 如果 CompassError 未定义，则这是 COMPASS_NOT_SUPPORTED 的示例
        //     errorMsg += 'Compass not supported on this device.';
        //     break;
        default:
            errorMsg += `Unknown error (code: ${error.code})`;
    }
    headingDisplay.innerHTML = errorMsg;
    console.error(errorMsg, error);
}

当点击“Get Current Heading”按钮时，将显示当前的指南针朝向。例如：“Magnetic Heading: 123.45°”。

点击“Watch Heading”按钮将持续更新朝向，本例中每 3 秒更新一次（根据 frequency: 3000 设置）。“Stop Watching”按钮将清除此间隔更新。

如果设备没有指南针或发生错误，将调用 onCompassError 函数。例如，如果设备缺少磁传感器，可能会显示：“Compass Error: Compass not supported on this device.”（指南针错误：此设备不支持指南针）。

重要说明

设备支持：并非所有设备都配备硬件指南针。请务必检查设备是否支持，或优雅地处理错误（handle errors gracefully）。
准确性：指南针读数可能受磁场干扰影响。某些平台（platforms）可能提供准确性信息。
权限：在某些平台（platforms）上，使用指南针可能需要位置权限，因为它可用于推断位置。
真北朝向（True Heading）与磁北朝向（Magnetic Heading）：magneticHeading 是原始读数。trueHeading 经过磁偏角（magnetic declination）校正（磁北与真北之间的差异），但并非总能获得。