map-ol-utils 0.1.31 → 1.0.0

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

@@ -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`，用于派发要素选中等事件。
+- **扩展能力**：提供天地图组合、栅格着色、标记、绘制量算、GeoJSON 图层和多图层选择能力。
+- **私有 VTS 转换**：通过 `tdt-vts-core` 复用 PK 编解码、私有 Protobuf/MVT 转换和 Web Worker 解码，本包只保留 OpenLayers 适配。
+
+## 项目结构
+
+```text
+packages/map-utils/
+├── src/
+│   ├── core/                    # 类型、常量、事件总线与地图上下文
+│   ├── interaction/             # 绘制和要素选择交互
+│   ├── layer/                   # 底图、矢量、聚合、海量点、WMTS 与图层生命周期
+│   ├── map/                     # 地图实例管理与视野适配
+│   ├── overlay/                 # Overlay 与动画标注
+│   ├── tdt-vts/                 # 天地图私有 VTS 的公共重导出与 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` 是**对等依赖**（要求 `^10.10.0`），需由宿主项目安装。`tdt-vts-core` 是普通依赖，由包管理器自动安装。
 
 ## 快速开始
 
@@ -43,13 +66,34 @@ map.addLayer(layer)
 emitter.on('selected-feature', (data) => console.log('选中要素：', data))
 ```
 
+## 天地图私有 VTS
+
+传入 Mapbox/MapLibre Style v8 JSON 地址或已加载的样式对象，创建 OpenLayers 图层：
+
+```ts
+import { createTdtVtsLayer } from 'map-ol-utils'
+
+const layer = await createTdtVtsLayer({
+  token: 'YOUR_TDT_TOKEN',
+  hosts: ['https://tile0.tianditu.gov.cn'],
+  style: '/styles/tdt-style.json'
+})
+
+map.addLayer(layer)
+layer.dispose() // 同时释放解码 Worker
+```
+
+`hosts` 与 `style` 均为必填项。传入地址时，本包会请求并校验 Style v8 JSON，服务端需允许当前页面跨域访问；也可以直接传入包含 `sources` 和 `layers` 的样式对象。
+
+业务调用只需要 `createTdtVtsLayer()`；底层转换 API 保留用于兼容已有调用。
+
 ---
 
-# API 详解
+# 接口（API）详解
 
-> 约定：下文「实例方法默认 `mapInstance = instance`」表示该参数缺省时使用模块单例；调用前请确保已 `createMapInstance` / `createMap`。
+> 约定：独立工具函数默认操作 `createMapInstance()` 创建的模块单例；`createMap()` 返回独立地图，其挂载的图层方法只操作自身。
 
-## 一、地图实例（`create-map.ts`）
+## 一、地图实例（`map/create-map.ts`）
 
 ### `createMapInstance(config?)`
 
@@ -59,8 +103,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` 字段）。
@@ -72,7 +116,7 @@ map.setTarget('map')
 
 ### `createMap(config?)`
 
-始终新建一个 `CustomMap`。默认挂载杭州规自暗色底图，禁用旋转/双击缩放，并在 `pointermove` 时根据是否命中要素切换鼠标指针。`config` 与以下默认值合并后作为 `ol/View` 选项：
+始终新建一个 `CustomMap`。默认挂载杭州规自暗色底图，禁用旋转/双击缩放，并在 `pointermove` 时根据是否命中要素切换鼠标指针；挂载的图层查询、切换和删除方法绑定到当前地图。`config` 与以下默认值合并后作为 `ol/View` 选项：
 
 ```ts
 function createMap(config?: Record<string, any>): CustomMap
@@ -83,7 +127,7 @@ function createMap(config?: Record<string, any>): CustomMap
 ```
 
 | 参数 | 类型 | 默认 | 说明 |
-|---|---|---|---|
+| --- | --- | --- | --- |
 | `config` | `object` | `{}` | `ol/View` 配置；可额外传 `layers` 覆盖默认底图、`baseLayer` 标记当前底图名 |
 
 ```ts
@@ -104,7 +148,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?)`
 
@@ -131,7 +175,7 @@ let instance: CustomMap // 导出变量；未创建时为 undefined
 
 ---
 
-## 二、底图与图层名管理（`base-layer.ts`）
+## 二、底图与图层名管理（`layer/base-layer.ts`）
 
 ### `createBaseLayer(layerName?)`
 
@@ -159,7 +203,7 @@ function createMapWorldLayer(layerName: WorldLayerType, tk?: string): Tile
 ```
 
 | 参数 | 类型 | 默认 | 说明 |
-|---|---|---|---|
+| --- | --- | --- | --- |
 | `layerName` | `WorldLayerType` | — | 形如 `img_c`，内部按 `_` 拆分为图层名与 matrixSet |
 | `tk` | `string` | 内置默认令牌 | 天地图访问令牌，**建议自行传入** |
 
@@ -190,12 +234,15 @@ function getLayerByName(name: string): Layer<Source> | undefined
 function removeLayerByName(name: string): void
 ```
 
-查找匹配图层并释放其 source、从地图移除并 `dispose`。
+查找匹配图层并释放其数据源、从地图移除并执行 `dispose`。
 
 ### `changeLayersByNames(activeNames, allLayerNames)`
 
 ```ts
-function changeLayersByNames(activeNames: string[], allLayerNames: string[]): void
+function changeLayersByNames(
+  activeNames: string[],
+  allLayerNames: string[]
+): void
 ```
 
 在 `allLayerNames` 范围内，按 `activeNames` 是否包含来逐一 `setVisible`，实现批量显隐切换。
@@ -206,18 +253,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 +283,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,13 +303,19 @@ 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?)`
 
-向已有矢量图层追加要素（同步更新其 `_uuidSet`），复用图层 `_vectorConfig` 生成样式。
+向已有矢量图层追加要素（同步更新其 `_uuidSet`），复用图层 `_vectorConfig` 生成样式；未传 `crsForm` 时继承图层配置的源坐标系。
 
 ```ts
 function appendFeaturesByLayer(
@@ -264,7 +327,7 @@ function appendFeaturesByLayer(
 
 ---
 
-## 四、海量点 MassMarks（`layer-utils.ts`）
+## 四、海量点 MassMarks（`layer/mass-marks.ts`）
 
 ### `buildMassMarksStyles(getImgUrlFn)`
 
@@ -282,14 +345,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 +374,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 +398,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)`
@@ -336,7 +419,7 @@ function addFeaturesByLayer(
 ): void
 ```
 
-`config.clear` 为 `true` 时先清空 source 再添加。
+`config.clear` 为 `true` 时先清空数据源再添加。
 
 ### `updateMarksLayersByStatus(checkedStatusList?)`
 
@@ -348,12 +431,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 +463,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 +495,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 +515,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)`
@@ -436,7 +524,7 @@ function removeAllLayers(): void            // 移除并释放所有非底图（
 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`
 
@@ -445,7 +533,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 +545,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,11 +568,11 @@ function getLayersDataList(): any[]
 
 ---
 
-## 八、WMTS（`ogc-utils.ts`）
+## 八、WMTS（`layer/ogc-utils.ts`）
 
 ### `createWmtsLayer(serverUrl)`
 
-柯里化函数：先传 GeoServer 服务地址，返回的方法按 `WmtsSourceOptions` 解析 GetCapabilities 并构建图层（内部缓存 capabilities，重复调用不重复请求）。
+柯里化函数：先传 GeoServer 服务地址，返回的方法按 `WmtsSourceOptions` 解析 GetCapabilities 并构建图层。仅成功响应会进入 capabilities 缓存；HTTP 非成功状态直接抛错，后续调用仍可重试。
 
 ```ts
 function createWmtsLayer(
@@ -489,11 +580,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 +603,67 @@ import { emitter } from 'map-ol-utils' // mitt 实例
 ```
 
 | 事件名 | 载荷 | 触发时机 |
-|---|---|---|
+| --- | --- | --- |
 | `selected-feature` | 要素属性对象 | 要素被选中（`createSelectByLayer` 内触发） |
 | `dynamic-marker` | 动画标注配置 | 选中动态图层（`_isDynamic`）要素 1s 后 |
 
 ---
 
-## 十、类型定义（`types.ts`，`export * from './types'`）
+## 十、扩展能力
+
+以下 API 补充天地图组合、标记、绘制与 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?)`：创建栅格颜色转换数据源；`options.threads` 可指定线程数。
+- `changeLayer(layer, rgbColorArray, ratioArray, options?)`：把转换数据源包装为 `VectorImageLayer`；支持相同的线程配置。
+
+`options` 类型为 `{ threads?: number }`。未指定时使用浏览器硬件并发数与 4 的较小值（无法读取时为 2），且至少使用 1 个线程。
+
+### 标记与选择
+
+```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?)`：创建标记文本和图标样式。
+- `createMarker(item, config)` / `createMarkersLayer(dataList, config)`：创建单个标记或标记图层。
+- `createElasticMarkerLayer(dataList, config)`：按缩放级别切换 `img`、`smallImg`、`largeImg`，通过库的生命周期方法移除时自动解绑缩放监听。
+- `changeUnselectStyle(featureCollection)`：清空选择集合并恢复未选中样式。
+- `createLayerSelectByNames(layerNames, selectedHandler?, unSelectHandler?)`：按多个图层名选择标记。
+- `createMoveMarkerLayer(dataItem, config)`：创建单标记图层并加入当前地图。
+
+### 绘制、GeoJSON 与视野
+
+- `createDrawInteraction(type, vectorLayer, openTip?)`：创建绘制交互。
+- `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 {
@@ -557,17 +702,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   # tsup 产出 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`，正式项目请传入自有令牌。