@dindo-group/cloud-map

由点都科技集团开源，基于天地图的地图选择组件，支持地点搜索、位置标注、逆地理编码等功能的轻量插件。

✨ 特性

• 🗺️ 基于天地图 - 使用中国官方地图服务，数据准确可靠
• 🔍 地点搜索 - 支持 POI 搜索和地址搜索，快速定位目标位置
• 📍 位置标注 - 点击地图即可添加标记，支持拖拽调整
• 🔄 逆地理编码 - 根据坐标自动获取详细地址信息
• 🎨 Vue 组件 - 开箱即用的 Vue 组件，支持 Vue 2.x 和 Vue 3.x
• 📦 内置 Leaflet - Leaflet 已内置，无需额外安装依赖
• 🎯 灵活配置 - 支持只读模式、禁用模式等多种配置选项
• 📱 响应式设计 - 适配各种屏幕尺寸

📦 安装

npm install @dindo-group/cloud-map

🔧 依赖要求

本组件需要以下依赖：

• Vue: ^2.6.0 或 ^3.0.0
• Element UI (可选): 如果使用搜索功能，需要 Element UI 的 el-autocomplete 和 el-input 组件

💡 提示: Leaflet 已内置在包中，无需单独安装。

🚀 快速开始

全局注册

import Vue from 'vue';
import CloudMap from '@dindo-group/cloud-map';

Vue.use(CloudMap);

局部注册

<template>
  <div>
    <tianditu-map
      :visible="true"
      :initial-position="[116.37304, 39.92594]"
      :show-search="true"
      :tk="yourTiandituKey"
      @location-change="handleLocationChange"
      @address-change="handleAddressChange"
    />
  </div>
</template>

<script>
import { TiandituMap } from '@dindo-group/cloud-map';

export default {
  components: {
    TiandituMap,
  },
  data() {
    return {
      yourTiandituKey: 'your-tianditu-key',
    };
  },
  methods: {
    handleLocationChange(location) {
      console.log('位置变化:', location);
      // location: { lng, lat, address }
    },
    handleAddressChange(address) {
      console.log('地址变化:', address);
    },
  },
};
</script>

📸 预览

📖 API 文档

Props

| 参数 | 说明 | 类型 | 默认值 | 必填 | |------|------|------|--------|------| | visible | 是否显示组件 | Boolean | true | 否 | | initialPosition | 初始经纬度 [lng, lat] | Array | [116.37304, 39.92594] | 否 | | showSearch | 是否显示搜索框 | Boolean | true | 否 | | readonly | 是否只读模式（纯标注展示，去除手动标注和搜索） | Boolean | false | 否 | | disabled | 是否禁用（禁用时不能点击标注） | Boolean | false | 否 | | height | 地图高度 | String | '400px' | 否 | | tk | 天地图密钥 | String | 'XXXXX' | 是 | | addressValue | 地址输入框的值（用于双向绑定） | String | '' | 否 | | initGeocode | 是否初始化时进行逆地理编码和标记 | Boolean | false | 否 |

Events

| 事件名 | 说明 | 回调参数 | 示例 | |--------|------|----------|------| | location-change | 位置变化时触发（点击地图或选择搜索结果） | { lng, lat, address } | { lng: 116.37304, lat: 39.92594, address: '北京市...' } | | address-change | 地址变化时触发（逆地理编码或手动输入） | address (String) | '北京市朝阳区...' |

Methods

通过 ref 调用组件方法：

<template>
  <tianditu-map ref="map" :tk="tiandituKey" />
</template>

<script>
export default {
  data() {
    return {
      tiandituKey: 'your-tianditu-key',
    };
  },
  methods: {
    // 获取当前选中的位置
    getLocation() {
      const location = this.$refs.map.getLocation();
      console.log(location); 
      // 返回: { lng: 116.37304, lat: 39.92594, address: '北京市...' }
      // 如果没有选中位置，返回 null
    },
    
    // 设置位置（移动到指定坐标并添加标记）
    setLocation(lng, lat) {
      this.$refs.map.setLocation(lng, lat);
    },
    
    // 根据区域名称移动地图（不添加标记）
    moveToRegion(regionName) {
      this.$refs.map.moveToRegion('北京市');
      // 或 this.$refs.map.moveToRegion('上海市黄浦区');
    },
    
    // 逆地理编码（根据坐标获取地址）
    // 注意：地址会通过 @address-change 事件返回
    getAddress(lng, lat) {
      this.$refs.map.getAddress(lng, lat);
      // 地址会通过 @address-change 事件触发
    }
  },
};
</script>

💡 使用示例

基础用法

<template>
  <div class="map-wrapper">
    <tianditu-map
      :tk="tiandituKey"
      :height="'500px'"
      @location-change="onLocationChange"
    />
  </div>
</template>

<script>
import { TiandituMap } from '@dindo-group/cloud-map';

export default {
  components: { TiandituMap },
  data() {
    return {
      tiandituKey: 'your-tianditu-key',
    };
  },
  methods: {
    onLocationChange(location) {
      console.log('选中位置:', location);
      // 可以在这里保存位置信息
    },
  },
};
</script>

只读模式（仅展示）

<template>
  <tianditu-map
    :tk="tiandituKey"
    :readonly="true"
    :initial-position="[116.37304, 39.92594]"
    :show-search="false"
  />
</template>

双向绑定地址

<template>
  <div>
    <tianditu-map
      :tk="tiandituKey"
      v-model:address-value="selectedAddress"
      @location-change="onLocationChange"
    />
    <p>当前地址：{{ selectedAddress }}</p>
  </div>
</template>

<script>
import { TiandituMap } from '@dindo-group/cloud-map';

export default {
  components: { TiandituMap },
  data() {
    return {
      tiandituKey: 'your-tianditu-key',
      selectedAddress: '',
    };
  },
  methods: {
    onLocationChange(location) {
      this.selectedAddress = location.address;
    },
  },
};
</script>

初始化时进行逆地理编码

<template>
  <tianditu-map
    :tk="tiandituKey"
    :initial-position="[116.37304, 39.92594]"
    :init-geocode="true"
    @address-change="onAddressChange"
  />
</template>

<script>
export default {
  methods: {
    onAddressChange(address) {
      console.log('初始地址:', address);
    },
  },
};
</script>

🔑 获取天地图密钥

1. 访问 天地图开放平台
2. 注册账号并登录
3. 进入"控制台" → "应用管理"
4. 创建新应用，获取 API Key (tk)
5. 将获取的密钥配置到组件的 tk 属性中

⚠️ 重要: 天地图密钥是必需的，没有有效的密钥将无法加载地图。

⚠️ 注意事项

1. 天地图密钥: 本组件使用天地图服务，需要有效的天地图密钥才能正常使用
2. Leaflet 内置: Leaflet 已内置在包中，无需单独安装或引入 CSS
3. Element UI: 搜索功能依赖 Element UI，如果项目中没有 Element UI，需要自行安装或修改搜索框实现
4. 坐标系: 地图使用 GCJ-02 坐标系（火星坐标系），这是中国官方标准坐标系
5. 浏览器兼容性: 支持现代浏览器（Chrome、Firefox、Safari、Edge 等）

📝 更新日志

1.0.0

• ✨ 初始版本发布
• 🗺️ 支持天地图底图加载
• 🔍 支持地点搜索功能
• 📍 支持位置标注和拖拽
• 🔄 支持逆地理编码
• 📦 内置 Leaflet，无需额外安装

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 License

MIT

👥 作者

点都科技集团有限公司