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"。