map-ol-utils 0.2.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tomxuetao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -13,8 +13,8 @@
 - **聚合图层**：基于 `ol/source/Cluster`，半径/颜色随聚合数量动态计算。
 - **坐标系转换**：内部统一通过 [`gcoord`](https://github.com/hujiulong/gcoord) 转换到 `WGS84`（`EPSG:4326`）。
 - **事件总线**：内置 `mitt` 实例 `emitter`，用于派发要素选中等事件。
-- **扩展能力**：提供天地图组合、栅格着色、Marker、绘制量算、GeoJSON 图层和多图层选择能力。
-- **私有 VTS 转换**：支持 PK 编解码、私有 Protobuf 字段与 Geometry 命令转换、样式合并和 Web Worker 解码。
+- **扩展能力**：提供天地图组合、栅格着色、标记、绘制量算、GeoJSON 图层和多图层选择能力。
+- **私有 VTS 转换**：通过 `tdt-vts-core` 复用 PK 编解码、私有 Protobuf/MVT 转换和 Web Worker 解码，本包只保留 OpenLayers 适配。
 
 ## 项目结构
 
@@ -26,7 +26,7 @@ packages/map-utils/
 │   ├── layer/                   # 底图、矢量、聚合、海量点、WMTS 与图层生命周期
 │   ├── map/                     # 地图实例管理与视野适配
 │   ├── overlay/                 # Overlay 与动画标注
-│   ├── tdt-vts/                 # 天地图私有 VTS 加载、转换、Worker 与 OL 适配
+│   ├── tdt-vts/                 # 天地图私有 VTS 的公共重导出与 OL 适配
 │   └── index.ts                 # 唯一公共 API 入口
 ├── test/
 │   ├── architecture.test.ts     # 模块边界与架构约束
@@ -43,7 +43,7 @@ packages/map-utils/
 pnpm add map-ol-utils ol gcoord
 ```
 
-`ol` 是 **peerDependency**（要求 `^10.10.0`），需由宿主项目安装。
+`ol` 是**对等依赖**（要求 `^10.10.0`），需由宿主项目安装。`tdt-vts-core` 是普通依赖，由包管理器自动安装。
 
 ## 快速开始
 
@@ -68,63 +68,30 @@ emitter.on('selected-feature', (data) => console.log('选中要素：', data))
 
 ## 天地图私有 VTS
 
-直接加载并转换为标准 Mapbox Vector Tile：
+传入 Mapbox/MapLibre Style v8 JSON 地址或已加载的样式对象，创建 OpenLayers 图层：
 
 ```ts
-import { createTdtVtsUrl, loadAndNormalizeTdtVts } from 'map-ol-utils'
+import { createTdtVtsLayer } from 'map-ol-utils'
 
-const url = createTdtVtsUrl([3, 0, 4], {
+const layer = await createTdtVtsLayer({
   token: 'YOUR_TDT_TOKEN',
-  hosts: [
-    'https://tile0.tianditu.gov.cn',
-    'https://tile1.tianditu.gov.cn',
-    'https://tile2.tianditu.gov.cn'
-  ]
+  hosts: ['https://tile0.tianditu.gov.cn'],
+  style: '/styles/tdt-style.json'
 })
 
-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()
+map.addLayer(layer)
+layer.dispose() // 同时释放解码 Worker
 ```
 
-`decoderOptions.requestTimeoutMs` 默认值为 30 秒。`source.dispose()` 与 `decoder.dispose()` 均可安全重复调用；前者会自动调用后者。
-
-相关公共 API：
+`hosts` 与 `style` 均为必填项。传入地址时，本包会请求并校验 Style v8 JSON，服务端需允许当前页面跨域访问；也可以直接传入包含 `sources` 和 `layers` 的样式对象。
 
-- `encodeTdtPk()` / `decodeTdtPk()` / `createTdtVtsUrl()`
-- `loadAndNormalizeTdtVts()` / `normalizePrivateMvt()`
-- `TdtDecoderWorkerClient` / `createTdtVectorSource()`
-- `loadTdtStyleBundle()` / `mergeTdtStyleLayers()`
+业务调用只需要 `createTdtVtsLayer()`；底层转换 API 保留用于兼容已有调用。
 
 ---
 
-# API 详解
+# 接口（API）详解
 
-> 约定：下文「实例方法默认 `mapInstance = instance`」表示该参数缺省时使用模块单例；调用前请确保已 `createMapInstance` / `createMap`。
+> 约定：独立工具函数默认操作 `createMapInstance()` 创建的模块单例；`createMap()` 返回独立地图，其挂载的图层方法只操作自身。
 
 ## 一、地图实例（`map/create-map.ts`）
 
@@ -149,7 +116,9 @@ map.setTarget('map')
 
 ### `createMap(config?)`
 
-始终新建一个 `CustomMap`。默认挂载杭州规自暗色底图，禁用旋转/双击缩放，并在 `pointermove` 时根据是否命中要素切换鼠标指针。`config` 与以下默认值合并后作为 `ol/View` 选项：
+始终新建一个 `CustomMap`。默认挂载杭州规自暗色底图，禁用旋转/双击缩放，并在 `pointermove` 时根据是否命中要素切换鼠标指针；挂载的图层查询、切换和删除方法绑定到当前地图。`config` 与以下默认值合并后作为 `ol/View` 选项：
+
+鼠标指针更新按帧合并；延迟回调执行时若地图已解除目标元素，会跳过命中检测与样式更新。
 
 ```ts
 function createMap(config?: Record<string, any>): CustomMap
@@ -181,7 +150,7 @@ function getMapInstance(): CustomMap
 function disposeMap(): void
 ```
 
-销毁单例：移除全部 overlay、清空 interaction、移除并释放（`source.dispose()` + `layer.dispose()`）所有图层，`setTarget('')` 后将 `instance` 置为 `undefined`。未初始化或重复调用时会安全跳过。
+销毁单例：移除全部覆盖物、清空交互、移除并释放（`source.dispose()` + `layer.dispose()`）所有图层，`setTarget('')` 后将 `instance` 置为 `undefined`。未初始化或重复调用时会安全跳过。
 
 ### `resetMap(config?)`
 
@@ -267,7 +236,7 @@ function getLayerByName(name: string): Layer<Source> | undefined
 function removeLayerByName(name: string): void
 ```
 
-查找匹配图层并释放其 source、从地图移除并 `dispose`。
+查找匹配图层并释放其数据源、从地图移除并执行 `dispose`。
 
 ### `changeLayersByNames(activeNames, allLayerNames)`
 
@@ -348,7 +317,7 @@ function createVectorFaceLayer(
 
 ### `appendFeaturesByLayer(targetLayer, dataList, crsForm?)`
 
-向已有矢量图层追加要素（同步更新其 `_uuidSet`），复用图层 `_vectorConfig` 生成样式。
+向已有矢量图层追加要素（同步更新其 `_uuidSet`），复用图层 `_vectorConfig` 生成样式；未传 `crsForm` 时继承图层配置的源坐标系。
 
 ```ts
 function appendFeaturesByLayer(
@@ -452,7 +421,7 @@ function addFeaturesByLayer(
 ): void
 ```
 
-`config.clear` 为 `true` 时先清空 source 再添加。
+`config.clear` 为 `true` 时先清空数据源再添加。
 
 ### `updateMarksLayersByStatus(checkedStatusList?)`
 
@@ -557,7 +526,7 @@ function removeAllLayers(): void // 移除并释放所有非底图（无 _isBase
 function createAnimationMarker(imgUrl: string, data: MassData): void
 ```
 
-以 `data.lnglat`（经 `data.crsForm` → `WGS84` 转换）创建动画标注 Overlay，先移除已有动画标注。`data` 中读取 `width` / `height` / `lnglat` / `crsForm`。
+以 `data.lnglat`（经 `data.crsForm` → `WGS84` 转换）创建动画标注覆盖物，先移除已有动画标注。`data` 中读取 `width` / `height` / `lnglat` / `crsForm`。
 
 ### `setFitViewByCoords` / `setFitViewByGeom` / `setFitViewByLayer`
 
@@ -605,7 +574,7 @@ function getLayersDataList(): any[]
 
 ### `createWmtsLayer(serverUrl)`
 
-柯里化函数：先传 GeoServer 服务地址，返回的方法按 `WmtsSourceOptions` 解析 GetCapabilities 并构建图层（内部缓存 capabilities，重复调用不重复请求）。
+柯里化函数：先传 GeoServer 服务地址，返回的方法按 `WmtsSourceOptions` 解析 GetCapabilities 并构建图层。仅成功响应会进入 capabilities 缓存；HTTP 非成功状态直接抛错，后续调用仍可重试。
 
 ```ts
 function createWmtsLayer(
@@ -644,7 +613,7 @@ import { emitter } from 'map-ol-utils' // mitt 实例
 
 ## 十、扩展能力
 
-以下 API 补充天地图组合、Marker、绘制与 GeoJSON 等能力；`createMapInstance`、`createOverlay`、`disposeMap` 等既有 API 的签名、默认值和行为保持不变。`disposeInstance()` 直接复用 `disposeMap()` 的完整清理语义。
+以下 API 补充天地图组合、标记、绘制与 GeoJSON 等能力；`createMapInstance`、`createOverlay`、`disposeMap` 等既有 API 的签名、默认值和行为保持不变。`disposeInstance()` 直接复用 `disposeMap()` 的完整清理语义。
 
 ### 天地图组合与栅格处理
 
@@ -660,12 +629,12 @@ const recoloredLayer = changeLayer(
 ```
 
 - `baseLayers(tk)`：创建影像、影像注记、矢量、矢量注记四个 XYZ 图层。
-- `changeSource(layer, rgbColorArray, ratioArray, options?)`：创建栅格颜色转换 Source；`options.threads` 可指定线程数。
-- `changeLayer(layer, rgbColorArray, ratioArray, options?)`：把转换 Source 包装为 `VectorImageLayer`；支持相同的线程配置。
+- `changeSource(layer, rgbColorArray, ratioArray, options?)`：创建栅格颜色转换数据源；`options.threads` 可指定线程数。
+- `changeLayer(layer, rgbColorArray, ratioArray, options?)`：把转换数据源包装为 `VectorImageLayer`；支持相同的线程配置。
 
 `options` 类型为 `{ threads?: number }`。未指定时使用浏览器硬件并发数与 4 的较小值（无法读取时为 2），且至少使用 1 个线程。
 
-### Marker 与选择
+### 标记与选择
 
 ```ts
 const markerLayer = createMarkersLayer(markerData, {
@@ -678,16 +647,16 @@ 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`。
+- `createText(item)` / `createIconStyle(item, active?)`：创建标记文本和图标样式。
+- `createMarker(item, config)` / `createMarkersLayer(dataList, config)`：创建单个标记或标记图层。
+- `createElasticMarkerLayer(dataList, config)`：按缩放级别切换 `img`、`smallImg`、`largeImg`，通过库的生命周期方法移除时自动解绑缩放监听。
 - `changeUnselectStyle(featureCollection)`：清空选择集合并恢复未选中样式。
-- `createLayerSelectByNames(layerNames, selectedHandler?, unSelectHandler?)`：按多个图层名选择 Marker。
-- `createMoveMarkerLayer(dataItem, config)`：创建单 Marker 图层并加入当前地图。
+- `createLayerSelectByNames(layerNames, selectedHandler?, unSelectHandler?)`：按多个图层名选择标记。
+- `createMoveMarkerLayer(dataItem, config)`：创建单标记图层并加入当前地图。
 
 ### 绘制、GeoJSON 与视野
 
-- `createDrawInteraction(type, vectorLayer, openTip?)`：创建 Draw interaction。
+- `createDrawInteraction(type, vectorLayer, openTip?)`：创建绘制交互。
 - `getDrawStyle(feature, drawStyle?)`：为线和面绘制追加长度/面积标签。
 - `createGeoJsonLayer(geoJson, style, config?)`：直接从 GeoJSON 创建矢量图层。
 - `flyToAnimate(center, zoom?)`：使用两段缩放动画飞到目标点。
@@ -735,17 +704,19 @@ enum GeometryType {
 
 ## 图层约定属性
 
-工具库通过图层 properties 标记元信息，维护时请保持一致：`_isBaseLayer`、`_layerName`、`_isCustom`、`_isVectorLayer`、`_isClusterLayer`、`_isMassMarksLayer`、`_selectInteraction`、`_uuidSet`、`_dataList`、`_vectorConfig`、`_isAutoFit`、`_massMarksStyles`、`_statusNum`。
+工具库通过图层 properties 标记元信息，维护时请保持一致：`_isBaseLayer`、`_layerName`、`_isCustom`、`_isVectorLayer`、`_isClusterLayer`、`_isMassMarksLayer`、`_selectInteraction`、`_resolutionChangeKey`、`_uuidSet`、`_dataList`、`_vectorConfig`、`_isAutoFit`、`_massMarksStyles`、`_statusNum`。
 
 ## 构建
 
 ```bash
-pnpm --dir packages/map-utils build   # tsdown 产出 esm + cjs + d.ts
-pnpm --dir packages/map-utils dev     # watch 模式
+pnpm --dir packages/map-utils build       # tsdown 产出 esm + cjs + d.ts（压缩）
+pnpm --dir packages/map-utils check:types # tsc --noEmit
+pnpm --dir packages/map-utils test        # build + check:types + node:test
+pnpm --dir packages/map-utils dev         # watch 模式
 ```
 
 ## 注意事项
 
-- **单例副作用**：绝大多数函数依赖模块级 `instance`，请先 `createMapInstance` / `createMap` 再调用其他工具；`disposeMap` 后 `instance` 为 `undefined`。
+- **单例副作用**：绝大多数独立函数依赖模块级 `instance`，请先调用 `createMapInstance`；`createMap` 只创建独立地图，`disposeMap` 后 `instance` 为 `undefined`。
 - **坐标系**：输入数据可通过 `config.crsForm` / `data.crsForm` 指定源坐标系，内部统一转为 `WGS84`。
 - **天地图令牌**：`createMapWorldLayer` / `createZheJiangLayer` 内置了默认 `tk`，正式项目请传入自有令牌。