KML 查看器

工具背景

KML（Keyhole Markup Language）是 Google Earth 使用的矢量地理数据格式，广泛应用于地图标注、轨迹记录、区域划分等场景。在日常工作中，我们经常收到他人分享的 KML 文件，需要快速在地图上查看其内容。

工具定位

KML 查看器是一个轻量级地图浏览工具，专注于"查看"而非"编辑"。你可以将任何 KML 文件拖入页面，立即看到文件中的点、线、面要素在地图上的分布。

核心价值

• 即拖即看：无需安装任何软件，浏览器中拖入 KML 文件即可查看
• 多底图切换：支持天地图、高德、Google、OSM 等多种底图，方便在不同地图风格下对比查看
• 图层管理：支持同时加载多个 KML 文件，独立控制每个图层的显示与隐藏

使用方法

加载 KML 文件

有两种方式加载 KML 文件：

方式一：拖拽上传

直接将 KML 文件（.kml）拖入左侧面板的虚线区域，松开即可加载。

方式二：点击选择

点击虚线区域内的"选择文件"按钮，在文件选择器中选择一个或多个 KML 文件。

切换底图

在左侧面板的"地图底图"下拉框中，选择你需要的地图底图：

底图	说明
OpenStreetMap	国际通用的开源地图
高德地图	国内常用的道路地图
高德卫星图	高德卫星影像
Google 地图	Google 道路地图
Google 卫星图	Google 卫星影像
腾讯地图	腾讯道路地图

注：天地图需要申请 API Key 才能使用。

图层管理

每个加载的 KML 文件会作为一个独立图层显示在左侧面板中：

• 显示/隐藏：点击图层名称旁的眼睛图标切换显示状态
• 删除图层：点击删除按钮移除该图层
• 图层命名：图层默认使用文件名作为名称

查看要素信息

在地图上点击任意 KML 要素（点标记、线段、多边形），会弹出信息窗口显示该要素的名称和描述信息。

术

核心依赖

leaflet

• 用途：轻量级开源地图引擎，提供瓦片加载、图层管理、交互控制
• 官网：https://leafletjs.com/
• 版本：^1.9.4

地图底图配置

底图切换通过 Leaflet 的 TileLayer 实现，各底图采用标准的 WMTS/TMS 瓦片协议：

• OpenStreetMap：标准 OSM 瓦片，坐标系 EPSG:3857
• 高德地图：GCJ-02 坐标系，无需 API Key
• Google 地图：WGS-84/GCJ-02（国内），无需 API Key
• 腾讯地图：GCJ-02 坐标系，无需 API Key

瓦片地址配置在 tileProviders.ts 中集中管理：

// tileProviders.ts — 统一的底图 TileLayer 工厂函数
export function createTileLayer(provider: TileProvider): L.TileLayer {
  return L.tileLayer(provider.url, { attribution: provider.attribution })
}

KML 解析流程

KML 文件使用浏览器原生 DOMParser 手动解析，不依赖第三方 KML 解析库：

用户拖拽/选择 KML 文件
    ↓
FileReader 读取文件为文本
    ↓
DOMParser 解析 XML → DOM 树
    ↓
parseKmlStyles() 提取 <Style> 元素，建立 styleId → 颜色映射
    ↓
parseKmlNode() 递归遍历 DOM：解析 Folder / Placemark / Point / LineString / Polygon
    ↓
构建树形数据结构（KmlTreeNode），每条节点包含名称、几何类型、坐标数组、颜色
    ↓
Leaflet GeoJSON Layer 渲染到地图，自适应视野（fitBounds）

样式解析

// 解析 KML 中的 <Style> 定义
function parseKmlStyles(xmlDoc: Document): Map<string, string> {
  const styles = new Map<string, string>()
  // 遍历 Style 元素，提取 IconStyle/LineStyle/PolyStyle 的颜色
  // 通过 parseKmlColorEl() 解析 ABGR 格式颜色值并转换为 #RRGGBB
}

节点递归解析

// 递归解析 KML DOM 节点树
function parseKmlNode(xmlEl: Element, parent: KmlTreeNodeData, styles: Map<string, string>) {
  // 根据标签名分发：Folder → 递归子节点
  //                Placemark → 提取名称、几何、样式
  //                Point / LineString / Polygon → 解析坐标串
}

坐标系说明

大部分在线底图使用 GCJ-02 坐标系（火星坐标），KML 文件通常使用 WGS-84 坐标系。加载到国内底图时可能存在数百米的偏移。可在后续版本中集成坐标转换模块进行自动纠偏。

图层树与拖拽

KML 文件结构以可交互的树形组件呈现，每个节点对应 KML 中的 Folder 或 Placemark。支持复选框控制图层显隐，Leaflet LayerGroup 管理多图层，操作复杂度为 O(1)。

性能考虑

• KML 解析为一次性操作（FileReader + DOMParser），解析完成后不重复执行
• 单个 KML 文件即使包含数千个要素，在 Leaflet 中仍能流畅浏览
• 图层的显隐切换通过 Leaflet 的 addLayer/removeLayer 方法，无需重新解析