npm package: @giszhc/kml-to-geojson
Description: 一个简单、轻量的 JavaScript / TypeScript 工具库，用于将 **KML**、**GPX**、**OVKML**（奥维 KML）或 **OVJSN**（奥维 JSON）文件转换为 **GeoJSON** 格式。
Latest version: 0.0.5

# 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 友好** - 支持按需引入

---

## 在线示例

我们提供了一个功能完整的在线演示页面，您可以直接在浏览器中体验所有功能：

**🌐 立即体验：** [点击访问在线演示](https://giszhc.github.io/kml-to-geojson/)

在线示例支持：
- ✨ KML、GPX、OVKML、OVJSN 格式转换
- 📁 本地文件上传
- 🌐 URL 地址加载
- 💾 结果下载和复制

---

## 安装

你可以通过 npm 或 pnpm 安装该库：

```bash
pnpm install @giszhc/kml-to-geojson
# 或
npm install @giszhc/kml-to-geojson
```

---

## API

### kmlToGeoJSON(input: Document | string): Promise<FeatureCollection>

将 KML 文档或 URL 转换为 GeoJSON FeatureCollection

**参数：**
- `input` - 可以是：
  - DOM Document 对象
  - KML 文件的 URL 字符串（以 `http://` 或 `https://` 开头）
  - KML 文件内容的字符串

**返回：**
- `Promise<FeatureCollection>` - GeoJSON FeatureCollection 对象

**输出示例：**
```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [120.5, 30.2]
      },
      "properties": {
        "name": "示例地点",
        "address": "测试地址",
        "description": "描述信息"
      }
    }
  ]
}
```

**示例：**

```typescript
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
```

```typescript
import { kmlToGeoJSON } from '@giszhc/kml-to-geojson';

// 方式 2：从网络 URL 加载
const geojson = await kmlToGeoJSON('https://example.com/data.kml');
console.log(geojson); // FeatureCollection
```

```typescript
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<FeatureCollection>

将 GPX 文档或 URL 转换为 GeoJSON FeatureCollection

**参数：**
- `input` - 可以是：
  - DOM Document 对象
  - GPX 文件的 URL 字符串（以 `http://` 或 `https://` 开头）
  - GPX 文件内容的字符串

**返回：**
- `Promise<FeatureCollection>` - GeoJSON FeatureCollection 对象

**示例：**

```typescript
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
```

```typescript
import { gpxToGeoJSON } from '@giszhc/kml-to-geojson';

// 方式 2：从网络 URL 加载
const geojson = await gpxToGeoJSON('https://example.com/track.gpx');
console.log(geojson); // FeatureCollection
```

```typescript
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<FeatureCollection>

将 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 对象

**示例：**

```typescript
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
```

```typescript
import { ovjsnToGeoJSON } from '@giszhc/kml-to-geojson';

// 方式 2：从网络 URL 加载
const geojson = await ovjsnToGeoJSON('https://example.com/data.ovjsn');
console.log(geojson); // FeatureCollection
```

```typescript
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": ["分组名称"]
//       }
//     }
//   ]
// }
```

## 使用示例

### 基本使用示例

#### 从本地文件转换

```html
<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 转换

```typescript
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）

```typescript
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 块来处理可能的解析错误

```typescript
try {
    const geojson = await kmlToGeoJSON('https://example.com/data.kml');
    console.log(geojson);
} catch (error) {
    console.error('转换失败:', error);
}
```

---

## License

MIT