geojson-to-kml (KML 格式转换工具)

geojson-to-kml (KML 格式转换工具)

一个 简单、轻量、健壮 的 JavaScript / TypeScript 库，用于将 GeoJSON 数据转换为 KML (Keyhole Markup Language) 格式。

本库不仅支持基础的几何转换，还完整支持了 Mapbox SimpleStyle 规范 ，可以将 GeoJSON 中的样式属性（如 marker-color、stroke 等）转换为 KML 的样式定义。

---

✨ 特性

• 🚀 零依赖：基于轻量级逻辑实现，无沉重依赖。
• 🛡️ 类型安全 ：原生 TypeScript 支持，完美适配 geojson 类型定义。
• 🎨 样式支持：支持 Mapbox SimpleStyle，自动生成 KML Style 标签。
• 📊 数据保留 ：GeoJSON 的 properties 会自动转换为 KML 的 ExtendedData。
• 🧩 全类型支持：涵盖所有 Geometry、Feature、FeatureCollection。
• 🌲 Tree Shaking：现代化 ESM 导出，支持按需引入。

---

📦 安装

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

或

# pnpm
pnpm add @giszhc/geojson-to-kml

---

🚀 快速上手

基础用法

TypeScript

import tokml from '@giszhc/geojson-to-kml';

const geojson = {
  type: 'Point',
  coordinates: [120.123, 30.456]
};

const kml = tokml(geojson);
console.log(kml);
// 输出包含 <Placemark><Point>... 的 XML 字符串

带样式的转换 (SimpleStyle)

TypeScript

const feature = {
  type: 'Feature',
  properties: {
    name: '我的位置',
    'marker-color': '#ff0000',
    'stroke': '#00ff00',
    'stroke-width': 3
  },
  geometry: {
    type: 'Point',
    coordinates: [120, 30]
  }
};

const kml = tokml(feature, {
  simplestyle: true, // 开启样式转换
  name: 'name'       // 指定使用哪个属性作为节点名称
});

---

🛠️ API 参数说明

tokml(geojson: GeoJSON, options?: TokmlOptions): string

参数名	类型	描述	默认值
documentName	string	KML <Document> 节点的名称	undefined
documentDescription	string	KML <Document> 节点的描述	undefined
name	string	从 properties 中提取哪个字段作为 <name>	'name'
description	string	从 properties 中提取哪个字段作为 <description>	'description'
simplestyle	boolean	是否将 Mapbox 样式属性转换为 KML 样式	false
timestamp	string	从 properties 中提取哪个字段作为 <TimeStamp>	'timestamp'

---

🎨 支持的样式属性 (SimpleStyle)

当开启 simplestyle: true 时，以下 GeoJSON 属性将被识别并转换：

属性名	描述	示例
marker-color	标记点的颜色 (Hex)	#ff0000
marker-size	标记点大小 (small, medium, large)	large
marker-symbol	标记点图标符号	bus, star
stroke	线条或多边形边界颜色	#0000ff
stroke-opacity	线条透明度 (0.0 - 1.0)	0.5
stroke-width	线条宽度 (像素)	2
fill	多边形填充颜色	#00ff00
fill-opacity	填充透明度 (0.0 - 1.0)	0.3

⚠️ 注意事项

1. 坐标系 ：KML 官方规范要求使用 WGS84 (EPSG:4326) 经纬度。转换前请确保您的 GeoJSON 坐标正确。
2. 数据类型 ：所有的 properties 都会被放入 <ExtendedData> 中，这有助于在 Google Earth 等软件中查看完整的业务数据。
3. 命名空间 ：生成的 KML 默认包含 xmlns="http://www.opengis.net/kml/2.2"。

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