# jl1Map

**Repository Path**: zd_g/jl1-map

## Basic Information

- **Project Name**: jl1Map
- **Description**: 基于 **吉林一号（JL1）空间数据 SDK v1.0** 构建的遥感数据服务平台前端。以 Vue 3 + TypeScript + Vite + Element Plus 实现全屏地图应用，地图能力（底图切换、图层管理、绘制量测、卷帘分屏、矢量分析、热力聚合等）全部由 SDK 提供，前端通过组合式函数（Composable）对 SDK 进行响应式封装与生命周期管理。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 2
- **Created**: 2026-08-07
- **Last Updated**: 2026-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 吉林一号, 遥感, webgis, SDK

## README

# 遥感数据服务平台（jl1map-vue）

基于 **吉林一号（JL1）空间数据 SDK v1.0** 构建的遥感数据服务平台前端。以 Vue 3 + TypeScript + Vite + Element Plus 实现全屏地图应用，地图能力（底图切换、图层管理、绘制量测、卷帘分屏、矢量分析、热力聚合等）全部由 SDK 提供，前端通过组合式函数（Composable）对 SDK 进行响应式封装与生命周期管理。

![2](img/2.png)

![3](img/3.png)

## 技术栈


| 类别 | 技术                                                                  |
| ---- | --------------------------------------------------------------------- |
| 框架 | Vue 3（`<script setup>`）+ TypeScript                                 |
| 构建 | Vite 6 + vue-tsc                                                      |
| UI   | Element Plus 2 + @element-plus/icons-vue                              |
| 地图 | 吉林一号空间数据 SDK（`src/lib/jl1map.js`，含类型声明 `jl1map.d.ts`） |
| 底图 | 天地图（影像/矢量）                                                   |

## 功能特性

- **全屏地图**：SDK 自带全部工具栏（图层管理、量测、截屏、卷帘、分屏、图例、切片影像套件、影像时间轴、矢量切片、矢量合并/简化/缓冲区）
- **底图切换**：天地图影像 / 天地图矢量 / 自定义底图，支持注记显隐
- **图层管理**：添加、显隐、透明度、层级调整、删除，URL 支持 `{z}/{x}/{y}` 占位符及 `${token}` 自动替换
- **绘制与量测**：矩形/圆形/多边形/线绘制、指定面积快速绘制、面积/长度量测
- **对比工具**：卷帘（方向可切换）、二分屏、四分屏
- **矢量数据**：GeoJSON / WKT / KML / KMZ 展示，shp 下载，合并、简化、缓冲区分析
- **专题图层**：热力图、聚合图（内置演示点数据）
- **状态提示**：地图初始化状态徽标（未初始化 / 运行中 / Token 无效），Token 失效时给出明确错误提示

## 环境要求

- Node.js ≥ 18（建议 20+）
- npm ≥ 9

## 快速开始

```bash
# 1. 安装依赖
npm install

# 2. 配置环境变量（复制模板并填写真实凭证）
cp .env.example .env
#   - VITE_JL1_TOKEN：吉林一号空间数据 SDK Token（必填，需向 SDK 服务方申请）
#   - VITE_TDT_TOKEN：天地图 Key（默认底图使用，需在天地图官网申请）
#   修改 .env 后需重启 dev server 生效

# 3. 启动开发服务（默认 http://localhost:5173）
npm run dev
```

> 注意：SDK 初始化时会向服务端校验 Token，若 Token 无效或网络异常，地图视图将无法加载，页面左下角会显示「Token 无效/未加载」红色徽标，并在控制台给出提示。

## 目录结构

```
jl1map-vue/
├── public/
│   └── doc/                  # 《空间数据SDKv1.0使用说明.pdf》
├── src/
│   ├── components/
│   │   └── MapContainer.vue  # 地图容器：挂载 SDK 地图实例（id 为 JL1Map）
│   ├── composables/
│   │   └── useMap.ts         # 核心封装：SDK 全部能力的响应式服务（MapService 单例）
│   ├── config/
│   │   └── mapConfig.ts      # 默认地图配置（中心点、缩放、图层、图例、工具栏等）
│   ├── lib/
│   │   ├── jl1map.js         # 吉林一号空间数据 SDK（第三方）
│   │   └── jl1map.d.ts       # SDK TypeScript 类型声明
│   ├── styles/
│   │   └── index.css         # 全局样式
│   ├── views/
│   │   └── MapPage.vue       # 主页面：全屏地图 + 顶部标题栏 + 地图状态徽标
│   ├── App.vue
│   └── main.ts               # 入口：注册 Element Plus（中文语言包）与全局图标
├── .env                      # 本地环境变量（含凭证，已被 git 忽略）
├── .env.example              # 环境变量模板
└── vite.config.ts            # Vite 配置（@ 别名、SDK 与 Element Plus 分包）
```

## 核心设计

### 地图服务（useMap）

`src/composables/useMap.ts` 导出全局单例 `MapService`，以组合式函数 `useMap()` 对外暴露，封装了 SDK 全部接口：

- **生命周期**：`init()` / `destroy()`；初始化后延迟 5s 检测地图视图是否真正渲染，未渲染则置为错误状态
- **分组能力**：底图管理、图层管理、绘制量测、对比工具（卷帘/分屏）、矢量数据、快捷工具（截屏/全屏/定位/缩放）、图例、演示数据
- **Token 替换**：图层 URL 中 `${token}` 占位符在初始化时自动替换为实际 Token

```ts
import { useMap } from '@/composables/useMap'

const { service, isReady, error } = useMap()
service.init(service.options, 'JL1Map') // 初始化地图
service.addNormalLayer({ title: '新图层', url: '...', visible: true })
```

### 默认配置（mapConfig）

`src/config/mapConfig.ts` 中的 `buildDefaultOptions()` 生成地图初始化配置，可通过环境变量覆盖：


| 配置项            | 说明                                                                                    |
| ----------------- | --------------------------------------------------------------------------------------- |
| `center` / `zoom` | 初始中心点（默认 [108.29883, 35.72902]）与缩放级别                                      |
| `layerData`       | 默认影像图层（吉林一号切片服务）                                                        |
| `compareGroup`    | 对比图层组（卷帘/分屏/影像时间轴用，内置 4 期示例影像）                                 |
| `useTool`         | 工具栏工具项（图层/量测/截屏/卷帘/分屏/图例/切片套件/时间轴/矢量切片/合并/简化/缓冲区） |
| `legendData`      | 默认图例数据（色卡式）                                                                  |

### 构建优化

`vite.config.ts` 通过 `manualChunks` 将 SDK 与 Element Plus 独立分包，避免单包体积过大：

```bash
npm run build    # 类型检查 + 生产构建，产物输出至 dist/
npm run preview  # 本地预览生产构建
```

## 环境变量


| 变量             | 必填 | 说明                                     |
| ---------------- | ---- | ---------------------------------------- |
| `VITE_JL1_TOKEN` | 是   | 吉林一号空间数据 SDK Token（申请后填入） |
| `VITE_TDT_TOKEN` | 是   | 天地图 Key（默认底图图源）               |

`.env` 已被 git 忽略（见 `.gitignore`），提交时请勿包含真实凭证。

## 参考文档

- [《空间数据SDKv1.0使用说明.pdf》](public/doc/空间数据SDKv1.0使用说明.pdf)：SDK 完整 API 说明（图例、图层、卷帘、分屏、矢量等）