更新记录

1.0.5（2026-09-15） 下载此版本

1. 新增《接入指南.md》，详细说明高德/百度地图SDK接入步骤（5步完整流程、ohpm/HAR两种集成方式、常见问题FAQ）
2. 优化README.md文档结构，添加荣誉标识、能力清单表格、快速接入流程图
3. 新增完整API文档，包含类型定义、参数说明、返回值说明
4. 添加常见问题FAQ（4个核心问题解答）
5. 完善目录结构和联系方式

1.0.4（2026-09-15） 下载此版本

1.0.3（2026-09-14） 下载此版本

1. 完善 displayName/description/keywords（新增 harmony/uni-app-x/amap/baidu/uts-plugin 等关键词）
2. init 增加 provider 必填与白名单校验，避免静默忽略错误入参
3. getLocation 修复 timeoutMs 用 ! 非空断言在 options 为 undefined 时会抛错的问题；统一使用 options && options.timeoutMs > 0 兜底
4. getLocation 增加 location 为空与经纬度 isFinite 校验，错误信息可读化
5. getLocation 把 timeoutMs 一并下发给 geoLocationManager.getCurrentLocation，减少 SDK 内部再次自旋
6. mapAccuracyToPriority 数值按 Harmony 通用 LocationRequestPriority 重映射：high=200(FIRST_FIX)、balanced=102、low=101(LOW_POWER)
7. getContextSafe 增加 globalThis.getContext?.() 兜底，适配不同 HBuilderX/引擎版本
8. requestLocationPermission 改用 (res as any).authResults 安全取数；授权结果独立 return 不再可能误判 granted
9. Provider（amap/baidu）upsertMarker 增加 marker.id 必填校验；upsertMarkers 跳过非法项，避免运行期静默丢数据
10. 对外 API 新增 isInited() 方法，方便业务侧判断初始化状态

平台兼容性

uni-app(4.45)

uni-app x(4.45)

zy-next-map 接入指南

本文档详细说明如何在 uni-app-x 项目中接入本插件，以及如何配置高德/百度地图 SDK。

目录

• 快速概览
• 前置要求
• 方式一：高德地图 SDK 接入（推荐）
• 方式二：百度地图 SDK 接入
• 配置权限声明
• 常见问题

快速概览

前置要求

环境要求

获取应用 AppID

在配置 SDK 前，需要获取你应用的 AppID（用于申请地图 Key）：

// 在 Harmony 侧获取 AppID
import bundleManager from '@ohos.bundle.bundleManager'

let flag = bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_SIGNATURE_INFO
let bundleInfo = bundleManager.getBundleInfoForSelfSync(flag)
let appId = bundleInfo.signatureInfo.appId
console.info('AppID:', appId)

⚠️ 重要：真机调试时使用的 Key 必须基于真机 AppID 申请，云真机调试时使用云真机 AppID 申请。

方式一：高德地图 SDK 接入（推荐）

第一步：申请高德 API Key

1. 访问 高德开放平台
2. 注册/登录开发者账号
3. 进入「控制台」→「应用管理」→「添加应用」
4. 添加「Key」时选择「HarmonyOS」平台
5. 填入上一步获取的 AppID
6. 保存生成的 API Key

第二步：集成高德 SDK

方法 A：通过 ohpm 集成（推荐）

在你的 Harmony 工程根目录下执行：

# 进入工程目录
cd your-project

# 初始化 ohpm（如果尚未初始化）
oh init -t shell

# 添加高德地图 SDK 依赖
ohpm install @amap/amap_map3d_harmony

方法 B：通过 HAR 包集成

1. 下载高德 SDK：相关下载页面
2. 将 .har 文件放入 entry/libs/ 或 libs/ 目录
3. 在 oh-package.json5 中添加依赖：

{
  "dependencies": {
    "@amap/amap_map3d_harmony": "file:./libs/amap_map3d_harmony.har"
  }
}

第三步：配置权限

在 module.json5 中添加：

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.ACCESS_LOCATION"
      },
      {
        "name": "ohos.permission.ACCESS_CONTROLLED_LOCATION"
      }
    ]
  }
}

第四步：设置 API Key

在应用启动时（建议在 EntryAbility 的 onCreate 中）设置 Key：

// EntryAbility.ets 或 Application 中
import AMapConfig from '@amap/amap_map3d_harmony'

export default class EntryAbility extends Ability {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    // 设置高德 API Key
    AMapConfig.setApiKey('你的高德API Key')

    // 注入 Context 给插件使用
    (globalThis as any).__uniContext = this.context
  }
}

第五步：完善 amap.uts 实现

将 utssdk/app-harmony/providers/amap.uts 中的占位控制器替换为真实实现。参考代码如下：

import { ZyMapController, ZyOpenMapOptions } from '../../src/public-types.uts'
import { ZyHarmonyMapProvider } from './provider-types.uts'

// 高德地图 SDK 导入（按你的实际导入路径调整）
import map from '@amap/amap_map3d_harmony'

/**
 * 高德（Harmony）Provider 实现
 */
export function createAmapProvider(debug: boolean): ZyHarmonyMapProvider {
  return {
    createController(options?: ZyOpenMapOptions): ZyMapController {
      return new AMapController(debug, options)
    }
  }
}

/**
 * 高德地图控制器
 */
class AMapController implements ZyMapController {
  private debug: boolean
  private options?: ZyOpenMapOptions
  private mapView: any = null
  private markers: Map<string, any> = new Map()
  private initialized: boolean = false

  constructor(debug: boolean, options?: ZyOpenMapOptions) {
    this.debug = debug
    this.options = options
  }

  private async ensureInitialized(): Promise<void> {
    if (this.initialized) return

    // 获取 mapView 实例
    // 注意：具体实现取决于高德 SDK 的 API
    this.mapView = await map.createMapView({
      // 根据 SDK 文档配置初始参数
    })

    // 设置初始中心点和缩放级别
    if (this.options?.center) {
      await this.setCenter(this.options.center, this.options.zoom)
    }

    // 添加初始标记点
    if (this.options?.markers) {
      await this.upsertMarkers(this.options.markers)
    }

    this.initialized = true
    if (this.debug) console.info('[zy-next-map] AMap initialized')
  }

  async open(): Promise<void> {
    await this.ensureInitialized()
    if (this.debug) console.info('[zy-next-map] AMap opened')
  }

  async setCenter(center: { latitude: number, longitude: number }, zoom?: number): Promise<void> {
    await this.ensureInitialized()

    // 调用高德 SDK 设置中心点
    // this.mapView.setCenter(new AMap.LngLat(center.longitude, center.latitude))
    // if (zoom) {
    //   this.mapView.setZoom(zoom)
    // }

    if (this.debug) {
      console.info('[zy-next-map] AMap setCenter', center, zoom)
    }
  }

  async upsertMarker(marker: any): Promise<void> {
    await this.ensureInitialized()

    if (marker == null || marker.id == null) {
      throw new Error('upsertMarker: marker.id 必填')
    }

    // 创建高德标记点
    // const amapMarker = new AMap.Marker({
    //   position: new AMap.LngLat(marker.position.longitude, marker.position.latitude),
    //   title: marker.title,
    //   snippet: marker.snippet
    // })

    // this.mapView.add(amapMarker)
    this.markers.set(marker.id, marker)

    if (this.debug) {
      console.info('[zy-next-map] AMap upsertMarker', marker.id)
    }
  }

  async upsertMarkers(markers: any[]): Promise<void> {
    await this.ensureInitialized()

    if (!Array.isArray(markers)) return

    for (const m of markers) {
      if (m != null && m.id != null) {
        await this.upsertMarker(m)
      }
    }
  }

  async removeMarker(id: string): Promise<void> {
    await this.ensureInitialized()

    const marker = this.markers.get(id)
    if (marker) {
      // this.mapView.remove(marker)
      this.markers.delete(id)
    }

    if (this.debug) {
      console.info('[zy-next-map] AMap removeMarker', id)
    }
  }

  async clearMarkers(): Promise<void> {
    await this.ensureInitialized()

    // this.mapView.clear()
    this.markers.clear()

    if (this.debug) {
      console.info('[zy-next-map] AMap clearMarkers')
    }
  }

  async close(): Promise<void> {
    if (this.mapView) {
      // this.mapView.destroy()
      this.mapView = null
    }
    this.markers.clear()
    this.initialized = false

    if (this.debug) {
      console.info('[zy-next-map] AMap closed')
    }
  }
}

⚠️ 注意：上述代码中的 map.createMapView、AMap.LngLat 等是高德 SDK 的伪代码示例，具体 API 请参考 高德官方文档。

方式二：百度地图 SDK 接入

第一步：申请百度 API Key

1. 访问 百度地图开放平台
2. 注册开发者账号
3. 创建应用，选择「HarmonyOS」平台
4. 填入 AppID，获取 AK（Access Key）

第二步：集成百度 SDK

百度地图 HarmonyOS SDK 集成方式与高德类似，请参考百度官方文档。

第三步：完善 baidu.uts 实现

参考 amap.uts 的实现方式，将占位控制器替换为百度地图 SDK 的调用。

配置权限声明

HarmonyOS 权限清单

在 module.json5 中配置：

{
  "module": {
    "requestPermissions": [
      // 网络权限（地图数据加载必需）
      {
        "name": "ohos.permission.INTERNET"
      },
      // 位置权限
      {
        "name": "ohos.permission.ACCESS_LOCATION"
      },
      {
        "name": "ohos.permission.ACCESS_CONTROLLED_LOCATION"
      },
      // 后台定位（可选，需要单独申请）
      {
        "name": "ohos.permission.LOCATION_IN_BACKGROUND"
      },
      // 网络权限（精确位置需要）
      {
        "name": "ohos.permission.ACCESS_NETWORK_STATE"
      },
      {
        "name": "ohos.permission.NETWORK_MEDIA"
      }
    ]
  }
}

uni-app manifest 配置

在 manifest.json 中配置 App 原生插件：

{
  "app-harmony": {
    "navigateMiniProgram": {
      "appid": "你的微信小程序AppID（可选）"
    }
  }
}

常见问题

Q1：定位功能正常，但地图不显示？

排查步骤：

1. 确认已正确设置 API Key：AMapConfig.setApiKey('你的Key')
2. 确认已在 module.json5 中添加网络权限
3. 确认设备已连接网络
4. 检查控制台是否有 SDK 初始化错误

Q2：提示"未获取到 Harmony Context"？

解决方案： 在 EntryAbility 或 Application 的 onCreate 中注入：

(globalThis as any).__uniContext = this.context

Q3：如何获取更精确的定位？

方法：

// 高精度定位
const loc = await zyNextAmapBaiduMap.getLocation({
  accuracy: 'high',
  timeoutMs: 10000
})

Q4：支持离线地图吗？

高德 SDK 支持离线地图下载，但需要在 SDK 层面实现。本插件提供了基础框架，具体离线功能可按需扩展。

Q5：如何调试地图显示？

开启调试模式：

await zyNextAmapBaiduMap.init({
  provider: 'amap',
  debug: true  // 开启后会在控制台输出详细日志
})

技术支持

• 插件市场：zy-next-map 插件页面
• 问题反馈：在插件市场评论或联系作者
• 社区讨论：DCloud 问答社区

更新日志

详细更新日志请查看：changelog.md

本文档最后更新：2026-09-15