# map-serve

**Repository Path**: hfuuwy/map-serve

## Basic Information

- **Project Name**: map-serve
- **Description**: 腾讯地图+threejs+vr+3d建模+日照模拟练习项目
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-16
- **Last Updated**: 2026-01-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

根据项目结构和代码地图，该项目是一个基于 Vue 3、TypeScript 和 Vite 的地图服务应用，主要功能是集成腾讯地图 API 并提供地图显示、操作和事件处理等功能。以下是该项目的 README 内容：

---

# 地图服务应用

一个基于 Vue 3、TypeScript 和 Vite 构建的地图服务应用，集成了腾讯地图 API。

## 功能特性

- 集成腾讯地图 API，支持地图显示、缩放、平移等基础操作
- 基于 Vue 3 组合式 API 和 TypeScript 开发
- 使用 Vite 作为构建工具，提供快速的开发体验
- 支持环境变量配置，方便切换不同环境的 API 密钥

## 快速开始

### 环境要求

- Node.js >= 20.0.0
- npm >= 9.0.0

### 安装依赖

```bash
npm install
```

### 配置环境变量

创建或修改 `.env` 文件，配置以下环境变量：

```env
# 腾讯地图 API 密钥
VITE_TENCENT_MAP_KEY=YOUR_MAP_KEY_HERE

# 开发服务器配置
VITE_DEV_PORT=8089

# 应用名称
VITE_APP_NAME=地图服务应用

# API 基础 URL
VITE_API_BASE_URL=http://localhost:3000/api
```

> 注意：你需要替换 `YOUR_MAP_KEY_HERE` 为你自己的腾讯地图 API 密钥。如果没有密钥，可以在[腾讯地图开放平台](https://lbs.qq.com/)申请。

### 开发模式

```bash
npm run dev
```

应用将在 `http://localhost:8089` 启动。

### 构建生产版本

```bash
npm run build
```

构建后的文件将生成在 `dist` 目录中。

### 预览生产版本

```bash
npm run preview
```

## 地图组件使用说明

### 组件引入

```vue
<script setup lang="ts">
import { ref, onMounted } from 'vue';
import Map from '@/components/Map.vue';

const mapRef = ref<InstanceType<typeof Map> | null>(null);

onMounted(() => {
  // 获取地图实例
  const mapInstance = mapRef.value?.getMapInstance();
  if (mapInstance) {
    // 可以在这里对地图实例进行操作
    console.log('地图实例已初始化', mapInstance);
  }
});
</script>

<template>
  <div class="app-container">
    <Map ref="mapRef" :options="{
      center: [116.397428, 39.90923], // 北京坐标
      zoom: 12,
      mapStyleId: 'style1'
    }" />
  </div>
</template>

<style scoped>
.app-container {
  width: 100vw;
  height: 100vh;
}
</style>
```

### Props 说明

| 属性名 | 类型 | 默认值 | 说明 |
|-------|------|-------|------|
| options | Object | `{ center: [113.27, 23.13], zoom: 12, mapStyleId: 'style1' }` | 地图初始化配置选项 |
| options.center | [number, number] | `[113.27, 23.13]` (广州坐标) | 地图中心点坐标，格式为 [经度, 纬度] |
| options.zoom | number | `12` | 地图缩放级别 |
| options.mapStyleId | string | `'style1'` | 地图样式 ID |

### 暴露的方法

| 方法名 | 返回类型 | 说明 |
|-------|---------|------|
| getMapInstance | TMapInstance \| null | 获取地图实例，可以用于进行更多的地图操作 |

## 项目结构

```
├── src/
│   ├── components/       # Vue 组件
│   │   └── Map.vue       # 地图组件
│   ├── types/            # TypeScript 类型定义
│   │   └── tmap.d.ts     # 腾讯地图 API 类型声明
│   ├── unils/            # 工具函数
│   │   └── index.ts      # 地图加载器等工具函数
│   ├── App.vue           # 应用入口组件
│   ├── main.ts           # 应用入口文件
│   └── style.css         # 全局样式
├── .env                  # 环境变量配置
├── vite.config.ts        # Vite 配置
└── package.json          # 项目依赖和脚本
```

## 腾讯地图 API 加载器

项目提供了一个 `TMapLoader` 函数，用于动态加载腾讯地图 API：

```typescript
import { TMapLoader } from '@/unils/index';

// 加载地图 API
const TMap = await TMapLoader('YOUR_MAP_KEY_HERE');

// 创建地图实例
const map = new TMap.Map('map-container', {
  center: new TMap.LatLng(39.90923, 116.397428),
  zoom: 12
});
```

## 注意事项

1. 确保你有有效的腾讯地图 API 密钥，并且已经在 `.env` 文件中正确配置
2. 地图组件需要一个有明确宽高的容器来显示地图
3. 开发时，请确保网络连接正常，以便能够加载腾讯地图 API
4. 在生产环境中，建议使用 CDN 加速地图 API 的加载

## 常见问题

### Q: 地图不显示怎么办？

**A:** 检查以下几点：
1. 确保你有有效的腾讯地图 API 密钥
2. 检查地图容器是否有明确的宽高
3. 检查浏览器控制台是否有错误信息

### Q: 如何获取地图点击事件？

**A:** 可以通过获取地图实例来添加事件监听：

```typescript
const mapInstance = mapRef.value?.getMapInstance();
if (mapInstance) {
  mapInstance.on('click', (evt) => {
    const { lat, lng } = evt.latLng;
    console.log('点击位置:', { lng, lat });
  });
}
```

## License

MIT