KML 文件解析与 GeoJSON 转换完全指南

KML（Keyhole Markup Language）是 Google Earth 使用的基于 XML 的地理数据标记语言。它最初由 Keyhole 公司开发，后被 Google 收购并成为 OGC 国际标准。KML 不仅可以描述地理要素的几何形状，还能携带丰富的样式、描述和元数据信息，在地理信息可视化领域应用广泛。

KML 文件结构

KML 基于 XML 语法，根元素为 <kml>，其内部通常包含一个 <Document> 或 <Folder> 作为容器。一个典型的 KML 文件结构如下：

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <Folder>
      <Placemark>
        <name>示例点</name>
        <description>这是一个示例</description>
        <Point>
          <coordinates>116.40,39.90,0</coordinates>
        </Point>
      </Placemark>
    </Folder>
  </Document>
</kml>

核心要素：Placemark

<Placemark> 是 KML 中最核心的要素单元，每个 Placemark 代表一个地理要素。它通常包含以下内容：

name：要素名称
description：要素描述，支持 HTML 内容
styleUrl：引用的样式定义
geometry：几何信息，如 Point、LineString、Polygon 等

几何类型

KML 支持多种几何类型，与 GeoJSON 基本可以一一对应：

Point —— 对应 GeoJSON 的 Point
LineString —— 对应 GeoJSON 的 LineString
Polygon —— 对应 GeoJSON 的 Polygon
MultiGeometry —— 对应 GeoJSON 的 MultiPoint、MultiLineString 或 MultiPolygon

需要注意的是，KML 中的坐标格式为 经度,纬度,高程，三者以逗号分隔，而 GeoJSON 的坐标为 [经度, 纬度] 数组形式，转换时需做格式调整。

转换原理

KML 转 GeoJSON 的核心流程如下：

使用 DOMParser 将 KML 字符串解析为 XML DOM 树
遍历 DOM 树，提取所有 <Placemark> 节点
解析每个 Placemark 的几何类型和坐标数据
将 name、description 等子元素转为 Feature 的 properties
组装为 GeoJSON FeatureCollection 输出

const parser = new DOMParser();
const dom = parser.parseFromString(kmlString, 'text/xml');
// 遍历 Placemark 节点并转换为 GeoJSON Feature

使用 @tmcw/togeojson 库

手动实现 KML 解析较为繁琐，推荐使用 @tmcw/togeojson 库。这是一个轻量级、无依赖的库，专门用于将 KML 和 GPX 转换为 GeoJSON：

import { kml } from '@tmcw/togeojson';
import { DOMParser } from 'xmldom';

const dom = new DOMParser().parseFromString(kmlString, 'text/xml');
const geojson = kml(dom);

该库会自动处理几何类型映射、坐标格式转换和属性提取，开发者无需关心底层 XML 解析细节。

属性保留

转换过程中，Placemark 的非几何子元素会被保留到 GeoJSON Feature 的 properties 中。常见的保留字段包括：

name —— 要素名称
description —— 描述信息
styleUrl —— 样式引用路径
ExtendedData —— 扩展自定义数据

常见问题

样式信息丢失：KML 的 <Style> 定义了颜色、图标、线宽等样式，而 GeoJSON 本身不含样式信息。转换后样式会丢失，需在前端渲染时单独处理。
网络链接（NetworkLink）：<NetworkLink> 用于引用外部 KML 资源，转换时无法自动加载远程内容，需手动获取后再合并。
地面叠加层（GroundOverlay）：<GroundOverlay> 表示叠加在地图上的图像，并非矢量几何，转 GeoJSON 时通常被忽略。
文件夹层级：KML 的 <Folder> 嵌套结构在 GeoJSON 中以扁平的 Feature 数组呈现，层级关系会以属性形式保留。

转换工具

如果你需要将 KML 文件快速转换为 GeoJSON，可以使用 KML 转 GeoJSON 工具，上传文件后即可在浏览器端完成转换，数据不会上传到服务器，安全可靠。