map-ol-utils 0.1.30 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 > 目录：`packages/map-utils` ｜ npm 包名：`map-ol-utils`
 
-基于 [OpenLayers](https://openlayers.org/) 的地图工具库，封装了地图实例管理、底图创建、矢量/面/线/聚合/海量点图层、要素交互选择、视野自适应、WMTS 接入等常用能力。
+基于 [OpenLayers](https://openlayers.org/) 的地图工具库，封装了地图实例管理、底图创建、矢量/面/线/聚合/海量点图层、要素交互选择、视野自适应、WMTS 接入，以及天地图私有 VTS 的浏览器加载与标准 MVT 转换能力。
 
 ## 特性
 
@@ -13,6 +13,29 @@
 - **聚合图层**：基于 `ol/source/Cluster`，半径/颜色随聚合数量动态计算。
 - **坐标系转换**：内部统一通过 [`gcoord`](https://github.com/hujiulong/gcoord) 转换到 `WGS84`（`EPSG:4326`）。
 - **事件总线**：内置 `mitt` 实例 `emitter`，用于派发要素选中等事件。
+- **扩展能力**：提供天地图组合、栅格着色、Marker、绘制量算、GeoJSON 图层和多图层选择能力。
+- **私有 VTS 转换**：支持 PK 编解码、私有 Protobuf 字段与 Geometry 命令转换、样式合并和 Web Worker 解码。
+
+## 项目结构
+
+```text
+packages/map-utils/
+├── src/
+│   ├── core/                    # 类型、常量、事件总线与地图上下文
+│   ├── interaction/             # 绘制和要素选择交互
+│   ├── layer/                   # 底图、矢量、聚合、海量点、WMTS 与图层生命周期
+│   ├── map/                     # 地图实例管理与视野适配
+│   ├── overlay/                 # Overlay 与动画标注
+│   ├── tdt-vts/                 # 天地图私有 VTS 加载、转换、Worker 与 OL 适配
+│   └── index.ts                 # 唯一公共 API 入口
+├── test/
+│   ├── architecture.test.ts     # 模块边界与架构约束
+│   └── compatibility.test.ts    # 公共 API 兼容性测试
+├── package.json                 # 包入口、依赖和构建脚本
+├── tsconfig.json                # TypeScript 配置
+├── tsdown.config.ts             # ESM/CJS 与类型声明构建配置
+└── README.md                    # 安装、API 与使用约定
+```
 
 ## 安装
 
@@ -20,7 +43,7 @@
 pnpm add map-ol-utils ol gcoord
 ```
 
-`ol` 是 **peerDependency**（要求 `>=10.5.0`），需由宿主项目安装。
+`ol` 是 **peerDependency**（要求 `^10.10.0`），需由宿主项目安装。
 
 ## 快速开始
 
@@ -43,13 +66,67 @@ map.addLayer(layer)
 emitter.on('selected-feature', (data) => console.log('选中要素：', data))
 ```
 
+## 天地图私有 VTS
+
+直接加载并转换为标准 Mapbox Vector Tile：
+
+```ts
+import { createTdtVtsUrl, loadAndNormalizeTdtVts } from 'map-ol-utils'
+
+const url = createTdtVtsUrl([3, 0, 4], {
+  token: 'YOUR_TDT_TOKEN',
+  hosts: [
+    'https://tile0.tianditu.gov.cn',
+    'https://tile1.tianditu.gov.cn',
+    'https://tile2.tianditu.gov.cn'
+  ]
+})
+
+if (url) {
+  const { buffer, stats } = await loadAndNormalizeTdtVts(url)
+}
+```
+
+OpenLayers 可直接创建私有矢量瓦片源。解码默认在随包发布的模块 Worker 中执行：
+
+```ts
+import { createTdtVectorSource } from 'map-ol-utils'
+
+const { source, decoder } = createTdtVectorSource({
+  token: 'YOUR_TDT_TOKEN',
+  restoreMode: 'auto',
+  decoderOptions: {
+    requestTimeoutMs: 15_000
+  }
+})
+
+// 释放 source 时会自动释放关联的 Worker
+source.dispose()
+
+// 也可以取消单次解码，或在仅使用 decoder 时手动释放
+const controller = new AbortController()
+const decoding = decoder.decode(url, { signal: controller.signal })
+controller.abort()
+await decoding.catch(() => undefined)
+decoder.dispose()
+```
+
+`decoderOptions.requestTimeoutMs` 默认值为 30 秒。`source.dispose()` 与 `decoder.dispose()` 均可安全重复调用；前者会自动调用后者。
+
+相关公共 API：
+
+- `encodeTdtPk()` / `decodeTdtPk()` / `createTdtVtsUrl()`
+- `loadAndNormalizeTdtVts()` / `normalizePrivateMvt()`
+- `TdtDecoderWorkerClient` / `createTdtVectorSource()`
+- `loadTdtStyleBundle()` / `mergeTdtStyleLayers()`
+
 ---
 
 # API 详解
 
 > 约定：下文「实例方法默认 `mapInstance = instance`」表示该参数缺省时使用模块单例；调用前请确保已 `createMapInstance` / `createMap`。
 
-## 一、地图实例（`create-map.ts`）
+## 一、地图实例（`map/create-map.ts`）
 
 ### `createMapInstance(config?)`
 
@@ -59,8 +136,8 @@ emitter.on('selected-feature', (data) => console.log('选中要素：', data))
 function createMapInstance(config?: Record<string, any>): CustomMap
 ```
 
-| 参数 | 类型 | 默认 | 说明 |
-|---|---|---|---|
+| 参数     | 类型     | 默认 | 说明                                      |
+| -------- | -------- | ---- | ----------------------------------------- |
 | `config` | `object` | `{}` | 透传给 `createMap` → `ol/View` 的视图配置 |
 
 返回：`CustomMap`（OpenLayers `Map` 的扩展，附带 `getLayerByName` / `removeLayerByName` / `changeLayersByNames` 方法与 `activeBaseLayer` 字段）。
@@ -83,7 +160,7 @@ function createMap(config?: Record<string, any>): CustomMap
 ```
 
 | 参数 | 类型 | 默认 | 说明 |
-|---|---|---|---|
+| --- | --- | --- | --- |
 | `config` | `object` | `{}` | `ol/View` 配置；可额外传 `layers` 覆盖默认底图、`baseLayer` 标记当前底图名 |
 
 ```ts
@@ -104,7 +181,7 @@ function getMapInstance(): CustomMap
 function disposeMap(): void
 ```
 
-销毁单例：移除全部 overlay、清空 interaction、移除并释放（`source.dispose()` + `layer.dispose()`）所有图层，`setTarget('')` 后将 `instance` 置为 `undefined`。
+销毁单例：移除全部 overlay、清空 interaction、移除并释放（`source.dispose()` + `layer.dispose()`）所有图层，`setTarget('')` 后将 `instance` 置为 `undefined`。未初始化或重复调用时会安全跳过。
 
 ### `resetMap(config?)`
 
@@ -131,7 +208,7 @@ let instance: CustomMap // 导出变量；未创建时为 undefined
 
 ---
 
-## 二、底图与图层名管理（`base-layer.ts`）
+## 二、底图与图层名管理（`layer/base-layer.ts`）
 
 ### `createBaseLayer(layerName?)`
 
@@ -159,7 +236,7 @@ function createMapWorldLayer(layerName: WorldLayerType, tk?: string): Tile
 ```
 
 | 参数 | 类型 | 默认 | 说明 |
-|---|---|---|---|
+| --- | --- | --- | --- |
 | `layerName` | `WorldLayerType` | — | 形如 `img_c`，内部按 `_` 拆分为图层名与 matrixSet |
 | `tk` | `string` | 内置默认令牌 | 天地图访问令牌，**建议自行传入** |
 
@@ -195,7 +272,10 @@ function removeLayerByName(name: string): void
 ### `changeLayersByNames(activeNames, allLayerNames)`
 
 ```ts
-function changeLayersByNames(activeNames: string[], allLayerNames: string[]): void
+function changeLayersByNames(
+  activeNames: string[],
+  allLayerNames: string[]
+): void
 ```
 
 在 `allLayerNames` 范围内，按 `activeNames` 是否包含来逐一 `setVisible`，实现批量显隐切换。
@@ -206,18 +286,21 @@ changeLayersByNames(['poi-layer'], ['poi-layer', 'line-layer', 'face-layer'])
 
 ---
 
-## 三、矢量图层（`layer-utils.ts`）
+## 三、矢量图层（`layer/vector-layer.ts`）
 
 ### `createBusinessLayer(dataList, config)`
 
 核心矢量图层构造函数：将业务数据组装为 GeoJSON（自动推断线/面几何类型），生成默认/激活样式并写入要素属性，可选开启点击交互。
 
 ```ts
-function createBusinessLayer(dataList: MassData[], config: VectorConfig): VectorLayer
+function createBusinessLayer(
+  dataList: MassData[],
+  config: VectorConfig
+): VectorLayer
 ```
 
 | `config` 关键字段 | 类型 | 说明 |
-|---|---|---|
+| --- | --- | --- |
 | `key` | `string` | 数据中存放坐标数组的字段名 |
 | `isLine` | `boolean` | 是否线图层（影响是否生成填充样式） |
 | `layerName` | `string?` | 图层名（className） |
@@ -233,10 +316,17 @@ function createBusinessLayer(dataList: MassData[], config: VectorConfig): Vector
 
 ```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
+  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)
 ```
@@ -246,8 +336,14 @@ map.addLayer(layer)
 `createBusinessLayer` 的便捷包装，分别固定 `isLine: true` / `isLine: false`。
 
 ```ts
-function createVectorLineLayer(dataList?: MassData[], config: VectorConfig): VectorLayer
-function createVectorFaceLayer(dataList?: MassData[], config: VectorConfig): VectorLayer
+function createVectorLineLayer(
+  dataList?: MassData[],
+  config: VectorConfig
+): VectorLayer
+function createVectorFaceLayer(
+  dataList?: MassData[],
+  config: VectorConfig
+): VectorLayer
 ```
 
 ### `appendFeaturesByLayer(targetLayer, dataList, crsForm?)`
@@ -264,7 +360,7 @@ function appendFeaturesByLayer(
 
 ---
 
-## 四、海量点 MassMarks（`layer-utils.ts`）
+## 四、海量点 MassMarks（`layer/mass-marks.ts`）
 
 ### `buildMassMarksStyles(getImgUrlFn)`
 
@@ -282,14 +378,24 @@ type GetImgUrlFn = (baseUrl: string) => GetImgUrl
 图标地址按 `${markerIcon}-${i}` / `${markerIcon}-${i}-active`（后缀 `.webp`）拼接。
 
 ```ts
-const buildStyles = buildMassMarksStyles((baseUrl) => (name, ext) => `${baseUrl}/${name}${ext}`)
-const styles = buildStyles({ baseUrl: '/icons', markerIcon: 'alarm', markerSize: [32, 32], statusNum: 5 })
+const buildStyles = buildMassMarksStyles(
+  (baseUrl) => (name, ext) => `${baseUrl}/${name}${ext}`
+)
+const styles = buildStyles({
+  baseUrl: '/icons',
+  markerIcon: 'alarm',
+  markerSize: [32, 32],
+  statusNum: 5
+})
 ```
 
 ### `createMassMarksLayer(dataList, styleList?)`
 
 ```ts
-function createMassMarksLayer(dataList: MassData[], styleList?: StyleLike[]): VectorLayer
+function createMassMarksLayer(
+  dataList: MassData[],
+  styleList?: StyleLike[]
+): VectorLayer
 ```
 
 按 `item.style` 索引在 `styleList` 中取样式创建要素图层（`zIndex: 2000`）。图层附带 `_isMassMarksLayer`、`_statusNum`、`_dataList`、`_uuidSet` 等属性。
@@ -301,11 +407,15 @@ function createMassMarksLayer(dataList: MassData[], styleList?: StyleLike[]): Ve
 ```ts
 function addMassMarksLayer(
   getImgUrlFn: GetImgUrlFn
-): (dataList?: MassData[], iconConfig: IconConfig, openClick?: boolean) => VectorLayer
+): (
+  dataList?: MassData[],
+  iconConfig: IconConfig,
+  openClick?: boolean
+) => VectorLayer
 ```
 
 | `iconConfig` 字段 | 类型 | 说明 |
-|---|---|---|
+| --- | --- | --- |
 | `baseUrl` | `string` | 图标根地址 |
 | `markerIcon` | `string` | 图标名前缀 |
 | `markerSize` | `[number, number]` | 图标尺寸 |
@@ -321,7 +431,13 @@ function addMassMarksLayer(
 
 ```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 })
+const layer = add(dataList, {
+  baseUrl: '/icons',
+  markerIcon: 'alarm',
+  markerSize: [32, 32],
+  statusNum: 5,
+  hasLine: true
+})
 ```
 
 ### `addFeaturesByLayer(targetLayer, dataList, config)`
@@ -348,12 +464,15 @@ function updateMarksLayersByStatus(checkedStatusList?: string[]): MassData[]
 
 ---
 
-## 五、聚合图层（`layer-utils.ts`）
+## 五、聚合图层（`layer/cluster-layer.ts`）
 
 ### `createClusterLayer(dataList, config)`
 
 ```ts
-function createClusterLayer(dataList: ClusterData[], config: ClusterConfig): VectorLayer
+function createClusterLayer(
+  dataList: ClusterData[],
+  config: ClusterConfig
+): VectorLayer
 
 type ClusterData = {
   _uuid: string
@@ -377,15 +496,17 @@ type ClusterConfig = {
 
 ```ts
 const cluster = createClusterLayer(dataList, {
-  distance: 80, minDistance: 20,
-  singleStyles: [singlePointStyle], openClick: true
+  distance: 80,
+  minDistance: 20,
+  singleStyles: [singlePointStyle],
+  openClick: true
 })
 map.addLayer(cluster)
 ```
 
 ---
 
-## 六、交互与选中（`layer-utils.ts`）
+## 六、交互与选中（`interaction/select.ts`）
 
 ### `createSelectByLayer(vectorLayer)`
 
@@ -407,12 +528,12 @@ function activeFeatureByUid(uid: string): void
 
 ```ts
 function resetActiveFeature(): void // 清空 overlay + 触发各矢量图层 deselect
-function resetActiveVector(): void  // 清空 overlay + 清空各图层选择交互的要素集合
+function resetActiveVector(): void // 清空 overlay + 清空各图层选择交互的要素集合
 ```
 
 ---
 
-## 七、覆盖物与视野（`layer-utils.ts`）
+## 七、覆盖物与视野（`overlay/overlay.ts`、`map/view-fit.ts`）
 
 ### `createOverlay(config?)`
 
@@ -427,7 +548,7 @@ function createOverlay(config?: import('ol/Overlay').Options): Overlay
 
 ```ts
 function removeOverlays(key?: string): void // 移除带指定属性键的 overlay（默认按 'position'）
-function removeAllLayers(): void            // 移除并释放所有非底图（无 _isBaseLayer）图层 + overlay
+function removeAllLayers(): void // 移除并释放所有非底图（无 _isBaseLayer）图层 + overlay
 ```
 
 ### `createAnimationMarker(imgUrl, data)`
@@ -445,7 +566,7 @@ function setFitViewByCoords(
   coords: Coordinate[],
   mapInstance?: CustomMap,
   fitOptions?: FitOptions | AnimationOptions
-): void   // 单点时 animate 到 zoom 14，多点时 fit 包围盒
+): void // 单点时 animate 到 zoom 14，多点时 fit 包围盒
 
 function setFitViewByGeom(
   geom: SimpleGeometry,
@@ -457,13 +578,16 @@ function setFitViewByLayer(
   layer: VectorLayer,
   mapInstance?: CustomMap,
   fitOptions?: FitOptions
-): void   // 按图层 source 的 extent 自适应
+): void // 按图层 source 的 extent 自适应
 ```
 
 三者默认 `padding: [50,50,50,50]`、`duration: 1000`，可由 `fitOptions` 覆盖。
 
 ```ts
-setFitViewByCoords([[120.1, 30.2], [120.3, 30.4]])
+setFitViewByCoords([
+  [120.1, 30.2],
+  [120.3, 30.4]
+])
 setFitViewByLayer(layer, undefined, { duration: 500 })
 ```
 
@@ -477,7 +601,7 @@ function getLayersDataList(): any[]
 
 ---
 
-## 八、WMTS（`ogc-utils.ts`）
+## 八、WMTS（`layer/ogc-utils.ts`）
 
 ### `createWmtsLayer(serverUrl)`
 
@@ -489,11 +613,11 @@ function createWmtsLayer(
 ): (config: WmtsSourceOptions) => Promise<TileLayer>
 
 type WmtsSourceOptions = {
-  layerName: string   // 形如 'workspace:datastore'
+  layerName: string // 形如 'workspace:datastore'
   style?: string
-  format?: string     // 默认 'image/png'
-  version?: string    // 默认 '1.1.0'
-  matrixSet?: string  // 默认 'EPSG:4326'
+  format?: string // 默认 'image/png'
+  version?: string // 默认 '1.1.0'
+  matrixSet?: string // 默认 'EPSG:4326'
 }
 ```
 
@@ -512,13 +636,67 @@ import { emitter } from 'map-ol-utils' // mitt 实例
 ```
 
 | 事件名 | 载荷 | 触发时机 |
-|---|---|---|
+| --- | --- | --- |
 | `selected-feature` | 要素属性对象 | 要素被选中（`createSelectByLayer` 内触发） |
 | `dynamic-marker` | 动画标注配置 | 选中动态图层（`_isDynamic`）要素 1s 后 |
 
 ---
 
-## 十、类型定义（`types.ts`，`export * from './types'`）
+## 十、扩展能力
+
+以下 API 补充天地图组合、Marker、绘制与 GeoJSON 等能力；`createMapInstance`、`createOverlay`、`disposeMap` 等既有 API 的签名、默认值和行为保持不变。`disposeInstance()` 直接复用 `disposeMap()` 的完整清理语义。
+
+### 天地图组合与栅格处理
+
+```ts
+const { baseImgLayer, baseCiaLayer, baseVecLayer, baseCvaLayer } =
+  baseLayers('你的天地图令牌')
+
+const recoloredLayer = changeLayer(
+  baseImgLayer,
+  [255, 255, 255],
+  [0.05, 0.55, 0.05]
+)
+```
+
+- `baseLayers(tk)`：创建影像、影像注记、矢量、矢量注记四个 XYZ 图层。
+- `changeSource(layer, rgbColorArray, ratioArray, options?)`：创建栅格颜色转换 Source；`options.threads` 可指定线程数。
+- `changeLayer(layer, rgbColorArray, ratioArray, options?)`：把转换 Source 包装为 `VectorImageLayer`；支持相同的线程配置。
+
+`options` 类型为 `{ threads?: number }`。未指定时使用浏览器硬件并发数与 4 的较小值（无法读取时为 2），且至少使用 1 个线程。
+
+### Marker 与选择
+
+```ts
+const markerLayer = createMarkersLayer(markerData, {
+  layerName: 'device-layer',
+  zIndex: 10
+})
+map.addLayer(markerLayer)
+
+const select = createLayerSelectByNames(['device-layer'], handleSelected)
+map.addInteraction(select)
+```
+
+- `createText(item)` / `createIconStyle(item, active?)`：创建 Marker 文本和图标样式。
+- `createMarker(item, config)` / `createMarkersLayer(dataList, config)`：创建单个 Marker 或 Marker 图层。
+- `createElasticMarkerLayer(dataList, config)`：按缩放级别切换 `img`、`smallImg`、`largeImg`。
+- `changeUnselectStyle(featureCollection)`：清空选择集合并恢复未选中样式。
+- `createLayerSelectByNames(layerNames, selectedHandler?, unSelectHandler?)`：按多个图层名选择 Marker。
+- `createMoveMarkerLayer(dataItem, config)`：创建单 Marker 图层并加入当前地图。
+
+### 绘制、GeoJSON 与视野
+
+- `createDrawInteraction(type, vectorLayer, openTip?)`：创建 Draw interaction。
+- `getDrawStyle(feature, drawStyle?)`：为线和面绘制追加长度/面积标签。
+- `createGeoJsonLayer(geoJson, style, config?)`：直接从 GeoJSON 创建矢量图层。
+- `flyToAnimate(center, zoom?)`：使用两段缩放动画飞到目标点。
+
+相关类型包括 `LayerConfig`、`DataItemConfig`、`ElasticDataItemConfig`。
+
+---
+
+## 十一、类型定义（`core/types.ts`，`export * from './core/types'`）
 
 ```ts
 interface CustomMap extends OlMap {
@@ -562,7 +740,7 @@ enum GeometryType {
 ## 构建
 
 ```bash
-pnpm --dir packages/map-utils build   # tsup 产出 esm + cjs + d.ts
+pnpm --dir packages/map-utils build   # tsdown 产出 esm + cjs + d.ts
 pnpm --dir packages/map-utils dev     # watch 模式
 ```