atchain-mapbox-vue/QUICK_START.md

A Vue 3 MapBox component library with subway lines, stations, markers and polygons support. Zero dependencies except Vue 3 and Mapbox GL JS.

# 🚀 MapBox 组件库 - 快速开始

## 1️⃣ 复制文件

将整个 `mapbox` 文件夹复制到你的项目中：

```
src/components/mapbox/  # 复制整个文件夹
```

## 2️⃣ 安装依赖

```bash
npm install atchain-mapbox-vue mapbox-gl
```

## 3️⃣ 基础使用

```vue
<template>
  <div class="w-full h-screen">
    <MapBox 
      token="你的-mapbox-token"
      :center="[121.431502, 31.214212]"
      :zoom="14"
      json-path="/data/landmark.geojson"
    >
      <!-- 标记点 -->
      <MapBoxMarker 
        id="marker-1"
        src="/images/marker.png"
        json-path="/data/landmark.geojson"
        width="50px"
        height="50px"
      />
      
      <!-- 多边形 -->
      <MapBoxPolygon 
        id="polygon-1" 
        json-path="/data/landmark.geojson"
      />
    </MapBox>
  </div>
</template>

<script setup lang="ts">
import { 
  MapBox, 
  MapBoxMarker, 
  MapBoxPolygon 
} from 'atchain-mapbox-vue'
</script>
```

## 4️⃣ 准备数据文件

创建 `public/data/landmark.geojson`：

```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "marker-1",
      "properties": { "point": "我的标记" },
      "geometry": {
        "type": "Point",
        "coordinates": [121.431502, 31.214212]
      }
    },
    {
      "type": "Feature", 
      "id": "polygon-1",
      "properties": { "polygon": "我的区域" },
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[121.43, 31.21], [121.44, 31.21], [121.44, 31.22], [121.43, 31.22], [121.43, 31.21]]]
      }
    }
  ]
}
```

## 5️⃣ 自定义数据路径 (可选)

每个组件都可以使用不同的数据文件：

```vue
<!-- 使用不同的数据文件 -->
<MapBoxMarker 
  id="poi-1"
  src="/images/poi.png"
  json-path="/data/points-of-interest.geojson"
/>

<MapBoxPolygon 
  id="area-1"
  json-path="/data/areas.geojson"
/>
```

**注意**: 如果不指定 `json-path`，组件会使用默认路径 `./data/landmark.geojson`

## 6️⃣ 获取 Mapbox Token

1. 访问 [Mapbox 官网](https://www.mapbox.com/)
2. 注册账号并创建访问令牌
3. 将令牌替换到代码中

## ✅ 完成！

现在你应该能看到：
- 🗺️ 一个完整的地图
- 📍 一个可点击的标记点
- 🔷 一个可交互的多边形区域

## 🎯 下一步

- 查看 [完整文档](./README.md) 了解更多功能
- 添加地铁线路和站点显示
- 自定义样式和交互效果

## 🆘 遇到问题？

1. **地图不显示**: 检查 token 和容器尺寸
2. **标记不显示**: 检查 GeoJSON 格式和 id 匹配
3. **控制台错误**: 检查文件路径和依赖安装
4. **组件不显示**: 检查控制台警告，可能是 ID 在数据文件中不存在
5. **站点半径无效**: 确保使用了最新版本 (1.0.3+)

### 常见警告信息

```
MapBoxMarker: 未找到 ID 为 xxx 的点要素，组件将不显示
```
**解决**: 检查数据文件中是否存在对应 ID 的点要素

```
MapBoxPolygon: 未找到 ID 为 xxx 的多边形要素，组件将不显示  
```
**解决**: 检查数据文件中是否存在对应 ID 的多边形要素

更多帮助请查看 [完整文档](./README.md) 的故障排除部分。