@capacitor/geolocation

地理位置 API 提供簡單的方法，可使用 GPS 取得和追蹤裝置的目前位置，以及海拔高度、方位和速度資訊（如果有的話）。

安裝

npm install @capacitor/geolocation
npx cap sync

iOS

Apple 要求必須在 Info.plist 中指定位置資訊的隱私權描述

• NSLocationWhenInUseUsageDescription (Privacy - Location When In Use Usage Description)

請參閱 在 Info.plist 中設定 iOS 指南，以深入瞭解如何在 Xcode 中設定 iOS 權限

Android

此 API 需要將下列權限新增至您的 AndroidManifest.xml

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-feature android:name="android.hardware.location.gps" />

前兩個權限要求位置資料，包括精確和粗略的位置資料，最後一行是選用的，但如果您的應用程式需要 GPS 才能運作，則必須新增。您可以省略它，但請記住，這可能表示您的應用程式會安裝在沒有 GPS 硬體的裝置上。

請參閱 設定權限 Android 指南，以深入瞭解如何設定 Android 權限。

變數

此外掛程式將使用下列專案變數（在您的應用程式的 variables.gradle 檔案中定義）

• playServicesLocationVersion com.google.android.gms:play-services-location 的版本（預設值：21.1.0）

範例

import { Geolocation } from '@capacitor/geolocation';

const printCurrentPosition = async () => {
  const coordinates = await Geolocation.getCurrentPosition();

  console.log('Current position:', coordinates);
};

API

• getCurrentPosition(...)
• watchPosition(...)
• clearWatch(...)
• checkPermissions()
• requestPermissions(...)
• 介面
• 類型別名

getCurrentPosition(...)

getCurrentPosition(options?: PositionOptions | undefined) => Promise<Position>

取得裝置的目前 GPS 位置

參數	類型
options	PositionOptions

傳回： Promise<Position>

起始版本 1.0.0

---

watchPosition(...)

watchPosition(options: PositionOptions, callback: WatchPositionCallback) => Promise<CallbackID>

設定位置變更的監看。請注意，監看位置變更可能會消耗大量電力。請務必在僅需要時才進行監聽。

參數	類型
options	PositionOptions
callback	WatchPositionCallback

傳回： Promise<string>

起始版本 1.0.0

---

clearWatch(...)

clearWatch(options: ClearWatchOptions) => Promise<void>

清除指定的監看

參數	類型
options	ClearWatchOptions

起始版本 1.0.0

---

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

檢查位置權限。如果系統位置服務已停用，則會擲回例外狀況。

傳回： Promise<PermissionStatus>

起始版本 1.0.0

---

requestPermissions(...)

requestPermissions(permissions?: GeolocationPluginPermissions | undefined) => Promise<PermissionStatus>

要求位置權限。如果系統位置服務已停用，則會擲回例外狀況。

參數	類型
permissions	GeolocationPluginPermissions

傳回： Promise<PermissionStatus>

起始版本 1.0.0

---

介面

Position

屬性	類型	說明	起始版本
timestamp	number	座標的建立時間戳記	1.0.0
coords	{ latitude: number; longitude: number; accuracy: number; altitudeAccuracy: number | null; altitude: number | null; speed: number | null; heading: number | null; }	GPS 座標以及資料的精確度	1.0.0

PositionOptions

屬性	類型	說明	預設值	起始版本
enableHighAccuracy	boolean	高精確度模式（例如 GPS，如果有的話）。在 Android 12 以上的裝置上，如果使用者未授予 ACCESS_FINE_LOCATION 權限（可以使用 location 別名檢查），則會忽略此設定。	false	1.0.0
timeout	number	位置更新的最大等待時間（以毫秒為單位）。在 Android 中，由於此外掛程式的 4.0.0 版，timeout 會在 getCurrentPosition 時遭到忽略。	10000	1.0.0
maximumAge	number	可接受傳回的可能快取位置的最長期限（以毫秒為單位）	0	1.0.0

ClearWatchOptions

屬性	類型
id	CallbackID

PermissionStatus

屬性	類型	說明	起始版本
location	PermissionState	location 別名的權限狀態。在 Android 上，它會要求/檢查 ACCESS_COARSE_LOCATION 和 ACCESS_FINE_LOCATION 權限。在 iOS 和網頁上，它會要求/檢查位置權限。	1.0.0
coarseLocation	PermissionState	coarseLocation 別名的權限狀態。在 Android 上，它會要求/檢查 ACCESS_COARSE_LOCATION。在 Android 12 以上的版本中，使用者可以在近似位置 (ACCESS_COARSE_LOCATION) 或精確位置 (ACCESS_FINE_LOCATION) 之間選擇，因此如果應用程式不需要高精確度，則可以使用此別名。在 iOS 和網頁上，它會與 location 別名具有相同的值。	1.2.0

GeolocationPluginPermissions

屬性	類型
permissions	GeolocationPermissionType[]

類型別名

WatchPositionCallback

(position: Position | null, err?: any): void

CallbackID

string

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

GeolocationPermissionType

'location' | 'coarseLocation'