Skip to content
FEE
Frontend Engineering Essentials
Mid Level
Hardened· 2026-07

[FEE-413] 地理位置、裝置方向與裝置 API ​

INFO

Geolocation API、Device Orientation API 與 Device Motion API 將硬體感測器暴露 給 Web 應用程式。Geolocation 透過 GPS、Wi-Fi 三角定位或基地台資料提供緯度、 經度、海拔、方向與速度。DeviceOrientationEvent 透過加速度計與陀螺儀提供空間 方向資訊,DeviceMotionEvent 則提供原始加速度與旋轉速率資料。這些 API 共同 銜接物理環境與瀏覽器,讓位置感知服務、擴增實境疊加層、指南針介面與動作驅動 互動得以實現,無需原生應用程式包裝。

背景 ​

所有這些 API 都需要明確的使用者授權。若未出現授權提示,瀏覽器不會允許存取位 置或動作感測器;且在大多數平台上,授權必須在使用者手勢的回應中請求。試圖在 未告知使用者原因的情況下靜默存取位置、或在頁面載入時直接存取的應用程式,將 會被封鎖。iOS Safari 13 及更新版本還額外要求在使用者手勢觸發下,以程式呼叫執 行 DeviceOrientationEvent.requestPermission();僅設定事件監聽器本身,在該呼 叫解析為 'granted' 之前,於 iOS 上不會有任何作用。

實際的挑戰在於處理完整的授權生命週期:請求、取得、處理拒絕,並在適當時機再 次請求,同時在感測器不可用時(例如無 GPS 硬體的桌機瀏覽器,或使用者拒絕授 權)仍提供有用的體驗。漸進增強是核心原則:功能在沒有感測器的情況下仍可運 作,感測器則讓它更好。當授權被拒絕時能退回郵遞區號輸入欄位的位置感知門市查 詢,比只呈現空白狀態的版本更有用。

試想一個配送追蹤功能,讓快遞員的位置隨移動即時更新在地圖上。初始實作可能只 在載入時呼叫 getCurrentPosition 取得一次位置。若要即時追蹤快遞員的路徑,則 需要改用 watchPosition,它會安裝一個回呼函式,在裝置位置變化超過可設定的精 確度閾值時觸發。

視覺呈現 ​

範例 ​

js
function getUserLocation() {
  return new Promise((resolve, reject) => {
    if (!navigator.geolocation) {
      reject(new Error('Geolocation not supported'));
      return;
    }
    navigator.geolocation.getCurrentPosition(
      (pos) => resolve({
        lat: pos.coords.latitude,
        lng: pos.coords.longitude,
      }),
      (err) => {
        const messages = {
          1: 'Permission denied, enable location in browser settings',
          2: 'Position unavailable, no location fix',
          3: 'Timeout, location request took too long',
        };
        reject(new Error(messages[err.code] ?? 'Unknown error'));
      },
      { enableHighAccuracy: false, timeout: 8000, maximumAge: 60000 }
    );
  });
}

最佳實踐 ​

必須(MUST)只在向使用者說明為何需要位置資料後,才請求 Geolocation 授 權。 在沒有脈絡的情況下出現的授權提示遭到駁回的比率很高,且在許多瀏覽器中 單次駁回就會永久封鎖該來源的後續提示。在呼叫 getCurrentPosition 之前,於觸 發請求的按鈕旁顯示簡短的行內說明。知情同意的意義超越使用者體驗本身:許多資 料保護法規(包括歐盟 GDPR)要求應用程式收集位置資料前須具備合法依據 (lawful basis),而使用者明確同意正是瀏覽器所提供的其中一種機制。

應該(SHOULD)在 getCurrentPosition 與 watchPosition 的選項中指定 timeout 值,以避免無限期的載入狀態。 若未設定,瀏覽器可能無限期等待 GPS 硬體:冷啟動可能耗時超過 30 秒,訊號不良時甚至完全無法取得定位。設定 5–10 秒 的逾時,搭配退回較低精確度方法或手動輸入表單的 TIMEOUT 錯誤處理程式,能讓 等待時間維持在可預期的範圍內。

必須(MUST)在不再需要持續追蹤時,對 watchPosition 的回傳值呼叫 clearWatch。 watchPosition 在明確停止前會持續查詢位置硬體,即使需要即 時位置的功能已不再可見,仍會消耗電池。將監看 ID 儲存在清理程式碼可存取的變 數中,並在元件卸載、路由切換或功能停用時呼叫 navigator.geolocation.clearWatch(watchId)。在 React 中,慣用的模式是從 useEffect 回傳 clearWatch 呼叫。

必須(MUST)處理所有三種 GeolocationPositionError 代碼: PERMISSION_DENIED(1)、POSITION_UNAVAILABLE(2)與 TIMEOUT(3)。 每種代碼都需要不同的回應。代碼 1 需要說明如何在瀏覽器或作業系統設定中啟用位 置授權。代碼 2 需要備援輸入方式,例如郵遞區號欄位,因為無論授權狀態如何,裝 置都無法判定其位置。代碼 3 需要重試選項或較低精確度的備援,因為定位已逾時, 但後續嘗試可能成功。err.message 屬性在各瀏覽器間並未標準化,不得作為顯示給 使用者的主要錯誤文字。

應該(SHOULD)在 iOS 上附加方向或動作事件監聽器前,先檢查 DeviceOrientationEvent.requestPermission。 在 iOS 13 及更新版本上,動作事 件受限於一個必須源自使用者手勢的明確授權呼叫。若未先呼叫 requestPermission 就附加監聽器,在 iOS 上不會產生任何錯誤,也不會有任何事件觸發,使錯誤在未於 實機測試前完全不可見。檢查 typeof DeviceOrientationEvent.requestPermission === 'function':若存在,則 呼叫它並等待結果後再新增監聽器;若不存在,則直接附加監聽器。

必須(MUST)透過 HTTPS 或從 localhost 提供任何使用這些 API 的頁面。 Geolocation、Device Orientation 與 Device Motion API 皆限制於安全情境 (secure context)中使用。純 HTTP 頁面無論使用者授權狀態為何,都完全無法存 取這些 API:瀏覽器會直接拒絕該 API,且從不顯示授權提示。以 HTTP 提供的測試 環境會讓這些 API 呈現靜默不可用的狀態,可能掩蓋 bug 直到正式環境部署才浮 現。應在啟動時檢查 window.isSecureContext,並主動顯示明確的錯誤訊息,而非 讓 API 呼叫靜默失敗。

設計思維 ​

單次位置取得 vs. 持續追蹤 ​

getCurrentPosition 取得一次位置定位後,呼叫成功回呼一次;適合在特定時刻需 要位置的功能,例如尋找附近地點或填入運送地址欄位。watchPosition 則安裝一 個持續的監聽器,在位置變化超過閾值時每次觸發回呼,並回傳一個數字形式的監看 ID 供後續清理使用。

一次性定位沒有清理步驟;監看則有:一旦使用者離開或元件卸載,導致需要即時位 置的功能不再可見,就必須搭配呼叫 navigator.geolocation.clearWatch(watchId)。 若在那之後仍讓 watchPosition 保持啟用,會使 GPS 硬體在背景持續輪詢,是最快 耗盡行動裝置電池的方式之一。

PositionOptions 的三角取捨 ​

getCurrentPosition 與 watchPosition 都接受一個 PositionOptions 物件作 為第三個引數,其三個屬性彼此互相取捨。提高 enableHighAccuracy 以請求 GPS 定位,通常也需要提高 timeout,因為 GPS 需要時間鎖定衛星:冷啟動可能耗時 30–60 秒,相對於近乎即時的 Wi-Fi 或基地台定位。縮短 maximumAge 會迫使硬體 更頻繁地被查詢,適合需要反映最新位置的導航功能,但對於只需要判斷使用者所在 城市的功能而言則浪費電力。

正確的校準取決於功能本身的需求,而非預設就追求最高精確度。門市查詢或天氣小 工具可以讓 enableHighAccuracy 保持 false,並接受一分鐘以上的 maximumAge; 導航或運動追蹤功能則需要 enableHighAccuracy: true 與較短的 maximumAge, 並應在 GPS 取得首次定位期間顯示載入指示器與取消選項,因為這段等待對使用者 而言可能感覺很長。

深入探討 ​

PositionOptions 欄位參考 ​

enableHighAccuracy 會在可能的情況下請求 GPS 定位,而非依賴 Wi-Fi 三角定位 或基地台資料;預設為 false。GPS 在開闊天空下通常可達到個位數公尺的水平精 確度,一般智慧型手機 GNSS 接收器約為 4.9 公尺,而基於網路的定位則較粗略,通 常落在數十到數百公尺之間,實際數值取決於附近 Wi-Fi 熱點與基地台的密度。

timeout 設定瀏覽器在錯誤回呼以代碼 TIMEOUT(3)觸發前,可花費在取得位置 上的最大毫秒數;沒有預設值。maximumAge 設定快取位置的最大可接受存放時間 (毫秒):若裝置已持有不超過 maximumAge 的定位,瀏覽器會立即回傳而不查詢 硬體。大多數應用程式的合理預設值為 { enableHighAccuracy: false, timeout: 8000, maximumAge: 60000 }。

DeviceOrientationEvent 與 DeviceMotionEvent 欄位 ​

DeviceOrientationEvent 會在裝置空間方向改變時持續觸發,並暴露三個歐拉角。 alpha 是繞 Z 軸的旋轉,範圍 0–360 度,當 absolute 為 true 時等同於羅盤方 位角。beta 是前後傾斜,範圍 -180 到 180 度:裝置平放時為 0,隨著頂端向前傾 而趨近 90,這大致就是使用者將手機直立、以直向模式拿在眼前閱讀時的 beta 值。 gamma 是左右傾斜,範圍 -90 到 90 度:只要裝置沒有向兩側傾倒,無論是平放還 是直立於直向模式,數值都會維持在接近 0;當裝置被翻轉至左側或右側邊緣時,數 值才會趨近 ±90。應用情境包括 AR 疊加層對齊、旋轉指向北方的羅盤 UI 元件,以及 傾斜捲動介面。

DeviceMotionEvent 回報原始感測器資料,而非計算後的方向。acceleration 提 供不含重力的 X、Y、Z 加速度;accelerationIncludingGravity 包含重力向量; rotationRate 提供以每秒度數表示的 alpha、beta 與 gamma 旋轉速率。這些資料 適用於步數計算與搖晃偵測,在這類場景中,原始感測器串流比過濾後的方向角更具 參考價值。這兩種事件都受瀏覽器速率限制,典型間隔約為 16ms(大致 60Hz),但 因裝置而異。

iOS 13 及更新版本要求在任一事件觸發前,先完成最佳實踐中所述的 DeviceOrientationEvent.requestPermission() 明確授權呼叫。Android 與桌機瀏 覽器則無需獨立的授權步驟即可授予動作事件。

安全情境要求 ​

Geolocation、Device Orientation 與 Device Motion API 都限制於透過 HTTPS 或 從 localhost 提供的頁面。此限制由瀏覽器層級強制執行,無法在 JavaScript 中 繞過。window.isSecureContext 會回報目前頁面是否符合資格,在啟動時檢查它, 可讓應用程式顯示明確的錯誤訊息,而非讓 API 呼叫靜默失敗。

以 Page Visibility API 暫停 watchPosition ​

將 watchPosition 與 Page Visibility API 的 visibilitychange 事件搭配使 用,可進一步降低背景電量消耗。當 document.hidden 變為 true 時呼叫 clearWatch,待分頁返回前景時再重新呼叫 watchPosition。這能避免 GPS 硬體 為使用者目前看不到的分頁持續輪詢,在功能本身變為非活躍狀態時呼叫 clearWatch 的基本規則之上再加一層節省。

漸進式增強的實務作法 ​

呼叫 getCurrentPosition 或註冊 deviceorientation 監聽器的程式碼路徑,應 一律先經過特性偵測('geolocation' in navigator、'DeviceOrientationEvent' in window),並搭配可啟動備援 UI 的錯誤處理程式。三種失敗狀態都需要備援: 裝置上不存在該 API、授權遭拒,或感測器暫時無法使用。門市查詢功能可退回手動 搜尋欄位;導航功能可退回手動地址輸入表單。任何狀態都不應讓使用者停留在空白 畫面,或卡在沒有出路的載入指示器上。

授權決定會跨 session 持續存在:使用者一旦授予或拒絕地理位置存取,多數瀏覽器 會記住該來源的決定,不再重新提示。navigator.permissions.query({ name: 'geolocation' })(FEE-415)可在呼叫 getCurrentPosition 之前讀取目前的授 權狀態,讓應用程式直接路由至備援 UI,而不必等待錯誤回呼觸發。此方法回傳的 PermissionStatus 物件也會觸發 onchange 事件,讓 watchPosition 的使用端 能偵測到 session 期間的授權被撤銷(例如使用者在另一個分頁開啟瀏覽器設定並關 閉授權),並在下一次 GPS 回呼失敗前就切換至備援 UI。

位置資料的精確度、來源與隱私 ​

getCurrentPosition 回傳的位置,可能來自 GPS 衛星、Wi-Fi 熱點三角定位、基 地台資料,或三者的組合,實際取決於裝置當下可取得的訊號。GeolocationCoordinates.accuracy 以公尺回報估計的水平精確度;根據 W3C Geolocation 規範,這是一個 95% 信賴半 徑:數值為 5 代表瀏覽器有 95% 的信心,真實位置落在回報座標的 5 公尺範圍內。 將位置顯示在地圖上的應用程式,應將此數值繪製為不確定性圓圈,而非單一圖釘, 讓使用者能看出回報位置實際的精確程度。

enableHighAccuracy: true 只有在硬體能提供更好定位時才有幫助。沒有 GPS 接 收器的筆電或桌機,無論是否設定此選項,精確度都不會改善,這類裝置上的 coords.accuracy 通常維持在數百公尺的範圍。

coords.altitude 與 coords.altitudeAccuracy 在不回報海拔的裝置上可能為 null:多數配備 GNSS 接收器的行動裝置會回報海拔,但基於網路的定位來源通常 不會。coords.heading 與 coords.speed 在相同條件下、或裝置靜止時同樣會是 null。使用前務必對這四個屬性進行 null 檢查。

地理位置資料屬於敏感資料。精確的座標配對,經長時間追蹤後,足以揭露一個人的 住家、工作地點,或就醫紀錄。設計時應遵循資料最小化原則:只請求功能所需的精 確度,只在功能運作期間持有座標,且不將原始座標持久化於 localStorage 或 sessionStorage 中。若座標必須傳送到後端,應截斷至功能實際需要的精確度,而 非直接轉送感測器的完整精確度;只需要鄰里等級位置的功能,不需要到小數點後六 位的經緯度。前端程式碼 MUST NOT(禁止)將原始座標記錄到應用程式日誌,或第三 方錯誤追蹤與分析服務中:這些服務通常不在組織的資料處理協議涵蓋範圍內,而且 位置資料一旦被第三方接收,就很難要求刪除。

延伸閱讀 ​

參考資料 ​