map-ol-utils 0.1.28 → 0.1.30

package/README.md

@@ -1,109 +1,573 @@
 # map-ol-utils
 
-OpenLayers 地图工具库，封装常用的图层创建、要素交互与地图管理操作。
+> 目录：`packages/map-utils` ｜ npm 包名：`map-ol-utils`
+
+基于 [OpenLayers](https://openlayers.org/) 的地图工具库，封装了地图实例管理、底图创建、矢量/面/线/聚合/海量点图层、要素交互选择、视野自适应、WMTS 接入等常用能力。
+
+## 特性
+
+- **单例地图实例**：模块内维护一个全局 `instance`，多数工具函数直接操作该单例，无需层层传参。
+- **多种底图**：杭州规自瓦片、全国天地图（WMTS）、浙江省天地图（XYZ）。
+- **业务矢量图层**：根据业务数据自动推断几何类型（线/面）并生成 GeoJSON 图层，支持着色映射、点击高亮。
+- **海量点 MassMarks**：基于状态值的多套样式（默认 + 激活），可附带伴生线/面图层。
+- **聚合图层**：基于 `ol/source/Cluster`，半径/颜色随聚合数量动态计算。
+- **坐标系转换**：内部统一通过 [`gcoord`](https://github.com/hujiulong/gcoord) 转换到 `WGS84`（`EPSG:4326`）。
+- **事件总线**：内置 `mitt` 实例 `emitter`，用于派发要素选中等事件。
 
 ## 安装
 
 ```bash
-pnpm add map-ol-utils
+pnpm add map-ol-utils ol gcoord
 ```
 
-## 快速上手
+`ol` 是 **peerDependency**（要求 `>=10.5.0`），需由宿主项目安装。
+
+## 快速开始
 
 ```ts
-import { createMapInstance, createMassMarksLayer, addMassMarksLayer } from 'map-ol-utils'
+import { createMapInstance, createBusinessLayer, emitter } from 'map-ol-utils'
 
-// 创建地图（单例）
-const map = createMapInstance({ target: 'map-container' })
+const map = createMapInstance({ center: [120.15, 30.28], zoom: 11 })
+map.setTarget('map') // 容器通过 setTarget 绑定，config 仅透传给 ol/View
 
-// 添加点位图层
-const layer = createMassMarksLayer(dataList, styles)
+const layer = createBusinessLayer(dataList, {
+  key: 'coordinates',
+  isLine: false,
+  openClick: true,
+  layerName: 'biz-layer',
+  fillColor: '#4247DF',
+  strokeColor: '#1DEBFF'
+})
 map.addLayer(layer)
+
+emitter.on('selected-feature', (data) => console.log('选中要素：', data))
+```
+
+---
+
+# API 详解
+
+> 约定：下文「实例方法默认 `mapInstance = instance`」表示该参数缺省时使用模块单例；调用前请确保已 `createMapInstance` / `createMap`。
+
+## 一、地图实例（`create-map.ts`）
+
+### `createMapInstance(config?)`
+
+创建并缓存地图单例；若已存在则直接返回，不会重建。
+
+```ts
+function createMapInstance(config?: Record<string, any>): CustomMap
+```
+
+| 参数 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `config` | `object` | `{}` | 透传给 `createMap` → `ol/View` 的视图配置 |
+
+返回：`CustomMap`（OpenLayers `Map` 的扩展，附带 `getLayerByName` / `removeLayerByName` / `changeLayersByNames` 方法与 `activeBaseLayer` 字段）。
+
+```ts
+const map = createMapInstance({ center: [120.15, 30.28], zoom: 11 })
+map.setTarget('map')
+```
+
+### `createMap(config?)`
+
+始终新建一个 `CustomMap`。默认挂载杭州规自暗色底图，禁用旋转/双击缩放，并在 `pointermove` 时根据是否命中要素切换鼠标指针。`config` 与以下默认值合并后作为 `ol/View` 选项：
+
+```ts
+function createMap(config?: Record<string, any>): CustomMap
+// 默认 View 配置：
+// { zoom: 9.4, maxZoom: 18, minZoom: 9.4, center, baseLayer: 'vec-layer',
+//   projection: 'EPSG:4326', layers: [createBaseLayer()],
+//   constrainResolution: false, smoothExtentConstraint: false, tk }
+```
+
+| 参数 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `config` | `object` | `{}` | `ol/View` 配置；可额外传 `layers` 覆盖默认底图、`baseLayer` 标记当前底图名 |
+
+```ts
+const map = createMap({ zoom: 12, center: [121.43, 28.66] })
+```
+
+### `getMapInstance()`
+
+```ts
+function getMapInstance(): CustomMap
+```
+
+返回当前单例（等价于导出的 `instance` 变量）。
+
+### `disposeMap()`
+
+```ts
+function disposeMap(): void
+```
+
+销毁单例：移除全部 overlay、清空 interaction、移除并释放（`source.dispose()` + `layer.dispose()`）所有图层，`setTarget('')` 后将 `instance` 置为 `undefined`。
+
+### `resetMap(config?)`
+
+```ts
+function resetMap(config?: { center?: Coordinate; isClearAll?: boolean }): void
+// 默认：{ center: 上次中心, isClearAll: true }
+```
+
+清除所有非底图图层（内部调用 `removeAllLayers`）并复位缩放与中心。
+
+### `resetZoomAndCenter(center?)`
+
+```ts
+function resetZoomAndCenter(center?: [number, number]): void // 默认上次中心
+```
+
+动画（1s）复位到默认缩放 `9.4` 与指定中心。
+
+### `instance`
+
+```ts
+let instance: CustomMap // 导出变量；未创建时为 undefined
+```
+
+---
+
+## 二、底图与图层名管理（`base-layer.ts`）
+
+### `createBaseLayer(layerName?)`
+
+杭州规自瓦片底图（`EPSG:4326`，XYZ，5 路负载）。
+
+```ts
+function createBaseLayer(layerName?: HzsyType): Tile
+// HzsyType = 'hzsyraster' | 'hzsyvector' | 'hzsyvector_dark'（默认 'hzsyvector_dark'）
+```
+
+图层附带属性 `{ _isBaseLayer: true, _layerName: layerName }`，`zIndex: -5`。
+
+```ts
+const base = createBaseLayer('hzsyvector')
+map.addLayer(base)
+```
+
+### `createMapWorldLayer(layerName, tk?)`
+
+全国天地图 WMTS 图层。
+
+```ts
+function createMapWorldLayer(layerName: WorldLayerType, tk?: string): Tile
+// WorldLayerType = 'vec_c' | 'cva_c' | 'img_c' | 'cia_c' | 'ter_c' | 'cta_c' | 'ibo_c'
+```
+
+| 参数 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `layerName` | `WorldLayerType` | — | 形如 `img_c`，内部按 `_` 拆分为图层名与 matrixSet |
+| `tk` | `string` | 内置默认令牌 | 天地图访问令牌，**建议自行传入** |
+
+```ts
+map.addLayer(createMapWorldLayer('img_c', '你的天地图令牌'))
+```
+
+### `createZheJiangLayer(layerName?, tk?)`
+
+浙江省天地图 XYZ 图层。
+
+```ts
+function createZheJiangLayer(layerName?: ZheJiangType, tk?: string): Tile
+// ZheJiangType = 'emap' | 'emap_lab' | 'imgmap' | 'imgmap_lab'（默认 'emap'）
+```
+
+### `getLayerByName(name)`
+
+```ts
+function getLayerByName(name: string): Layer<Source> | undefined
+```
+
+按图层 `_layerName` 属性或 `className` 查找首个匹配图层。
+
+### `removeLayerByName(name)`
+
+```ts
+function removeLayerByName(name: string): void
+```
+
+查找匹配图层并释放其 source、从地图移除并 `dispose`。
+
+### `changeLayersByNames(activeNames, allLayerNames)`
+
+```ts
+function changeLayersByNames(activeNames: string[], allLayerNames: string[]): void
+```
+
+在 `allLayerNames` 范围内，按 `activeNames` 是否包含来逐一 `setVisible`，实现批量显隐切换。
+
+```ts
+changeLayersByNames(['poi-layer'], ['poi-layer', 'line-layer', 'face-layer'])
+```
+
+---
+
+## 三、矢量图层（`layer-utils.ts`）
+
+### `createBusinessLayer(dataList, config)`
+
+核心矢量图层构造函数：将业务数据组装为 GeoJSON（自动推断线/面几何类型），生成默认/激活样式并写入要素属性，可选开启点击交互。
+
+```ts
+function createBusinessLayer(dataList: MassData[], config: VectorConfig): VectorLayer
+```
+
+| `config` 关键字段 | 类型 | 说明 |
+|---|---|---|
+| `key` | `string` | 数据中存放坐标数组的字段名 |
+| `isLine` | `boolean` | 是否线图层（影响是否生成填充样式） |
+| `layerName` | `string?` | 图层名（className） |
+| `openClick` | `boolean?` | 是否创建单击选择交互 |
+| `colorKey` / `colorMap` | `string?` / `Map<string,string>?` | 按数据字段值映射颜色 |
+| `fillColor` / `strokeColor` | `string?` | 填充 / 描边色 |
+| `fillOpacity` / `strokeWeight` | `number?` | 填充透明度 / 线宽 |
+| `activeFillColor` / `activeStrokeColor` / `activeStrokeWeight` | … | 激活态样式 |
+| `crsForm` | `CRSTypes?` | 源坐标系（默认 `WGS84`） |
+| `isAutoFit` | `boolean?` | 选中后是否自动居中 |
+
+图层附带属性：`_isCustom`、`_isVectorLayer`、`_isAutoFit`、`_vectorConfig`、`_layerName`、`_dataList`、`_uuidSet`。
+
+```ts
+const layer = createBusinessLayer(dataList, {
+  key: 'coordinates', isLine: false, openClick: true,
+  layerName: 'area', colorKey: 'level',
+  colorMap: new Map([['1', '#f00'], ['2', '#0f0']]),
+  fillOpacity: 0.3, strokeWeight: 2
+})
+map.addLayer(layer)
+```
+
+### `createVectorLineLayer(dataList?, config)` / `createVectorFaceLayer(dataList?, config)`
+
+`createBusinessLayer` 的便捷包装，分别固定 `isLine: true` / `isLine: false`。
+
+```ts
+function createVectorLineLayer(dataList?: MassData[], config: VectorConfig): VectorLayer
+function createVectorFaceLayer(dataList?: MassData[], config: VectorConfig): VectorLayer
 ```
 
-## 主要 API
+### `appendFeaturesByLayer(targetLayer, dataList, crsForm?)`
 
-### 地图管理
+向已有矢量图层追加要素（同步更新其 `_uuidSet`），复用图层 `_vectorConfig` 生成样式。
 
-| 函数 | 说明 |
-|------|------|
-| `createMap(config)` | 创建 OL 地图实例 |
-| `createMapInstance(config)` | 创建地图单例 |
-| `getMapInstance()` | 获取当前单例 |
-| `disposeMap()` | 销毁地图，释放资源 |
-| `resetMap(config)` | 重置地图（清除图层并还原视图） |
-| `resetZoomAndCenter(center)` | 动画还原缩放和中心点 |
+```ts
+function appendFeaturesByLayer(
+  targetLayer: VectorLayer,
+  dataList: MassData[],
+  crsForm?: CRSTypes
+): void
+```
 
-### 底图图层
+---
 
-| 函数 | 说明 |
-|------|------|
-| `createBaseLayer(type?)` | 创建杭州本地切片底图 |
-| `createMapWorldLayer(options)` | 创建天地图图层 |
-| `createZheJiangLayer(type?)` | 创建浙江省切片图层 |
-| `switchBaseLayer(type)` | 切换底图类型 |
+## 四、海量点 MassMarks（`layer-utils.ts`）
 
-### 矢量图层
+### `buildMassMarksStyles(getImgUrlFn)`
 
-| 函数 | 说明 |
-|------|------|
-| `createBusinessLayer(dataList, config)` | 从业务数据创建矢量图层（自动识别线/面类型） |
-| `createVectorLineLayer(dataList, config)` | 创建线状图层 |
-| `createVectorFaceLayer(dataList, config)` | 创建面状图层 |
-| `appendFeaturesByLayer(layer, dataList)` | 向已有图层追加要素 |
+高阶函数：先注入「图标地址生成器工厂」，再按 `IconConfig` 生成「默认 + 激活」两段样式数组（长度 `statusNum * 2`）。
 
-### 点位与聚合
+```ts
+function buildMassMarksStyles(
+  getImgUrlFn: GetImgUrlFn
+): (iconConfig: IconConfig) => Style[]
 
-| 函数 | 说明 |
-|------|------|
-| `createMassMarksLayer(dataList, styles)` | 创建大量点位图层 |
-| `addMassMarksLayer(getImgUrlFn)` | 高阶函数，返回添加点位图层的方法 |
-| `buildMassMarksStyles(getImgUrlFn)` | 构建多状态点位样式数组 |
-| `updateMarksLayersByStatus(statusList)` | 按状态控制点位显隐 |
-| `createClusterLayer(dataList, config)` | 创建聚合图层 |
+type GetImgUrl = (name: string, ext?: string) => string
+type GetImgUrlFn = (baseUrl: string) => GetImgUrl
+```
 
-### 交互与选择
+图标地址按 `${markerIcon}-${i}` / `${markerIcon}-${i}-active`（后缀 `.webp`）拼接。
 
-| 函数 | 说明 |
-|------|------|
-| `createSelectByLayer(layer)` | 为图层添加点击选中交互 |
-| `activeFeatureByUid(uid)` | 通过 uid 程序化激活要素 |
-| `resetActiveFeature()` | 清除选中状态 |
-| `resetActiveVector()` | 清除矢量激活状态 |
+```ts
+const buildStyles = buildMassMarksStyles((baseUrl) => (name, ext) => `${baseUrl}/${name}${ext}`)
+const styles = buildStyles({ baseUrl: '/icons', markerIcon: 'alarm', markerSize: [32, 32], statusNum: 5 })
+```
 
-### 视图控制
+### `createMassMarksLayer(dataList, styleList?)`
 
-| 函数 | 说明 |
-|------|------|
-| `setFitViewByCoords(coords)` | 缩放至坐标范围 |
-| `setFitViewByGeom(geom)` | 缩放至几何范围 |
-| `setFitViewByLayer(layer)` | 缩放至图层范围 |
+```ts
+function createMassMarksLayer(dataList: MassData[], styleList?: StyleLike[]): VectorLayer
+```
 
-### OGC
+按 `item.style` 索引在 `styleList` 中取样式创建要素图层（`zIndex: 2000`）。图层附带 `_isMassMarksLayer`、`_statusNum`、`_dataList`、`_uuidSet` 等属性。
 
-| 函数 | 说明 |
-|------|------|
-| `createWmtsLayer(url, options)` | 从 GeoServer GetCapabilities 创建 WMTS 图层 |
+### `addMassMarksLayer(getImgUrlFn)`
 
-## 依赖
+高阶函数，返回的方法会生成样式、创建海量点图层、按 `hasLine` / `hasFace` 附加伴生矢量图层，并自动加入地图。
 
-- [ol](https://openlayers.org/) `>=10.5.0`（peer dependency）
-- [gcoord](https://github.com/hujiulong/gcoord) — 坐标系转换
-- [mitt](https://github.com/developit/mitt) — 事件总线
+```ts
+function addMassMarksLayer(
+  getImgUrlFn: GetImgUrlFn
+): (dataList?: MassData[], iconConfig: IconConfig, openClick?: boolean) => VectorLayer
+```
 
-## 事件
+| `iconConfig` 字段 | 类型 | 说明 |
+|---|---|---|
+| `baseUrl` | `string` | 图标根地址 |
+| `markerIcon` | `string` | 图标名前缀 |
+| `markerSize` | `[number, number]` | 图标尺寸 |
+| `statusNum` | `number?` | 状态数（默认 5） |
+| `activeScale` | `number?` | 激活放大倍数（默认 1.3） |
+| `hasLine` / `hasFace` | `boolean?` | 是否附带线 / 面图层 |
+| `isDynamic` | `boolean?` | 是否动态图层（选中派发 `dynamic-marker`） |
+| `isAutoFit` | `boolean?` | 选中是否自动居中 |
+| `layerName` | `string?` | 图层名 |
+| `offset` | `[number, number]?` | 偏移 |
+| `marksStyles` | `Style[]?` | 直接指定样式（跳过自动生成） |
+| `vectorConfig` | `VectorConfig?` | 伴生线/面图层配置覆盖 |
+
+```ts
+const add = addMassMarksLayer((baseUrl) => (n, e) => `${baseUrl}/${n}${e}`)
+const layer = add(dataList, { baseUrl: '/icons', markerIcon: 'alarm', markerSize: [32, 32], statusNum: 5, hasLine: true })
+```
 
-通过导出的 `emitter` 监听图层交互事件：
+### `addFeaturesByLayer(targetLayer, dataList, config)`
+
+向海量点图层增量添加要素（复用图层 `_massMarksStyles`）。
+
+```ts
+function addFeaturesByLayer(
+  targetLayer: VectorLayer,
+  dataList: MassData[],
+  config: { clear: boolean }
+): void
+```
+
+`config.clear` 为 `true` 时先清空 source 再添加。
+
+### `updateMarksLayersByStatus(checkedStatusList?)`
+
+```ts
+function updateMarksLayersByStatus(checkedStatusList?: string[]): MassData[]
+```
+
+遍历所有海量点图层：`status` 不在勾选列表中的要素设为隐藏样式，否则恢复默认样式。返回当前保留显示的数据数组。
+
+---
+
+## 五、聚合图层（`layer-utils.ts`）
+
+### `createClusterLayer(dataList, config)`
 
 ```ts
-import { emitter } from 'map-ol-utils'
+function createClusterLayer(dataList: ClusterData[], config: ClusterConfig): VectorLayer
 
-emitter.on('selected-feature', (data) => {
-  console.log('选中要素：', data)
+type ClusterData = {
+  _uuid: string
+  name: string
+  style: number
+  lnglat: number[]
+  rawData: Record<string, any>
+}
+type ClusterConfig = {
+  distance: number
+  minDistance: number
+  singleStyles: Style[]
+  layerName?: string
+  openClick?: boolean
+  computedRadius?: (size: number) => number
+  buildStyle?: (feature: FeatureLike) => Style
+}
+```
+
+未传 `buildStyle` 时使用内置样式：聚合点半径与色相（`hsla`）随聚合数量变化；`size === 1` 时使用 `singleStyles`。
+
+```ts
+const cluster = createClusterLayer(dataList, {
+  distance: 80, minDistance: 20,
+  singleStyles: [singlePointStyle], openClick: true
 })
+map.addLayer(cluster)
+```
+
+---
+
+## 六、交互与选中（`layer-utils.ts`）
+
+### `createSelectByLayer(vectorLayer)`
+
+为指定图层创建 `ol/interaction/Select`（单击、`multi: false`、`hitTolerance: 10`），命中要素时切换激活样式并派发 `selected-feature` 事件，支持聚合图层单点展开。交互会写入图层属性 `_selectInteraction`。
+
+```ts
+function createSelectByLayer(vectorLayer: VectorLayer): Select
+```
+
+### `activeFeatureByUid(uid)`
+
+```ts
+function activeFeatureByUid(uid: string): void
 ```
 
-| 事件名 | 触发时机 | 回调参数 |
-|--------|----------|----------|
-| `selected-feature` | 点击选中要素 | feature properties |
-| `dynamic-marker` | 选中动态标注点 | marker data |
+在带 `_isVectorLayer` 且其 `_uuidSet` 含该 `uid` 的图层中，程序化触发对应要素的选中（派发 select 事件并加入选中集合）。
+
+### `resetActiveFeature()` / `resetActiveVector()`
+
+```ts
+function resetActiveFeature(): void // 清空 overlay + 触发各矢量图层 deselect
+function resetActiveVector(): void  // 清空 overlay + 清空各图层选择交互的要素集合
+```
+
+---
+
+## 七、覆盖物与视野（`layer-utils.ts`）
+
+### `createOverlay(config?)`
+
+```ts
+function createOverlay(config?: import('ol/Overlay').Options): Overlay
+// 默认：{ id: 'popup-container', positioning: 'top-center' }
+```
+
+未显式传 `element` 时，按 `config.id` 取 `document.getElementById(id)` 作为容器。
+
+### `removeOverlays(key?)` / `removeAllLayers()`
+
+```ts
+function removeOverlays(key?: string): void // 移除带指定属性键的 overlay（默认按 'position'）
+function removeAllLayers(): void            // 移除并释放所有非底图（无 _isBaseLayer）图层 + overlay
+```
+
+### `createAnimationMarker(imgUrl, data)`
+
+```ts
+function createAnimationMarker(imgUrl: string, data: MassData): void
+```
+
+以 `data.lnglat`（经 `data.crsForm` → `WGS84` 转换）创建动画标注 Overlay，先移除已有动画标注。`data` 中读取 `width` / `height` / `lnglat` / `crsForm`。
+
+### `setFitViewByCoords` / `setFitViewByGeom` / `setFitViewByLayer`
+
+```ts
+function setFitViewByCoords(
+  coords: Coordinate[],
+  mapInstance?: CustomMap,
+  fitOptions?: FitOptions | AnimationOptions
+): void   // 单点时 animate 到 zoom 14，多点时 fit 包围盒
+
+function setFitViewByGeom(
+  geom: SimpleGeometry,
+  mapInstance?: CustomMap,
+  fitOptions?: FitOptions
+): void
+
+function setFitViewByLayer(
+  layer: VectorLayer,
+  mapInstance?: CustomMap,
+  fitOptions?: FitOptions
+): void   // 按图层 source 的 extent 自适应
+```
+
+三者默认 `padding: [50,50,50,50]`、`duration: 1000`，可由 `fitOptions` 覆盖。
+
+```ts
+setFitViewByCoords([[120.1, 30.2], [120.3, 30.4]])
+setFitViewByLayer(layer, undefined, { duration: 500 })
+```
+
+### `getLayersDataList()`
+
+```ts
+function getLayersDataList(): any[]
+```
+
+汇总所有图层 `_dataList` 属性并 `flat(2)`，返回当前地图上的全部业务数据。
+
+---
+
+## 八、WMTS（`ogc-utils.ts`）
+
+### `createWmtsLayer(serverUrl)`
+
+柯里化函数：先传 GeoServer 服务地址，返回的方法按 `WmtsSourceOptions` 解析 GetCapabilities 并构建图层（内部缓存 capabilities，重复调用不重复请求）。
+
+```ts
+function createWmtsLayer(
+  serverUrl: string
+): (config: WmtsSourceOptions) => Promise<TileLayer>
+
+type WmtsSourceOptions = {
+  layerName: string   // 形如 'workspace:datastore'
+  style?: string
+  format?: string     // 默认 'image/png'
+  version?: string    // 默认 '1.1.0'
+  matrixSet?: string  // 默认 'EPSG:4326'
+}
+```
+
+```ts
+const build = createWmtsLayer('https://geoserver.example.com/geoserver')
+const layer = await build({ layerName: 'ws:store', matrixSet: 'EPSG:4326' })
+map.addLayer(layer)
+```
+
+---
+
+## 九、事件总线（`emitter`）
+
+```ts
+import { emitter } from 'map-ol-utils' // mitt 实例
+```
+
+| 事件名 | 载荷 | 触发时机 |
+|---|---|---|
+| `selected-feature` | 要素属性对象 | 要素被选中（`createSelectByLayer` 内触发） |
+| `dynamic-marker` | 动画标注配置 | 选中动态图层（`_isDynamic`）要素 1s 后 |
+
+---
+
+## 十、类型定义（`types.ts`，`export * from './types'`）
+
+```ts
+interface CustomMap extends OlMap {
+  activeBaseLayer?: string
+  changeBaseLayer?: () => void
+  getLayerByName?: (name: string) => Layer<Source> | undefined
+  removeLayerByName?: (name: string) => void
+  changeLayersByNames?: (activeNames: string[], allLayerNames: string[]) => void
+}
+
+type MassData = {
+  _uuid?: string
+  id: string
+  style: number
+  name: string
+  status: string
+  width?: number
+  height?: number
+  crsForm?: CRSTypes
+  rawData: Record<string, any>
+  lnglat: [string, string] | [number, number]
+}
+
+enum GeometryType {
+  LineString = 'LineString',
+  MultiLineString = 'MultiLineString',
+  Polygon = 'Polygon',
+  MultiPolygon = 'MultiPolygon',
+  Invalid = 'Invalid'
+}
+```
+
+完整导出还包括：`VectorConfig`、`ClusterConfig`、`ClusterData`、`IconConfig`、`WmtsSourceOptions`、`GetImgUrl`、`GetImgUrlFn`、`HzsyType`、`ZheJiangType`、`WorldLayerType`、`GeometryCoordinates`。
+
+---
+
+## 图层约定属性
+
+工具库通过图层 properties 标记元信息，维护时请保持一致：`_isBaseLayer`、`_layerName`、`_isCustom`、`_isVectorLayer`、`_isClusterLayer`、`_isMassMarksLayer`、`_selectInteraction`、`_uuidSet`、`_dataList`、`_vectorConfig`、`_isAutoFit`、`_massMarksStyles`、`_statusNum`。
+
+## 构建
+
+```bash
+pnpm --dir packages/map-utils build   # tsup 产出 esm + cjs + d.ts
+pnpm --dir packages/map-utils dev     # watch 模式
+```
+
+## 注意事项
+
+- **单例副作用**：绝大多数函数依赖模块级 `instance`，请先 `createMapInstance` / `createMap` 再调用其他工具；`disposeMap` 后 `instance` 为 `undefined`。
+- **坐标系**：输入数据可通过 `config.crsForm` / `data.crsForm` 指定源坐标系，内部统一转为 `WGS84`。
+- **天地图令牌**：`createMapWorldLayer` / `createZheJiangLayer` 内置了默认 `tk`，正式项目请传入自有令牌。