更新记录

0.3.0（2026-07-13） 下载此版本

免费

0.2.0（2026-07-13） 下载此版本

初始发布：全平台天地图 WebView 地图组件，支持标记点、定位、聚合、卫星/标准图切换

平台兼容性

uni-app(4.24)

@geek-fun/uni-map

平台支持

当前版本: 0.2.0 — 早期发布，API 可能变化。

快速开始

1. 安装

通过 HBuilderX 插件市场导入 geekfun-uni-map：

1. 打开 HBuilderX
2. 点击顶部菜单 [插件] → [浏览插件市场]
3. 搜索 geekfun-uni-map
4. 点击"导入插件"

2. 申请天地图 Key

1. 在 lbs.tianditu.gov.cn 注册账号
2. 创建 浏览器端 (Browser) 应用
3. 复制 API Key（tk 值）

当前所有平台都使用天地图，都需要 Key。

3. 使用组件

<template>
  <MapView
    :options="mapOptions"
    @ready="onReady"
    @markertap="onMarkerTap"
    @error="onError"
  />
</template>

<script setup lang="ts">
import MapView from '@geek-fun/uni-map'
import type { MapOptions } from '@geek-fun/uni-map'

const mapOptions: MapOptions = {
  latitude: 39.9,
  longitude: 116.4,
  zoom: 12,
  mapType: 'STANDARD',
  tiandituKey: 'your_tianditu_browser_key',  // 天地图浏览器端 Key
  showMyLocation: true,
}

function onReady() {
  console.log('Map ready')
}

function onMarkerTap(e: { markerId: string | number }) {
  console.log('Marker tapped:', e.markerId)
}

function onError(e: { code: string; message: string }) {
  console.error('Map error:', e.message)
}
</script>

4. HarmonyOS：注册原生组件

在 App.vue 中添加副作用导入（在任何 <embed> 标签渲染之前）：

// App.vue
import '@geek-fun/uni-map'

这会触发 defineNativeEmbed('geekfun-map')，注册原生地图组件。

API 参考

Props

组件只接受一个 options prop，类型为 MapOptions。

Events

外部方法（通过 ref）

<MapView ref="mapRef" :options="mapOptions" />

const mapRef = ref<MapContext>()

// 飞行到指定位置
mapRef.value?.flyTo(24.65, 102.6, 15)

// 替换所有标记点
mapRef.value?.setMarkers([{ id: 1, latitude: 24.65, longitude: 102.6, title: 'Sample' }])

// 获取最近已知用户位置
const loc = mapRef.value?.getUserLocation()

// 请求定位并飞往用户位置
await mapRef.value?.requestLocation()

// 切换标准/卫星地图
mapRef.value?.toggleMapType()

TypeScript 类型

MapOptions

MarkerOptions

MarkerData

TileServerOptions

功能特性

• 🌐 天地图 WebView — 全平台统一（免费）
• 🗺️ 花瓣地图原生 — 鸿蒙代码已就绪，等待 HBuilderX bug 修复
• 📍 内置定位 — 定位按钮 + 加载遮罩反馈
• 🎯 标记点聚合 — 大数据量下自动聚类
• 🛰️ 标准/卫星图切换 — map.setMapType() 内置支持
• 🎨 风险色标记点 — 自定义信息弹窗
• ⏳ 加载遮罩 — 初始化时显示转圈 + 状态文字
• ❌ 参数校验 — 必填字段缺失时显示明确的错误遮罩
• 🧹 无硬编码 Key — tiandituKey 通过 options 运行时传入
• 🔔 @error 事件 — SDK 加载失败或配置错误的回调

高级：自定义瓦片代理

如果你想通过自己的后端代理天地图瓦片（用于安全或缓存）：

const mapOptions: MapOptions = {
  latitude: 39.9,
  longitude: 116.4,
  tiandituKey: 'your_key',
  tileServer: {
    baseUrl: 'https://your-api.com/api/map/tiles',
  },
}

设置 tileServer.baseUrl 后，WebView 会从代理 URL 加载瓦片，而不是直接请求天地图 CDN。

常见问题

地图显示"配置缺失 请传入 tiandituKey"

tiandituKey 是所有平台的必填参数。在 MapOptions 中传入：

const options: MapOptions = {
  latitude: 24.65,
  longitude: 102.6,
  tiandituKey: 'your_tianditu_key',
}

地图空白 / 瓦片不加载（Android/iOS）

1. 确认天地图 Key 是 浏览器端 (Browser) 类型，不是服务端
2. 在天地图控制台将域名白名单设为 * 或你的代理域名。移动端没有固定 referrer，推荐 *
3. 检查设备网络连接是否正常
4. 如果不能用 *，设置瓦片代理 通过自己的域名转发

HarmonyOS：地图白屏

1. 确保 App.vue 中有 import '@geek-fun/uni-map'（在任何 <embed> 渲染之前执行）
2. 确认 agconnect-services.json 已正确配置
3. 确认 AppGallery Connect 中已开启 Map Kit 服务

花瓣地图原生渲染未启用

花瓣地图原生集成代码（utssdk/app-harmony/map.ets）已完整实现，但当前因 HBuilderX 5.07 的 <embed> 组件 bug（nodeRenderType of undefined）而禁用。全平台（含鸿蒙）目前使用天地图 WebView 作为降级方案。原生路径将在 HBuilderX 修复后恢复。

@ready 事件没有触发

组件有一个 6 秒兜底机制：即使 WebView 没有响应也会触发 ready。如果 6 秒后 ready 仍未触发，查看控制台中 [geekfun-map-diag] 相关日志。

License

Apache-2.0