@giszhc/kml-to-geojson：kml转换GeoJSON，这才是更优解

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 安装该库：

pnpminstall@giszhc/kml-to-geojson# 或npminstall@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：从本地文件读取constfileInput=document.getElementById('file');constfile=fileInput.files[0];consttext=awaitfile.text();constgeojson=awaitkmlToGeoJSON(text);console.log(geojson);// FeatureCollection

import{kmlToGeoJSON}from'@giszhc/kml-to-geojson';// 方式 2：从网络 URL 加载constgeojson=awaitkmlToGeoJSON('https://example.com/data.kml');console.log(geojson);// FeatureCollection

import{kmlToGeoJSON}from'@giszhc/kml-to-geojson';// 方式 3：直接传入 XML 字符串constkmlContent=`<?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>`;constgeojson=awaitkmlToGeoJSON(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：从本地文件读取constfileInput=document.getElementById('file');constfile=fileInput.files[0];consttext=awaitfile.text();constgeojson=awaitgpxToGeoJSON(text);console.log(geojson);// FeatureCollection

import{gpxToGeoJSON}from'@giszhc/kml-to-geojson';// 方式 2：从网络 URL 加载constgeojson=awaitgpxToGeoJSON('https://example.com/track.gpx');console.log(geojson);// FeatureCollection

import{gpxToGeoJSON}from'@giszhc/kml-to-geojson';// 方式 3：直接传入 XML 字符串constgpxContent=`<?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>`;constgeojson=awaitgpxToGeoJSON(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 格式）constfileInput=document.getElementById('file');constfile=fileInput.files[0];consttext=awaitfile.text();constgeojson=awaitovjsnToGeoJSON(text);console.log(geojson);// FeatureCollection

import{ovjsnToGeoJSON}from'@giszhc/kml-to-geojson';// 方式 2：从网络 URL 加载constgeojson=awaitovjsnToGeoJSON('https://example.com/data.ovjsn');console.log(geojson);// FeatureCollection

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

使用示例

基本使用示例

从本地文件转换

<inputtype="file"id="fileInput"accept=".kml,.gpx"><buttononclick="convert()">转换</button><scripttype="module">import{kmlToGeoJSON,gpxToGeoJSON}from'@giszhc/kml-to-geojson';asyncfunctionconvert(){constfileInput=document.getElementById('fileInput');constfile=fileInput.files[0];if(!file)return;consttext=awaitfile.text();constparser=newDOMParser();constdoc=parser.parseFromString(text,'text/xml');letgeojson;if(file.name.endsWith('.kml')){geojson=awaitkmlToGeoJSON(doc);}elseif(file.name.endsWith('.gpx')){geojson=awaitgpxToGeoJSON(doc);}console.log(JSON.stringify(geojson,null,2));}</script>

从网络 URL 转换

import{kmlToGeoJSON,gpxToGeoJSON}from'@giszhc/kml-to-geojson';// 转换 KMLconstkmlGeoJSON=awaitkmlToGeoJSON('https://example.com/regions.kml');console.log(kmlGeoJSON);// 转换 GPXconstgpxGeoJSON=awaitgpxToGeoJSON('https://example.com/hiking-track.gpx');console.log(gpxGeoJSON);

结合地图库使用（Leaflet）

import{kmlToGeoJSON}from'@giszhc/kml-to-geojson';importLfrom'leaflet';constmap=L.map('map').setView([30,120],10);L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png').addTo(map);// 加载 KML 并显示在地图上constgeojson=awaitkmlToGeoJSON('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和fetchAPI
2. CORS- 从网络 URL 加载文件时，需要确保目标服务器支持跨域请求
3. 异步处理- 所有转换方法都是异步的，需要使用await或.then()
4. 错误处理- 建议添加 try-catch 块来处理可能的解析错误

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

如果这篇文章对你有帮助，欢迎点赞 👍 收藏 ⭐ 关注 👀

完结，撒花✿✿ヽ(°▽°)ノ✿