d8d-vite-starter/docs/gaode-map-integration-guide.md

高德地图集成指南

概述

本指南说明如何将大屏幕地图从Leaflet替换为高德地图（AMap），实现国内地图展示功能。

主要变更

1. 新增文件

• src/client/big-shadcn/components/ChinaAMap.tsx - 高德地图组件
• src/client/big-shadcn/components/AMapLoader.tsx - 地图加载器
• src/client/big-shadcn/data/chinaCities.ts - 中国城市数据
• src/client/big-shadcn/hooks/useChinaMapData.ts - 中国地图数据Hook
• src/client/big-shadcn/config/mapConfig.ts - 地图配置

2. 修改文件

• src/client/big-shadcn/pages/HomePage.tsx - 替换地图组件

配置步骤

1. 获取高德地图API密钥

1. 访问 高德开放平台
2. 注册账号并创建应用
3. 获取Web端API密钥

2. 配置环境变量

在项目根目录创建或修改 .env 文件：

VITE_GAODE_MAP_KEY=您的高德地图API密钥

3. 使用默认密钥（开发测试）

如果暂时无法获取API密钥，可以使用默认配置测试：

// 在 mapConfig.ts 中修改
export const mapConfig = {
  gaodeApiKey: '您的高德地图API密钥' // 替换为实际密钥
};

功能特性

1. 全国地图展示

• 显示中国主要城市
• 深色主题适配大屏风格
• 3D视图模式

2. 数据可视化

• 城市标记点大小表示数据量
• 颜色渐变表示数据密度
• 点击城市显示详细信息

3. 交互功能

• 鼠标悬停放大效果
• 点击弹出信息窗口
• 缩放和平移操作

4. 实时数据

• 模拟全国银龄岗位和人才数据
• 支持实时刷新
• 省份数据汇总

数据结构

城市数据格式

interface ChinaCityData {
  code: string;      // 城市代码
  name: string;      // 城市名称
  lat: number;       // 纬度
  lng: number;       // 经度
  province: string;  // 所属省份
  dailyNewJobs?: number;     // 每日新增岗位
  totalJobs?: number;        // 累计岗位
  dailyNewTalents?: number;  // 每日新增人才
  totalTalents?: number;     // 累计人才
}

使用示例

基本使用

import ChinaAMap from '../components/ChinaAMap';
import { AMapLoader } from '../components/AMapLoader';

<AMapLoader apiKey={mapConfig.gaodeApiKey}>
  <ChinaAMap data={cities} />
</AMapLoader>

自定义配置

// 修改地图配置
export const mapConfig = {
  gaodeApiKey: '您的密钥',
  defaultCenter: [116.4074, 39.9042], // 北京
  defaultZoom: 6,
  mapStyle: 'amap://styles/darkblue'
};

注意事项

1. API限制

• 高德地图有调用次数限制
• 生产环境建议使用企业版

2. 网络要求

• 需要访问高德地图CDN
• 国内用户访问正常

3. 兼容性

• 支持现代浏览器
• IE11+ 支持

4. 性能优化

• 使用懒加载减少首屏加载时间
• 数据缓存策略避免频繁请求

故障排除

1. 地图不显示

• 检查API密钥是否正确
• 确认网络能访问高德地图
• 查看浏览器控制台错误信息

2. 标记点不显示

• 检查数据格式是否正确
• 确认经纬度在有效范围内
• 验证数据值不为空

3. 样式问题

• 确保CSS没有被覆盖
• 检查容器尺寸是否正确
• 确认z-index层级关系

扩展功能

1. 添加更多城市

在 chinaCities.ts 中添加新的城市数据：

{ code: '440100', name: '广州', lat: 23.1291, lng: 113.2644, province: '广东' }

2. 自定义标记样式

修改 mapConfig.ts 中的标记配置：

markerConfig: {
  minRadius: 5,
  maxRadius: 50,
  colors: {
    high: '#ff0000',
    medium: '#ffff00',
    low: '#00ff00'
  }
}

3. 添加实时数据

使用真实API替换模拟数据：

// 替换 useChinaMapData 中的 queryFn
queryFn: async () => {
  const response = await fetch('/api/china-data');
  return response.json();
}

相关文件

• src/client/big-shadcn/components/ChinaAMap.tsx - 主要地图组件
• src/client/big-shadcn/components/AMapLoader.tsx - 地图加载器
• src/client/big-shadcn/config/mapConfig.ts - 配置管理
• src/client/big-shadcn/data/chinaCities.ts - 城市数据