npm package: @giszhc/shapefile
Description: Shapefile 和 GeoJSON 格式双向转换库
Latest version: 0.0.1

# @giszhc/shapefile

Shapefile 和 GeoJSON 格式双向转换库

---

## 在线示例

我们提供了一个功能完整的在线演示页面，您可以直接在浏览器中体验所有功能：

**🌐 立即体验：** [点击访问在线演示](https://giszhc.github.io/shapefile/)

---

## 安装

```bash
npm install @giszhc/shapefile
```

## 使用方法

### shpToGeoJSON(input: File | ArrayBuffer | string | URL, options?: RequestOptions): Promise<FeatureCollection>
将 Shapefile(.zip/.shp) 转换为 GeoJSON

**支持的输入类型：**
- `File` - 用户上传的文件对象
- `ArrayBuffer` - 已读取的文件数据
- `string` - 网络URL地址
- `URL` - URL对象

```typescript
import { shpToGeoJSON } from '@giszhc/shapefile';

// 1. File对象
const file = document.getElementById('fileInput').files[0];
const geojson1 = await shpToGeoJSON(file);

// 2. ArrayBuffer
const arrayBuffer = await file.arrayBuffer();
const geojson2 = await shpToGeoJSON(arrayBuffer);

// 3. 网络URL
const geojson3 = await shpToGeoJSON('https://example.com/data.zip');

// 4. 带认证headers的网络请求
const geojson4 = await shpToGeoJSON('https://api.example.com/data.shp', {
  headers: {
    'Authorization': 'Bearer your-token',
    'X-API-Key': 'your-api-key'
  }
});
```

**RequestOptions 参数：**

```typescript
interface RequestOptions {
  headers?: HeadersInit;  // HTTP请求头，仅网络URL时有效
}
```

### geoJSONToShp(geojson: FeatureCollection, options?: ZipOptions): Promise<Blob>
将 GeoJSON 转换为 Shapefile(.zip) Blob对象

```typescript
import { geoJSONToShp } from '@giszhc/shapefile';

const geojson = {
  type: 'FeatureCollection',
  features: [...]
};

const zipBlob = await geoJSONToShp(geojson, {
  folder: 'shapes',           // zip内部文件夹名
  filename: 'output',         // zip文件名(不含扩展名)
  compression: 'DEFLATE',     // 压缩方式: 'DEFLATE' | 'STORE'
  outputType: 'blob',         // 输出类型: 'blob' | 'uint8array' | 'arraybuffer' 等
  types: {                    // 自定义各几何类型的文件名
    point: 'points',
    polygon: 'polygons',
    line: 'lines'
  }
});
```

**options 参数说明：**

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `folder` | `string` | `'shapes'` | zip包内部的文件夹名称 |
| `filename` | `string` | `'output'` | 输出的zip文件名(不含.zip扩展名) |
| `compression` | `'DEFLATE' \| 'STORE'` | `'DEFLATE'` | 压缩算法 |
| `outputType` | `string` | `'blob'` | 输出类型，支持: `'blob'`, `'uint8array'`, `'arraybuffer'`, `'nodebuffer'`, `'base64'` 等 |
| `types.point` | `string` | - | 点要素的文件名前缀 |
| `types.polygon` | `string` | - | 面要素的文件名前缀 |
| `types.line` | `string` | - | 线要素的文件名前缀 |
| `types.multipolygon` | `string` | - | 多面要素的文件名前缀 |
| `types.multiline` | `string` | - | 多线要素的文件名前缀 |
| `prj` | `string` | - | 自定义投影文件(.prj)内容，WKT格式的坐标系统定义 |

**自定义投影示例：**

```typescript
// 使用自定义坐标系（例如：荷兰 Amersfoort / RD New）
const zipBlob = await geoJSONToShp(geojson, {
  filename: 'custom_projection',
  prj: 'PROJCS["Amersfoort / RD New",GEOGCS["Amersfoort",DATUM["D_Amersfoort",SPHEROID["Bessel_1841",6377397.155,299.1528128]],PRIMEM["Greenwich",0],UNIT["Degree",0.017453292519943295]],PROJECTION["Stereographic_North_Pole"],PARAMETER["standard_parallel_1",52.15616055555555],PARAMETER["central_meridian",5.38763888888889],PARAMETER["scale_factor",0.9999079],PARAMETER["false_easting",155000],PARAMETER["false_northing",463000],UNIT["Meter",1]]'
});
```

> **注意**: `prj` 参数接受 WKT (Well-Known Text) 格式的坐标系统定义字符串。你可以从 [spatialreference.org](https://spatialreference.org/) 或其他GIS工具获取不同坐标系的 WKT 定义。

**类型定义：**

```typescript
interface ZipOptions {
  folder?: string;              // zip内部文件夹名
  filename?: string;            // zip文件名(不含扩展名)
  prj?: string;                 // 自定义投影文件(.prj)内容
  compression?: 'DEFLATE' | 'STORE';  // 压缩算法
  outputType?: 'blob' | 'uint8array' | 'arraybuffer' | 'nodebuffer' | 'base64' | 'string' | 'binarystring' | 'array' | 'stream';  // 输出类型
  types?: {
    point?: string;             // 点要素文件名
    polygon?: string;           // 面要素文件名
    line?: string;              // 线要素文件名
    multipolygon?: string;      // 多面要素文件名
    multiline?: string;         // 多线要素文件名
  };
}
```

## License

MIT