概述

维智定位SDK Flutter 插件 是一款专为 Flutter 框架打造的维智定位 SDK 插件，支持在 Android、iOS、HarmonyOS 三大主流移动平台上，调用原生 维智定位SDK 实现核心定位能力，涵盖持续定位、单次定位、正 / 逆地理编码、场所搜索等功能，为跨平台应用提供统一、便捷的定位开发接口。

核心特点

  1. 跨平台兼容：一站式适配 Android、iOS、HarmonyOS，基于 Flutter 统一封装，降低多平台定位功能开发成本；
  2. 功能完整：覆盖单次 / 连续定位模式，支持地理编码、场所搜索等拓展能力，满足各类定位场景需求；
  3. 权限适配：针对不同平台的定位权限体系（如 Android 后台定位、iOS 前台 / 后台定位、HarmonyOS 场景化权限）提供清晰的配置指引，符合各平台隐私合规要求；
  4. 灵活集成：插件源码不捆绑原生 SDK，开发者可自行导入官方最新版 维智定位SDK，适配不同版本的功能与兼容需求。

核心能力

  • 基础定位：支持单次定位、连续定位，可自定义定位时间间隔；
  • 地理编码：提供正 / 逆地理编码能力，实现坐标与地址信息的互转；
  • 场所搜索：基于定位能力拓展场所检索相关功能；
  • 多平台适配：针对 Android、iOS、HarmonyOS 各自的系统特性，完成原生 SDK 对接与权限、服务配置适配。

集成说明

插件采用本地依赖方式接入，需结合各平台要求完成原生 SDK 导入、权限配置、服务注册等操作，再通过 Dart 层统一调用定位接口。各平台均需遵循对应的隐私合规要求，配置定位权限说明与后台运行权限，确保定位功能正常运行。

无论是出行、物流、生活服务类应用，还是需要基于位置信息的场景化功能开发，维智定位SDK均可快速接入并稳定提供精准的定位能力，是 Flutter 跨平台应用集成 维智定位SDK 的高效解决方案。

开发指南

维智定位SDK Flutter 插件：在 Android / iOS / HarmonyOS 上调用原生 Wayz 定位SDK 完成持续定位、正/逆地理编码、场所搜索等功能。

SDK与Flutter插件：Flutter插件源码不附带 Android/ iOS / HarmonyOS SDK，需由开发者自行导入SDK按平台提供集成文档对接。

安装wz_location_plugin

在应用 pubspec.yaml 中依赖本插件：

本地 path

dependencies:
  wz_location_plugin:
    path: ../wz_location_plugin  # 改为相对你工程的实际路径

然后执行：

flutter pub get

Android 集成

下载 SDK

  • 将官网下载的sdk（示例：wayz-sdk-android-7.1.0.jar）放在 android/app/libs/ 下。
  • 在 android/app/build.gradle 中导入sdk。示例
dependencies {
   implementation files('libs/wayz-sdk-android-7.1.0.jar')
}
  • 在 ../wz_location_plugin/android/build.gradle 中导入sdk。示例
dependencies {
  // 这里sdk路径需配置为实际路径
  compileOnly files('../../../android/app/libs/wayz-sdk-android-7.1.0.jar')
}

添加权限（AndroidManifest.xml）

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

    <!--用于进行网络定位-->
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"></uses-permission>
    <!--用于访问GPS定位-->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"></uses-permission>
    <!--用于读取手机当前的状态，获取基站信息-->
    <uses-permission android:name="android.permission.READ_PHONE_STATE"></uses-permission>
    <!--用于获取运营商信息，用于支持提供运营商信息相关的接口-->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"></uses-permission>
    <!--用于访问wifi网络信息，wifi信息会用于进行网络定位-->
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"></uses-permission>
    <!--用于获取wifi的获取权限，wifi信息会用来进行网络定位-->
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE"></uses-permission>
    <!--用于访问网络，网络定位需要上网-->
    <uses-permission android:name="android.permission.INTERNET"></uses-permission>
    <!--用于申请调用A-GPS模块-->
    <uses-permission android:name="android.permission.ACCESS_LOCATION_EXTRA_COMMANDS"></uses-permission>
    <!-- 基础前台服务权限（兼容 Android 8.0-11） -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
    <!-- Android 12+ 定位类前台服务专用权限 -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION"/>
    <!-- 后台定位核心权限（Android 10+） -->
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>

添加定位服务

<application>
    <service android:name="com.wayz.location.WzService"></service>
</application>

iOS 集成

下载 SDK

  1. 从 Wayz 获取官方的 wzLib.xcframework。

  2. 将 wzLib.xcframework 放在ios目录下（即 /ios/WayzLocal/wzLib.xcframework）。

  3. 在 App 的 ios/Podfile 的 target 'Runner' 中flutter_install_all_ios_pods 之前加入pod 'WayzLocal', :path => 'WayzLocal'：

    target 'Runner' do

  # Wayz wzLib.xcframework 为静态产物时需配置静态 linkage
	# 否则 CocoaPods 报 transitive static binary 错误
  use_frameworks! :linkage => :static
  use_modular_headers!
 	# 导入wzLib.xcframework
  pod 'WayzLocal', :path => 'WayzLocal'

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
  target 'RunnerTests' do
    inherit! :search_paths
  end
end

  4. 执行 pod install 后再编译。

  • 最低 iOS 版本与示例一致为 13.0（platform :ios, '13.0'）。

隐私与权限（Info.plist）

至少配置「使用期间」定位用途说明，若需后台定位再配置「始终」相关键，例如：

<key>NSLocationWhenInUseUsageDescription</key>
<string>是否允许使用您的定位？</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>是否允许后台一直使用定位？</string>

需要后台定位时，在 Info.plist 中配置 UIBackgroundModes 含 location。

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

HarmonyOS 集成

下载 SDK

  1. 从 Wayz 获取官方的 wayz-sdk-hmos-next_3.0.0.har放到应用鸿蒙工程 ohos/libs/
  2. 在应用 ohos/oh-package.json5 中声明依赖。例如："wzlocation": "file:./libs/wayz-sdk-hmos-next_3.0.0.har"
  3. 在 ../wz_location_plugin/ohos/oh-package.json5 中导入sdk。示例
"dependencies": {
    "wzlocation": "file:../../../ohos/libs/wayz-sdk-hmos-next_3.0.0.har"
 }

隐私与权限

在/ohos/entry/src/main/module.json5添加权限：

{
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.LOCATION",
        "reason": "$string:permission_reason_location",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.LOCATION_IN_BACKGROUND",
        "reason": "$string:permission_reason_location_in_background",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "always"
        }
      },
      {
        "name": "ohos.permission.APPROXIMATELY_LOCATION",
        "reason": "$string:permission_reason_approx_location",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.APP_TRACKING_CONSENT",
        "reason": "$string:permission_reason_app_tracking_consent",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.GET_WIFI_INFO",
        "reason": "$string:permission_reason_get_wifi_info",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.GET_NETWORK_INFO",
        "reason": "$string:permission_reason_get_network_info",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.KEEP_BACKGROUND_RUNNING",
        "reason": "$string:permission_reason_keep_background_running",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "always"
        }
      }
    ]
  }
}

在/ohos/entry/src/main/resources/base/element/string.json添加权限说明：

{
  "string": [
    {
      "name": "permission_reason_location",
      "value": "允许应用在前台运行时获取位置信息"
    },
    {
      "name": "permission_reason_location_in_background",
      "value": "允许应用在后台运行时获取位置信息"
    },
    {
      "name": "permission_reason_approx_location",
      "value": "允许应用获取设备模糊位置信息"
    },
    {
      "name": "permission_reason_app_tracking_consent",
      "value": "允许应用获取设备唯一标识符"
    },
    {
      "name": "permission_reason_get_wifi_info",
      "value": "允许应用获取连接wifi信息"
    },
    {
      "name": "permission_reason_get_network_info",
      "value": "允许应用获取网络信息"
    },
    {
      "name": "permission_reason_keep_background_running",
      "value": "允许应用进行长时任务"
    }
  ]
}

Dart 集成与使用

1. 引用

import 'package:wz_location_plugin/wz_location_plugin.dart';

2. 隐私合规

在使用定位功能之前调用以下方法，标识用户已同意隐私政策：

WzLocationPlugin.updatePrivacyShow(true, false);
WzLocationPlugin.updatePrivacyAgree(true);

3. 配置 Key

WzLocationPlugin().setApiKey('你的 apiKey');//官网获取

4.单次定位

WzLocationPlugin().setLocationOption(
  WzLocationOption(
    apiKey: '你的 apiKey', //官网获取
    interval: 5000,//定位时间间隔，单位毫秒
    isLocateOnce: true,//是否是单次定位
  ),
);
StreamSubscription<Map<String, Object?>>? onLocationChangedSub = WzLocationPlugin().onLocationChanged().listen(
          (event) => log('onLocationChanged: $event'),
          onError: (Object e, StackTrace st) => log('onLocationChangederror: $e'),
        );
  };
// 调用前需判断是否授权定位相关权限
WzLocationPlugin().startLocation();

5.连续定位

WzLocationPlugin().setLocationOption(
  WzLocationOption(
    apiKey: '你的 apiKey', //官网获取
    interval: 5000,//定位时间间隔，单位毫秒
    isLocateOnce: false,//是否是单次定位
  ),
);
StreamSubscription<Map<String, Object?>>? onLocationChangedSub = WzLocationPlugin().onLocationChanged().listen(
          (event) => log('onLocationChanged: $event'),
          onError: (Object e, StackTrace st) => log('onLocationChangederror: $e'),
        );
  };
// 调用前需判断是否授权定位相关权限
WzLocationPlugin().startLocation();

定位插件下载：https://lothub.newayz.com/download/flutter-download/

示例代码：https://lothub.newayz.com/download/flutter-download-sample/

# flutter
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

分布式能力在鸿蒙 PC 上到底怎么用？

avatar HarmonyOS开发者社区
cover

从单页面到系统化：鸿蒙 App 演进路径

avatar HarmonyOS开发者社区

HarmonyOS 6学习：CapsLock键失效诊断与长截图完整实现指南

本文深入探讨了HarmonyOS应用开发中的两个典型问题：外接键盘CapsLock键失效和长截图功能实现。针对CapsLock键问题，分析指出需要显式启用功能键并管理状态，提供了完整的权限申请和状态同步方案。对于长截图功能，详细介绍了滚动分段截图、Web组件特殊处理、内存优化等关键技术实现。文章通过对比解决前后的效果数据，展示了方案的有效性，并总结了最佳实践：包括及时启用功能键、渐进式截图处理、性

avatar HarmonyOS开发者社区