HarmonyOS 平台配置指南

本文档介绍如何在 HarmonyOS 平台上配置和使用 csp_amap_flutter_map 插件。

🎯 前置要求

1. 开发环境要求

• DevEco Studio: 4.0 或以上版本
• HarmonyOS Next: API 10 或以上
• Flutter: 3.1.5 或以上版本
• 高德地图 HarmonyOS SDK: 10.0.0 或以上版本

2. 申请 API Key

1. 访问 高德开放平台
2. 登录并进入控制台
3. 创建 HarmonyOS 应用
4. 获取 HarmonyOS 平台的 API Key

🔧 配置步骤

1. pubspec.yaml 配置

dependencies:
  csp_amap_flutter_map:
    git:
      url: https://gitee.com/sto_workspace/flutter_map.git
      ref: develop

2. 初始化设置

import 'package:csp_amap_flutter_map/csp_amap_flutter_map.dart';
import 'package:st_amap_flutter_base/st_amap_flutter_base.dart';

// 初始化高德地图
AMapInitializer.init(context,
    apiKey: AMapApiKey(
        androidKey: 'your_android_key',
        iosKey: 'your_ios_key',
        ohosKey: 'your_harmonyos_key')); // HarmonyOS API Key

// 合规处理
AMapInitializer.updatePrivacyAgree(
    AMapPrivacyStatement(hasContains: true, hasShow: true, hasAgree: true));

3. HarmonyOS 项目配置

ohos/oh-package.json5

{
  "name": "csp_amap_flutter_map",
  "version": "1.0.0",
  "description": "高德地图SDK Flutter插件 - HarmonyOS 实现",
  "main": "index.ets",
  "dependencies": {
    "@ohos/flutter_ohos": "file:../flutter",
    "@amap/map": "^10.0.0"
  }
}

ohos/src/main/module.json5

{
  "module": {
    "name": "csp_amap_flutter_map",
    "type": "har",
    "deviceTypes": ["phone", "tablet"],
    "requestPermissions": [
      {
        "name": "ohos.permission.LOCATION",
        "reason": "$string:location_permission_reason",
        "usedScene": {
          "abilities": [],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.APPROXIMATELY_LOCATION",
        "reason": "$string:location_permission_reason"
      },
      {
        "name": "ohos.permission.INTERNET",
        "reason": "$string:internet_permission_reason"
      }
    ],
    "metadata": [
      {
        "name": "AMap_api_key",
        "value": "your_harmonyos_api_key_here"
      }
    ]
  }
}

📱 使用示例

基础地图显示

import 'package:flutter/material.dart';
import 'package:csp_amap_flutter_map/csp_amap_flutter_map.dart';

class HarmonyOSMapPage extends StatefulWidget {
  @override
  _HarmonyOSMapPageState createState() => _HarmonyOSMapPageState();
}

class _HarmonyOSMapPageState extends State<HarmonyOSMapPage> {
  late AMapController _mapController;

  static const CameraPosition _initialPosition = CameraPosition(
    target: LatLng(39.909187, 116.397451),
    zoom: 10.0,
  );

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('HarmonyOS 地图示例')),
      body: AMapWidget(
        initialCameraPosition: _initialPosition,
        onMapCreated: (AMapController controller) {
          _mapController = controller;
        },
        onTap: (LatLng latLng) {
          print('点击位置: ${latLng.latitude}, ${latLng.longitude}');
        },
      ),
    );
  }
}

添加标记

class MarkerExamplePage extends StatefulWidget {
  @override
  _MarkerExamplePageState createState() => _MarkerExamplePageState();
}

class _MarkerExamplePageState extends State<MarkerExamplePage> {
  final Set<Marker> _markers = {};
  late AMapController _mapController;

  void _addMarker() {
    const marker = Marker(
      position: LatLng(39.909187, 116.397451),
      icon: BitmapDescriptor.defaultMarker,
      infoWindow: InfoWindow(
        title: 'HarmonyOS 标记',
        snippet: '这是一个 HarmonyOS 平台的标记',
      ),
    );

    setState(() {
      _markers.add(marker);
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: AMapWidget(
        initialCameraPosition: CameraPosition(
          target: LatLng(39.909187, 116.397451),
          zoom: 10.0,
        ),
        markers: _markers,
        onMapCreated: (AMapController controller) {
          _mapController = controller;
        },
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _addMarker,
        child: Icon(Icons.add_location),
      ),
    );
  }
}

🚀 功能特性

✅ 已支持功能

• ✅ 地图显示和基础操作
• ✅ 相机控制（移动、缩放、旋转、倾斜）
• ✅ 标记 (Marker) 添加和管理
• ✅ 折线 (Polyline) 绘制
• ✅ 多边形 (Polygon) 绘制
• ✅ 地图事件监听（点击、长按、相机移动）
• ✅ 坐标转换
• ✅ 地图截图
• ✅ 缓存清理

🔄 开发中功能

• 🔄 定位功能
• 🔄 路径规划
• 🔄 POI 搜索
• 🔄 地理围栏

⚠️ 注意事项

1. 权限申请

使用地图功能前，需要确保应用已获得以下权限：

• ohos.permission.LOCATION - 精确位置权限
• ohos.permission.APPROXIMATELY_LOCATION - 大概位置权限
• ohos.permission.INTERNET - 网络权限

2. API Key 配置

• 确保在 module.json5 中正确配置了 API Key
• HarmonyOS 的 API Key 与 Android/iOS 不同，需要单独申请

3. 性能优化

• 建议在不需要地图时及时释放资源
• 大量标记时考虑使用聚合功能
• 适当控制地图更新频率

🐛 故障排除

常见问题

1. 地图不显示

• 检查 API Key 是否正确配置
• 检查网络权限是否已获取
• 检查高德地图 SDK 版本是否兼容

2. 定位不准确

• 检查位置权限是否已获取
• 检查设备 GPS 功能是否开启
• 在室外环境测试定位功能

3. 性能问题

• 减少同时显示的标记数量
• 使用合适的地图缩放级别
• 避免频繁的地图操作

📞 技术支持

如果遇到问题，可以通过以下方式获取支持：

1. 查看文档: 仔细阅读官方文档和本配置指南
2. 检查日志: 查看 DevEco Studio 控制台输出
3. 参考示例: 查看项目中的 example 示例代码
4. 联系开发团队: 提交 issue 或联系技术支持

📄 许可证

本项目基于 Apache License 2.0 许可证开源。详见 LICENSE 文件。