@nativescript/geolocation

内容

简介
安装
Android 权限要求
iOS 权限要求
使用 @nativescript/geolocation
- 获取当前位置
API
已知问题
- 与 Google Play 服务版本冲突
- Android API 级别 30 上的 openSettingsIfLocationHasBeenDenied

简介

一个用于获取当前位置、监控移动等的地理位置插件。

安装

要安装此插件，请在项目根目录中运行以下命令。

npm install @nativescript/geolocation

Android 权限要求

要在 Android 上使用地理位置，您需要在 AndroidManifest.xml 文件中添加以下权限，该文件位于 App_Resources/Android/src/main 目录内

  <!-- Always include this permission -->
  <!-- This permission is for "approximate" location data -->
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

  <!-- Include only if your app benefits from precise location access. -->
  <!-- This permission is for "precise" location data -->
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

  <!-- Required only when requesting background location access on
       Android 10 (API level 29) and higher. -->
  <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

更多信息可以在此处的 Android 文档中找到。

iOS 权限要求

如果 options 对象的 iosAllowsBackgroundLocationUpdates 属性设置为 true，则在 App_Resources/iOS/Info.plist 文件中需要以下代码

<key>UIBackgroundModes</key>
<array>
  <string>location</string>
</array>

使用 @nativescript/geolocation

获取当前位置

在调用任何获取用户位置的函数之前，请通过调用 enableLocationRequest 方法请求用户的权限。一旦用户授予了权限，您就可以调用 getCurrentLocation() 方法，并传递一个 options 对象来获取用户当前位置。

import * as geolocation from '@nativescript/geolocation';
import { CoreTypes } from '@nativescript/core' // used to describe at what accuracy the location should get

geolocation.enableLocationRequest().then(() => {
    
    geolocation.getCurrentLocation({ desiredAccuracy: CoreTypes.Accuracy.high, maximumAge: 5000, timeout: 20000 }).then((currentLocation) => {

      console.log("My current latitude: ", currentLocation.latitude)
    })
  })

API

插件函数

该插件提供了以下功能以获取当前位置以及更多

方法	返回值	描述
`getCurrentLocation(options: Options)`	Promise<Location>	根据指定的选项（如有）获取当前位置。自插件的 5.0 版本起，它将使用 requestLocation API，用于使用 `iOS 9.0+` 的设备。在 GPS 信号弱或无信号但有 Wi-Fi 的情况下，它将花费 10 秒来返回位置。 `options` 参数是可选的。
`watchLocation(successCallback: successCallbackType, errorCallback: errorCallbackType, options?: Options)`	`number`	监控位置变化。
`watchPermissionStatus(permissionCallback: permissionCallbackType, errorCallback: errorCallbackType)`	`number`	(`iOS 仅支持`)监控位置权限的变化。
`clearWatch(watchId: number)`	`void`	停止监控位置变化。 `watchId` 参数由 `watchLocation()` 方法返回。
`enableLocationRequest(always?: boolean, openSettingsIfLocationHasBeenDenied?: boolean`	`Promise<void>`	请求使用位置服务的权限。在iOS中，如果`always`设置为`true`，请将以下键添加到`Info.plist`中：NSLocationAlwaysAndWhenInUseUsageDescription（iOS 11.0+）或NSLocationAlwaysUsageDescription（iOS 8.0-10.0）和NSLocationWhenInUseUsageDescription。更多关于请求始终使用权限的信息。在Android中，如果`SDK >= 29`，将`always`参数设置为`true`需要在`AndroidManifest.xml`中添加`ACCESS_BACKGROUND_LOCATION`权限。这将导致用户看到一个包含“始终允许”选项的系统对话框。有关Android位置权限的更多信息，请参阅此处和此处。如果`openSettingsIfLocationHasBeenDenied`设置为`true`且权限之前已被拒绝，则设置应用将打开，以便用户可以更改位置服务权限。有关此处的异常信息。
`isEnabled(options?: Options)`	`Promise<boolean>`	根据位置服务的可用性解析为`true`或`false`。
`distance(loc1: Location, loc2: Location)`	`number`	计算两个位置之间的距离。返回以米为单位距离。
`getIOSLocationManagerStatus()`	CLAuthorizationStatus	返回位置授权权限的状态。

位置类

这是一个数据类，封装了以下针对地理定位的常见属性。

属性	类型	描述
`latitude`	`number`	地理定位的纬度，以度为单位。
`longitude`	`number`	地理定位的经度，以度为单位。
`altitude`	`number`	海拔（如果可用），以海平面以上米为单位。
`horizontalAccuracy`	`number`	水平精度，以米为单位。
`verticalAccuracy`	`number`	垂直精度，以米为单位。
`speed`	`number`	速度，以地面每秒米为单位。
`timestamp`	`日期`	确定此位置的时间。

选项接口

以下是在将选项对象传递给插件函数时传递的选项对象的属性。

属性	类型	描述
`desiredAccuracy`	`CoreTypes.Accuracy`	可选：指定是否需要高精度或任何精度。默认为`CoreTypes.Accuracy.high`，它返回可用的最佳位置，但比`CoreTypes.Accuracy.any`选项消耗更多电量。`Accuracy.any`被认为大约是100米精度。
`updateDistance`	`number`	可选：指定更新位置的时间间隔。更新距离过滤器以米为单位。更多信息请参阅Apple文档和/或Google文档
`updateTime`	`number`	位置更新之间的间隔，以毫秒为单位（iOS上忽略）。更多信息请参阅Google文档。默认为`1分钟`
`minimumUpdateTime`	`number`	可选：位置更新之间的最小时间间隔，以毫秒为单位（iOS上忽略）。更多信息请参阅Google文档。
`maximumAge`	`number`	可选：位置数据的最长年龄，以毫秒为单位。
`timeout`	`number`	可选：表示等待位置的时长，以毫秒为单位。默认为`5分钟`。
`iosAllowsBackgroundLocationUpdates`	`布尔值`	可选：表示是否允许应用在后台接收位置更新（Android上忽略）。默认为`false`。如果启用，则需要在`Info.plist`中的`UIBackgroundModes`键中指定。更多信息请参阅Apple文档
`iosPausesLocationUpdatesAutomatically`	`布尔值`	指示是否允许禁用位置更新的自动暂停（在Android上忽略）。更多信息请参阅苹果文档

破坏性更改

9.0+:
- watchLocation 现在是 async 以在尝试监视之前检查权限

已知问题

Android API 级别 30 上的 openSettingsIfLocationHasBeenDenied

如果用户在Android API级别30的应用程序安装期间两次拒绝权限，即使 enableLocationRequest() 的 openSettingsIfLocationHasBeenDenied 选项为真，用户也不会被带到设置。

许可证

Apache许可证版本2.0