Flutter Geolocator Plugin #
Flutter 地理定位器插件 #

A Flutter geolocation plugin which provides easy access to platform specific location services (FusedLocationProviderClient or if not available the LocationManager on Android and CLLocationManager on iOS).
Flutter 地理定位插件，可轻松访问特定于平台的位置服务（FusedLocationProviderClient，或者如果不可用，则为 Android 上的 LocationManager 和 iOS 上的 CLLocationManager）。

Features # 特征 ＃

• Get the last known location;
  获取最后已知位置；
• Get the current location of the device;
  获取设备当前位置；
• Get continuous location updates;
  获取持续的位置更新；
• Check if location services are enabled on the device;
  检查设备是否开启定位服务；
• Calculate the distance (in meters) between two geocoordinates;
  计算两个地理坐标之间的距离（以米为单位）；
• Calculate the bearing between two geocoordinates;
  计算两个地理坐标之间的方位角；

IMPORTANT: 重要的：

Version 7.0.0 of the geolocator plugin contains several breaking changes, for a complete overview please have a look at the Breaking changes in 7.0.0 wiki page.
地理定位器插件 7.0.0 版本包含多项重大更改，有关完整概述，请查看 7.0.0 维基页面中的重大更改。

Starting from version 6.0.0 the geocoding features (placemarkFromAddress and placemarkFromCoordinates) are no longer part of the geolocator plugin. We have moved these features to their own plugin: geocoding. This new plugin is an improved version of the old methods.
从版本 6.0.0 开始，地理编码功能（ placemarkFromAddress 和 placemarkFromCoordinates ）不再是地理定位器插件的一部分。我们已将这些功能转移到他们自己的插件中：地理编码。这个新插件是旧方法的改进版本。

Usage # 用法 ＃

To add the geolocator to your Flutter application read the install instructions. Below are some Android and iOS specifics that are required for the geolocator to work correctly.
要将地理定位器添加到您的 Flutter 应用程序中，请阅读安装说明。以下是地理定位器正常工作所需的一些 Android 和 iOS 细节。

android.useAndroidX=true
android.enableJetifier=true

android {
  compileSdkVersion 33

  ...
}

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs access to location when open.</string>

post_install do |installer|
  installer.pods_project.targets.each do |target|
    if target.name == "geolocator_apple"
      target.build_configurations.each do |config|
        config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= ['$(inherited)', 'BYPASS_PERMISSION_LOCATION_ALWAYS=1']
      end
    end
  end
end

<key>NSLocationTemporaryUsageDescriptionDictionary</key>
<dict>
  <key>YourPurposeKey</key>
  <string>The example App requires temporary access to the device&apos;s precise location.</string>
</dict>

<key>NSLocationUsageDescription</key>
<string>This app needs access to location.</string>

<key>com.apple.security.personal-information.location</key>
<true/>

<key>NSLocationTemporaryUsageDescriptionDictionary</key>
<dict>
  <key>YourPurposeKey</key>
  <string>The example App requires temporary access to the device&apos;s precise location.</string>
</dict>

Example # 例子 ＃

The code below shows an example on how to acquire the current position of the device, including checking if the location services are enabled and checking / requesting permission to access the position of the device:
下面的代码显示了如何获取设备当前位置的示例，包括检查位置服务是否启用以及检查/请求访问设备位置的权限：

import 'package:geolocator/geolocator.dart';

/// Determine the current position of the device.
///
/// When the location services are not enabled or permissions
/// are denied the `Future` will return an error.
Future<Position> _determinePosition() async {
  bool serviceEnabled;
  LocationPermission permission;

  // Test if location services are enabled.
  serviceEnabled = await Geolocator.isLocationServiceEnabled();
  if (!serviceEnabled) {
    // Location services are not enabled don't continue
    // accessing the position and request users of the 
    // App to enable the location services.
    return Future.error('Location services are disabled.');
  }

  permission = await Geolocator.checkPermission();
  if (permission == LocationPermission.denied) {
    permission = await Geolocator.requestPermission();
    if (permission == LocationPermission.denied) {
      // Permissions are denied, next time you could try
      // requesting permissions again (this is also where
      // Android's shouldShowRequestPermissionRationale 
      // returned true. According to Android guidelines
      // your App should show an explanatory UI now.
      return Future.error('Location permissions are denied');
    }
  }
  
  if (permission == LocationPermission.deniedForever) {
    // Permissions are denied forever, handle appropriately. 
    return Future.error(
      'Location permissions are permanently denied, we cannot request permissions.');
  } 

  // When we reach here, permissions are granted and we can
  // continue accessing the position of the device.
  return await Geolocator.getCurrentPosition();
}

API # API#

Geolocation # 地理位置#

Current location 当前位置

To query the current location of the device simply make a call to the getCurrentPosition method. You can finetune the results by specifying the following parameters:
要查询设备的当前位置，只需调用 getCurrentPosition 方法即可。您可以通过指定以下参数来微调结果：

• desiredAccuracy: the accuracy of the location data that your app wants to receive;
  desiredAccuracy ：您的应用想要接收的位置数据的准确性；
• timeLimit: the maximum amount of time allowed to acquire the current location. When the time limit is passed a TimeOutException will be thrown and the call will be cancelled. By default no limit is configured.
  timeLimit ：允许获取当前位置的最长时间。当超过时间限制时，将抛出 TimeOutException 并取消调用。默认情况下没有配置限制。

import 'package:geolocator/geolocator.dart';

Position position = await Geolocator.getCurrentPosition(desiredAccuracy: LocationAccuracy.high);

Last known location 最后已知位置

To query the last known location retrieved stored on the device you can use the getLastKnownPosition method (note that this can result in a null value when no location details are available):
要查询设备上存储的最后检索到的已知位置，您可以使用 getLastKnownPosition 方法（请注意，当没有位置详细信息可用时，这可能会导致 null 值）：

import 'package:geolocator/geolocator.dart';

Position? position = await Geolocator.getLastKnownPosition();

Listen to location updates
收听位置更新

To listen for location changes you can call the getPositionStream to receive stream you can listen to and receive position updates. You can finetune the results by specifying the following parameters:
要监听位置更改，您可以调用 getPositionStream 来接收流，您可以监听并接收位置更新。您可以通过指定以下参数来微调结果：

• accuracy: the accuracy of the location data that your app wants to receive;
  accuracy ：您的应用想要接收的位置数据的准确性；
• distanceFilter: the minimum distance (measured in meters) a device must move horizontally before an update event is generated;
  distanceFilter ：设备在生成更新事件之前必须水平移动的最小距离（以米为单位）；
• timeLimit: the maximum amount of time allowed between location updates. When the time limit is passed a TimeOutException will be thrown and the stream will be cancelled. By default no limit is configured.
  timeLimit ：位置更新之间允许的最长时间。当超过时间限制时，将抛出 TimeOutException 并且流将被取消。默认情况下没有配置限制。

import 'package:geolocator/geolocator.dart';

final LocationSettings locationSettings = LocationSettings(
  accuracy: LocationAccuracy.high,
  distanceFilter: 100,
);
StreamSubscription<Position> positionStream = Geolocator.getPositionStream(locationSettings: locationSettings).listen(
    (Position? position) {
        print(position == null ? 'Unknown' : '${position.latitude.toString()}, ${position.longitude.toString()}');
    });

In certain situation it is necessary to specify some platform specific settings. This can be accomplished using the platform specific AndroidSettings or AppleSettings classes. When using a platform specific class, the platform specific package must be imported as well. For example:
在某些情况下，有必要指定一些特定于平台的设置。这可以使用特定于平台的 AndroidSettings 或 AppleSettings 类来完成。当使用特定于平台的类时，还必须导入特定于平台的包。例如：

import 'package:geolocator/geolocator.dart';
import 'package:geolocator_apple/geolocator_apple.dart';
import 'package:geolocator_android/geolocator_android.dart';

late LocationSettings locationSettings;

if (defaultTargetPlatform == TargetPlatform.android) {
  locationSettings = AndroidSettings(
    accuracy: LocationAccuracy.high,
    distanceFilter: 100,
    forceLocationManager: true,
    intervalDuration: const Duration(seconds: 10),
    //(Optional) Set foreground notification config to keep the app alive 
    //when going to the background
    foregroundNotificationConfig: const ForegroundNotificationConfig(
        notificationText:
        "Example app will continue to receive your location even when you aren't using it",
        notificationTitle: "Running in Background",
        enableWakeLock: true,
    )
  );
} else if (defaultTargetPlatform == TargetPlatform.iOS || defaultTargetPlatform == TargetPlatform.macOS) {
  locationSettings = AppleSettings(
    accuracy: LocationAccuracy.high,
    activityType: ActivityType.fitness,
    distanceFilter: 100,
    pauseLocationUpdatesAutomatically: true,
    // Only set to true if our app will be started up in the background.
    showBackgroundLocationIndicator: false,
  );
} else {
    locationSettings = LocationSettings(
    accuracy: LocationAccuracy.high,
    distanceFilter: 100,
  );
}

StreamSubscription<Position> positionStream = Geolocator.getPositionStream(locationSettings: locationSettings).listen(
    (Position? position) {
        print(position == null ? 'Unknown' : '${position.latitude.toString()}, ${position.longitude.toString()}');
    });

Location accuracy (Android and iOS 14+ only)
位置准确性（仅限 Android 和 iOS 14+）

To query if a user enabled Approximate location fetching or Precise location fetching, you can call the Geolocator().getLocationAccuracy() method. This will return a Future<LocationAccuracyStatus>, which when completed contains a LocationAccuracyStatus.reduced if the user has enabled Approximate location fetching or LocationAccuracyStatus.precise if the user has enabled Precise location fetching. When calling getLocationAccuracy before the user has given permission, the method will return LocationAccuracyStatus.reduced by default. On iOS 13 or below, the method getLocationAccuracy will always return LocationAccuracyStatus.precise, since that is the default value for iOS 13 and below.
要查询用户是否启用了近似位置获取或精确位置获取，您可以调用 Geolocator().getLocationAccuracy() 方法。这将返回 Future<LocationAccuracyStatus> ，如果用户启用了近似位置获取，则完成后包含 LocationAccuracyStatus.reduced ；如果用户启用了精确位置获取，则包含 LocationAccuracyStatus.precise 。在用户授予权限之前调用 getLocationAccuracy 时，该方法将默认返回 LocationAccuracyStatus.reduced 。在 iOS 13 或更低版本上，方法 getLocationAccuracy 将始终返回 LocationAccuracyStatus.precise ，因为这是 iOS 13 及更低版本的默认值。

import 'package:geolocator/geolocator.dart';

var accuracy = await Geolocator.getLocationAccuracy();

Location service information
位置服务信息

To check if location services are enabled you can call the isLocationServiceEnabled method:
要检查位置服务是否已启用，您可以调用 isLocationServiceEnabled 方法：

import 'package:geolocator/geolocator.dart';

bool isLocationServiceEnabled  = await Geolocator.isLocationServiceEnabled();

To listen for service status changes you can call the getServiceStatusStream. This will return a Stream<ServiceStatus> which can be listened to, to receive location service status updates.
要侦听服务状态更改，您可以调用 getServiceStatusStream 。这将返回一个可以监听的 Stream<ServiceStatus> ，以接收位置服务状态更新。

import 'package:geolocator/geolocator.dart';

StreamSubscription<ServiceStatus> serviceStatusStream = Geolocator.getServiceStatusStream().listen(
    (ServiceStatus status) {
        print(status);
    });

Permissions # 权限#

When using the web platform, the checkPermission method will return the LocationPermission.denied status, when the browser doesn't support the JavaScript Permissions API. Nevertheless, the getCurrentPosition and getPositionStream methods can still be used on the web platform.
使用网络平台时，如果浏览器不支持 JavaScript Permissions API， checkPermission 方法将返回 LocationPermission.denied 状态。尽管如此， getCurrentPosition 和 getPositionStream 方法仍然可以在Web平台上使用。

If you want to check if the user already granted permissions to acquire the device's location you can make a call to the checkPermission method:
如果您想检查用户是否已授予获取设备位置的权限，您可以调用 checkPermission 方法：

import 'package:geolocator/geolocator.dart';

LocationPermission permission = await Geolocator.checkPermission();

If you want to request permission to access the device's location you can call the requestPermission method:
如果您想请求访问设备位置的权限，您可以调用 requestPermission 方法：

import 'package:geolocator/geolocator.dart';

LocationPermission permission = await Geolocator.requestPermission();

Possible results from the checkPermission and requestPermission methods are:
checkPermission 和 requestPermission 方法的可能结果是：

Note: Android can only return whileInUse, always or denied when checking permissions. Due to limitations on the Android OS it is not possible to determine if permissions are denied permanently when checking permissions. Using a workaround the geolocator is only able to do so as a result of the requestPermission method. More information can be found in our wiki.
注意：Android 在检查权限时只能返回 whileInUse 、 always 或 denied 。由于 Android 操作系统的限制，在检查权限时无法确定权限是否被永久拒绝。使用解决方法，地理定位器只能通过 requestPermission 方法来执行此操作。更多信息可以在我们的维基百科中找到。

Settings # 设置 ＃

In some cases it is necessary to ask the user and update their device settings. For example when the user initially permanently denied permissions to access the device's location or if the location services are not enabled (and, on Android, automatic resolution didn't work). In these cases you can use the openAppSettings or openLocationSettings methods to immediately redirect the user to the device's settings page.
在某些情况下，有必要询问用户并更新他们的设备设置。例如，当用户最初永久拒绝访问设备位置的权限或未启用位置服务（并且在 Android 上，自动解析不起作用）时。在这些情况下，您可以使用 openAppSettings 或 openLocationSettings 方法立即将用户重定向到设备的设置页面。

On Android the openAppSettings method will redirect the user to the App specific settings where the user can update necessary permissions. The openLocationSettings method will redirect the user to the location settings where the user can enable/ disable the location services.
在 Android 上， openAppSettings 方法会将用户重定向到应用程序特定设置，用户可以在其中更新必要的权限。 openLocationSettings 方法会将用户重定向到位置设置，用户可以在其中启用/禁用位置服务。

On iOS we are not allowed to open specific setting pages so both methods will redirect the user to the Settings App from where the user can navigate to the correct settings category to update permissions or enable/ disable the location services.
在 iOS 上，我们不允许打开特定的设置页面，因此这两种方法都会将用户重定向到“设置”应用程序，用户可以在其中导航到正确的设置类别以更新权限或启用/禁用位置服务。

import 'package:geolocator/geolocator.dart';

await Geolocator.openAppSettings();
await Geolocator.openLocationSettings();

Utility methods # 实用方法#

To calculate the distance (in meters) between two geocoordinates you can use the distanceBetween method. The distanceBetween method takes four parameters:
要计算两个地理坐标之间的距离（以米为单位），您可以使用 distanceBetween 方法。 distanceBetween 方法有四个参数：

import 'package:geolocator/geolocator.dart';

double distanceInMeters = Geolocator.distanceBetween(52.2165157, 6.9437819, 52.3546274, 4.8285838);

If you want to calculate the bearing between two geocoordinates you can use the bearingBetween method. The bearingBetween method also takes four parameters:
如果要计算两个地理坐标之间的方位角，可以使用 bearingBetween 方法。 bearingBetween 方法还采用四个参数：

import 'package:geolocator/geolocator.dart';

double bearing = Geolocator.bearingBetween(52.2165157, 6.9437819, 52.3546274, 4.8285838);

Location accuracy # 定位精度#

Android 安卓

On Android, the LocationAccuracy enum controls the accuracy of the location data the app wants to receive. It also provides control over the priority given to the location stream. This can be confusing, as a priority of lowest might not return any location, while one might expect it to give the quickest responses. The table below outlines the priority and its meaning per accuracy option:
在 Android 上， LocationAccuracy 枚举控制应用想要接收的位置数据的准确性。它还提供对位置流优先级的控制。这可能会令人困惑，因为最低优先级可能不会返回任何位置，而人们可能期望它给出最快的响应。下表概述了每个精度选项的优先级及其含义：

iOS

On iOS, the LocationAccuracy enum controls the accuracy of the location data the app wants to receive. It also provides control on the battery consumption of the device: the more detailed data is requested, the larger the impact on the battery consumption. More details can be found on Apple's documentation. The table below shows how the LocationAccuracy values map to the native iOS accuracy settings.
在 iOS 上， LocationAccuracy 枚举控制应用程序想要接收的位置数据的准确性。它还提供对设备电池消耗的控制：请求的数据越详细，对电池消耗的影响就越大。更多详细信息可以在 Apple 的文档中找到。下表显示了 LocationAccuracy 值如何映射到本机 iOS 准确度设置。

Issues # 问题 ＃

Please file any issues, bugs or feature requests as an issue on our GitHub page. Commercial support is available, you can contact us at hello@baseflow.com.
请将任何问题、错误或功能请求作为问题提交到我们的 GitHub 页面上。提供商业支持，您可以通过 hello@baseflow.com 联系我们。

Want to contribute # 想要贡献#

If you would like to contribute to the plugin (e.g. by improving the documentation, solving a bug or adding a cool new feature), please carefully review our contribution guide and send us your pull request.
如果您想为插件做出贡献（例如，通过改进文档、解决错误或添加很酷的新功能），请仔细查看我们的贡献指南并向我们发送您的拉取请求。

Author # 作者 ＃

This Geolocator plugin for Flutter is developed by Baseflow.
Flutter 的 Geolocator 插件由 Baseflow 开发。