更新记录

1.0.0（2026-06-09） 下载此版本

1.0.0（2026-06-06）

首次发布

核心功能

• ✅ 基础地图组件 siji-tianditu

  • 支持地图显示和交互
  • 支持自定义中心点和缩放级别
  • 支持中心定位图标显示
  • 支持定位按钮
  • 支持地图拖拽事件
  • 支持地图加载完成回调

• ✅ 地图选择器组件 siji-tianditu-picker

  • 弹窗式地图选择器
  • 自动定位功能（每次打开自动定位到当前位置）
  • 实时地址解析（拖拽地图自动获取地址）
  • 完整的交互流程（确认/取消按钮）
  • 位置信息展示（经纬度、地址）

工具函数

• ✅ getAddressByLocation - 逆地理编码（坐标转地址）
• ✅ getLocationByAddress - 正地理编码（地址转坐标）

特性

平台兼容性

uni-app(3.7.9)

其他

私集天地图组件 siji-tianditu

基于天地图 API 的 uni-app 地图组件，支持地图显示、定位、地址解析等功能。

私集官网 www.sijicms.com

📦 组件说明

本插件包含两个核心组件：

1. siji-tianditu - 基础地图组件

用于直接在页面中显示地图，支持地图交互、定位、拖拽等功能。

2. siji-tianditu-picker - 地图选择器组件

带弹窗的地图选择器，用于位置选择场景，内置定位、地址解析、确认/取消等完整交互流程。

🔑 坐标系说明

默认坐标系

天地图使用 WGS84 坐标系。

如果您使用的是其他坐标系（如百度坐标 BD09、火星坐标 GCJ02），需要先进行坐标转换。

坐标转换工具

推荐使用 @isvend/coord-transform 进行坐标转换：

# npm
npm install @isvend/coord-transform

# pnpm
pnpm add @isvend/coord-transform

转换示例

import {
    transformWGS84ToBD09,
    transformBD09ToGCJ02,
    transformBD09ToWGS84,
    transformGCJ02ToWGS84,
    transformWGS84ToGCJ02,
} from "@isvend/coord-transform";

const lng = 116.404;
const lat = 39.915;

// WGS84 转 GCJ02（火星坐标）
console.log("WGS84 to GCJ02", transformWGS84ToGCJ02(lng, lat));

// GCJ02 转 WGS84
console.log("GCJ02 to WGS84", transformGCJ02ToWGS84(lng, lat));

// WGS84 转 BD09（百度坐标）
console.log("WGS84 to BD09", transformWGS84ToBD09(lng, lat));

// BD09 转 WGS84
console.log("BD09 to WGS84", transformBD09ToWGS84(lng, lat));

🚀 快速开始

方式一：使用地图选择器（推荐）

适用于需要用户选择位置的场景，如填写地址、选择配送地点等。

<template>
  <view>
    <button @tap="openLocationPicker">选择位置</button>

    <!-- 地图选择器组件 -->
    <siji-tianditu-picker
      ref="mapPicker"
      :map-key="mapKey"
      :center="center"
      :zoom="zoom"
      :on-confirm="handleConfirm"
      :on-cancel="handleCancel">
    </siji-tianditu-picker>
  </view>
</template>

<script>
export default {
  data() {
    return {
      mapKey: '你的天地图API Key',
      center: [116.411794, 39.9068], // 默认中心点（北京）
      zoom: 18
    }
  },
  methods: {
    // 打开地图选择器
    openLocationPicker() {
      this.$refs.mapPicker.show();
    },

    // 确认选择
    handleConfirm(data) {
      console.log('选择的位置:', data);
      // data 包含: { lon, lat, address }
    },

    // 取消选择
    handleCancel() {
      console.log('取消选择');
    }
  }
}
</script>

方式二：直接使用地图组件

适用于需要直接展示地图的场景。

<template>
  <view style="width: 100%; height: 500px;">
    <siji-tianditu 
      ref="map"
      :map-key="mapKey" 
      :lonlat="center" 
      :zoom="zoom"
      :show-center-icon="true"
      :show-location-icon="true"
      :auto-get-address="true"
      :on-location="onLocation"
      :on-loaded="onMapLoaded"
      :on-end-drag="onMapDrag"
      :on-address-change="onAddressChange">
    </siji-tianditu>
  </view>
</template>

<script>
export default {
  data() {
    return {
      mapKey: '你的天地图API Key',
      center: [116.411794, 39.9068],
      zoom: 16
    }
  },
  methods: {
    onMapLoaded() {
      console.log('地图加载完成');
    },

    onLocation() {
      console.log('点击定位按钮');
      // 可以在这里调用 uni.getLocation 获取当前位置
    },

    onMapDrag(lon, lat) {
      console.log('地图拖拽结束', lon, lat);
    },

    onAddressChange(data) {
      console.log('地址变化:', data);
      // data 包含: { lon, lat, address }
    }
  }
}
</script>

📖 API 文档

一、siji-tianditu-picker（地图选择器）

Props

Methods

特性

• ✅ 自动定位：每次打开弹窗自动定位到当前位置
• ✅ 地址解析：拖拽地图自动获取当前位置的地址
• ✅ 完整交互：内置确认/取消按钮，提供完整的选择流程
• ✅ 位置信息：实时显示当前位置的经纬度和地址

二、siji-tianditu（基础地图组件）

Props

Methods

🔧 工具函数

组件内置了地图工具函数，位于 mapUtils.js：

getAddressByLocation

逆地理编码 - 根据坐标获取地址

import { getAddressByLocation } from '@/uni_modules/siji-tianditu/components/siji-tianditu/mapUtils.js';

const address = await getAddressByLocation(116.404, 39.915, 'your-map-key');
console.log(address); // 返回地址字符串

参数：

• lon (Number): 经度
• lat (Number): 纬度
• mapKey (String): 天地图 API Key（必填）

返回： Promise - 地址字符串

getLocationByAddress

正地理编码 - 根据地址获取坐标

import { getLocationByAddress } from '@/uni_modules/siji-tianditu/components/siji-tianditu/mapUtils.js';

const location = await getLocationByAddress('北京市天安门', 'your-map-key');
console.log(location); // { lon: 116.404, lat: 39.915 }

参数：

• address (String): 地址
• mapKey (String): 天地图 API Key（必填）

返回： Promise<Object> - { lon, lat }

🔐 安全建议

API Key 安全

不推荐： 将 API Key 直接写在前端代码中

// ❌ 不安全
data() {
  return {
    mapKey: 'b8502a3df597515cb919b348a333f9b9'
  }
}

推荐方案：

1. 使用后端代理（最安全）

前端不直接调用天地图 API，而是通过自己的后端服务转发请求。

// 后端 API
app.get('/api/geocode', async (req, res) => {
  const { lon, lat } = req.query;
  const apiKey = process.env.TDT_MAP_KEY; // 从环境变量读取

  const url = `https://api.tianditu.gov.cn/geocoder?postStr={'lon':${lon},'lat':${lat},'ver':1}&type=geocode&tk=${apiKey}`;
  const response = await fetch(url);
  const data = await response.json();

  res.json(data);
});

2. 使用 uniCloud 云函数

// 云函数 getAddress
'use strict';
exports.main = async (event, context) => {
  const { lon, lat } = event;
  const apiKey = 'your-api-key'; // 在云函数中安全存储

  const res = await uniCloud.httpclient.request(
    `https://api.tianditu.gov.cn/geocoder?postStr={'lon':${lon},'lat':${lat},'ver':1}&type=geocode&tk=${apiKey}`,
    { method: 'GET' }
  );

  return res.data;
};

3. 设置域名白名单

在天地图开发者平台设置"域名白名单"，限制只有您的域名可以使用该 Key。

💡 使用示例

完整示例：位置选择页面

<template>
  <view class="page">
    <view class="input-wrapper">
      <input 
        v-model="selectedLocation"
        placeholder="请点击右侧按钮选择位置"
        disabled
      />
      <button @tap="openLocationPicker">定位</button>
    </view>

    <view v-if="locationData">
      <text>经度: {{locationData.lon}}</text>
      <text>纬度: {{locationData.lat}}</text>
      <text>地址: {{locationData.address}}</text>
    </view>

    <!-- 地图选择器 -->
    <siji-tianditu-picker
      ref="mapPicker"
      :map-key="mapKey"
      :center="center"
      :zoom="zoom"
      :on-confirm="handleConfirm"
      :on-cancel="handleCancel">
    </siji-tianditu-picker>
  </view>
</template>

<script>
export default {
  data() {
    return {
      mapKey: '你的天地图API Key',
      selectedLocation: '',
      locationData: null,
      center: [116.411794, 39.9068],
      zoom: 18
    }
  },
  methods: {
    openLocationPicker() {
      this.$refs.mapPicker.show();
    },

    handleConfirm(data) {
      this.locationData = data;
      this.selectedLocation = data.address;

      uni.showToast({
        title: '位置已选择',
        icon: 'success'
      });
    },

    handleCancel() {
      console.log('取消选择');
    }
  }
}
</script>

📝 注意事项

1. API Key 必填：组件需要天地图 API Key 才能正常工作，请前往 天地图开放平台 申请。

2. 坐标系转换：天地图使用 WGS84 坐标系，如果使用其他坐标系需要先转换。

3. 定位权限：使用定位功能需要在 manifest.json 中配置定位权限。

4. 网络请求：地址解析功能需要网络请求，请确保网络畅通。

5. 性能优化：

   • 地图组件较重，建议按需加载
   • 避免在列表中使用多个地图组件
   • 使用 v-if 而不是 v-show 来控制地图显示

🐛 常见问题

Q: 地图不显示？

A: 请检查：

• API Key 是否正确
• 网络是否正常
• 是否给地图容器设置了高度

Q: 定位失败？

A: 请检查：

• 是否配置了定位权限
• 用户是否授权了定位权限
• 设备定位服务是否开启

Q: 地址获取失败？

A: 请检查：

• API Key 是否有效
• 网络请求是否正常
• 坐标是否在中国境内（天地图主要覆盖中国）

📄 License

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📮 联系方式

如有问题或建议，欢迎联系。