kml-to-geojson

一个简单、轻量的 JavaScript / TypeScript 工具库，用于将 KML、GPX、OVKML（奥维 KML）或 OVJSN（奥维 JSON）文件转换为 GeoJSON 格式。

支持以下特性：

• 支持 KML 格式 - Point, LineString, Polygon, MultiGeometry, Track 等
• 支持 GPX 格式 - Track, Route, Waypoint 等
• 支持 OVKML 格式 - OpenVector KML 格式（奥维 KML）
• 支持 OVJSN 格式 - OpenVector JSON 格式（奥维 JSON），包括标准 GeoJSON 和特殊层级格式
• 支持本地文件和网络 URL - 可直接传入 Document 对象或 HTTP(S) URL
• 保留样式和属性信息 - name, address, description, styleUrl 等
• KML 颜色转换 - 自动将 KML 的 AABBGGRR 颜色格式转换为 RGBA
• 异步处理 - 支持 Promise，方便现代 JavaScript 开发
• Tree Shaking 友好 - 支持按需引入

在线示例

我们提供了一个功能完整的在线演示页面，您可以直接在浏览器中体验所有功能：

🌐 立即体验： 点击访问在线演示

在线示例支持：

• ✨ KML、GPX、OVKML、OVJSN 格式转换
• 📁 本地文件上传
• 🌐 URL 地址加载
• 💾 结果下载和复制

安装

你可以通过 npm 或 pnpm 安装该库：

pnpm install @giszhc/kml-to-geojson
# 或
npm install @giszhc/kml-to-geojson

API

kmlToGeoJSON(input: Document | string): Promise

将 KML 文档或 URL 转换为 GeoJSON FeatureCollection

参数：

• input - 可以是：
  • DOM Document 对象
  • KML 文件的 URL 字符串（以 http:// 或 https:// 开头）
  • KML 文件内容的字符串

返回：

• Promise<FeatureCollection> - GeoJSON FeatureCollection 对象

输出示例：

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [120.5, 30.2]
      },
      "properties": {
        "name": "示例地点",
        "address": "测试地址",
        "description": "描述信息"
      }
    }
  ]
}

示例：

import { kmlToGeoJSON } from '@giszhc/kml-to-geojson';

// 方式 1：从本地文件读取
const fileInput = document.getElementById('file');
const file = fileInput.files[0];
const text = await file.text();
const geojson = await kmlToGeoJSON(text);
console.log(geojson); // FeatureCollection

import { kmlToGeoJSON } from '@giszhc/kml-to-geojson';

// 方式 2：从网络 URL 加载
const geojson = await kmlToGeoJSON('https://example.com/data.kml');
console.log(geojson); // FeatureCollection

import { kmlToGeoJSON } from '@giszhc/kml-to-geojson';

// 方式 3：直接传入 XML 字符串
const kmlContent = `
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <Placemark>
      <Point>
        <coordinates>120.5,30.2</coordinates>
      </Point>
    </Placemark>
  </Document>
</kml>
`;
const geojson = await kmlToGeoJSON(kmlContent);
console.log(geojson); // FeatureCollection

gpxToGeoJSON(input: Document | string): Promise

将 GPX 文档或 URL 转换为 GeoJSON FeatureCollection

参数：

• input - 可以是：
  • DOM Document 对象
  • GPX 文件的 URL 字符串（以 http:// 或 https:// 开头）
  • GPX 文件内容的字符串

返回：

• Promise<FeatureCollection> - GeoJSON FeatureCollection 对象

示例：

import { gpxToGeoJSON } from '@giszhc/kml-to-geojson';

// 方式 1：从本地文件读取
const fileInput = document.getElementById('file');
const file = fileInput.files[0];
const text = await file.text();
const geojson = await gpxToGeoJSON(text);
console.log(geojson); // FeatureCollection

import { gpxToGeoJSON } from '@giszhc/kml-to-geojson';

// 方式 2：从网络 URL 加载
const geojson = await gpxToGeoJSON('https://example.com/track.gpx');
console.log(geojson); // FeatureCollection

import { gpxToGeoJSON } from '@giszhc/kml-to-geojson';

// 方式 3：直接传入 XML 字符串
const gpxContent = `
<?xml version="1.0" encoding="UTF-8"?>
<gpx version="1.1" creator="Example">
  <trk>
    <name>轨迹</name>
    <trkseg>
      <trkpt lat="30.1" lon="120.2"></trkpt>
      <trkpt lat="30.2" lon="120.3"></trkpt>
    </trkseg>
  </trk>
</gpx>
`;
const geojson = await gpxToGeoJSON(gpxContent);
console.log(geojson); // FeatureCollection

ovjsnToGeoJSON(input: FeatureCollection | Record<string, any> | string): Promise

将 OVJSN 文档或 URL 转换为 GeoJSON FeatureCollection。支持两种格式：

• 标准 GeoJSON 格式 - 直接返回 FeatureCollection
• OVJSN 特有格式 - 包含 Version, Type, ObjItems 等字段的层级结构数据（奥维 JSON 特有格式）

参数：

• input - 可以是：
  • GeoJSON FeatureCollection 对象
  • OVJSN 对象（包含 Version, Type, ObjItems 等字段的奥维 JSON 对象）
  • OVJSN 文件的 URL 字符串（以 http:// 或 https:// 开头）
  • OVJSN 文件内容的字符串

返回：

• Promise<FeatureCollection> - GeoJSON FeatureCollection 对象

示例：

import { ovjsnToGeoJSON } from '@giszhc/kml-to-geojson';

// 方式 1：从本地文件读取（标准 GeoJSON 格式）
const fileInput = document.getElementById('file');
const file = fileInput.files[0];
const text = await file.text();
const geojson = await ovjsnToGeoJSON(text);
console.log(geojson); // FeatureCollection

import { ovjsnToGeoJSON } from '@giszhc/kml-to-geojson';

// 方式 2：从网络 URL 加载
const geojson = await ovjsnToGeoJSON('https://example.com/data.ovjsn');
console.log(geojson); // FeatureCollection

import { ovjsnToGeoJSON } from '@giszhc/kml-to-geojson';

// 方式 3：OVJSN 特有格式（奥维 JSON 层级结构）
const ovjsnData = {
  "Version": "V10.1.6",
  "Type": 1,
  "ObjItems": [
    {
      "Type": 30,
      "Object": {
        "Name": "分组名称",
        "ObjectDetail": {
          "ObjChildren": [
            {
              "Type": 7,
              "Object": {
                "Name": "名称",
                "ObjectDetail": {
                  "Lat": 31.4048,
                  "Lng": 120.8616
                }
              }
            }
          ]
        }
      }
    }
  ]
};
const geojson = await ovjsnToGeoJSON(ovjsnData);
console.log(geojson); 
// 输出：
// {
//   "type": "FeatureCollection",
//   "features": [
//     {
//       "type": "Feature",
//       "geometry": {
//         "type": "Point",
//         "coordinates": [120.816, 31.40152048]
//       },
//       "properties": {
//         "name": "名称",
//         "group": ["分组名称"]
//       }
//     }
//   ]
// }

使用示例

基本使用示例

从本地文件转换

<input type="file" id="fileInput" accept=".kml,.gpx">
<button onclick="convert()">转换</button>

<script type="module">
import { kmlToGeoJSON, gpxToGeoJSON } from '@giszhc/kml-to-geojson';

async function convert() {
    const fileInput = document.getElementById('fileInput');
    const file = fileInput.files[0];
    
    if (!file) return;
    
    const text = await file.text();
    const parser = new DOMParser();
    const doc = parser.parseFromString(text, 'text/xml');
    
    let geojson;
    if (file.name.endsWith('.kml')) {
        geojson = await kmlToGeoJSON(doc);
    } else if (file.name.endsWith('.gpx')) {
        geojson = await gpxToGeoJSON(doc);
    }
    
    console.log(JSON.stringify(geojson, null, 2));
}
</script>

从网络 URL 转换

import { kmlToGeoJSON, gpxToGeoJSON } from '@giszhc/kml-to-geojson';

// 转换 KML
const kmlGeoJSON = await kmlToGeoJSON('https://example.com/regions.kml');
console.log(kmlGeoJSON);

// 转换 GPX
const gpxGeoJSON = await gpxToGeoJSON('https://example.com/hiking-track.gpx');
console.log(gpxGeoJSON);

结合地图库使用（Leaflet）

import { kmlToGeoJSON } from '@giszhc/kml-to-geojson';
import L from 'leaflet';

const map = L.map('map').setView([30, 120], 10);
L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png').addTo(map);

// 加载 KML 并显示在地图上
const geojson = await kmlToGeoJSON('https://example.com/data.kml');
L.geoJSON(geojson).addTo(map);

支持的几何类型

KML:

• Point
• LineString
• Polygon
• MultiGeometry
• Track / gx:Track

GPX:

• Track (trk)
• Route (rte)
• Waypoint (wpt)

注意事项

1. 浏览器环境 - 需要在浏览器环境中运行，依赖 DOMParser、XMLSerializer 和 fetch API
2. CORS - 从网络 URL 加载文件时，需要确保目标服务器支持跨域请求
3. 异步处理 - 所有转换方法都是异步的，需要使用 await 或 .then()
4. 错误处理 - 建议添加 try-catch 块来处理可能的解析错误

try {
    const geojson = await kmlToGeoJSON('https://example.com/data.kml');
    console.log(geojson);
} catch (error) {
    console.error('转换失败:', error);
}

License

MIT