ym-gis-2d 1.0.49 → 1.0.51

package/API.md

@@ -0,0 +1,789 @@
+# ym-gis-2d API 文档
+
+> 基于 [OpenLayers 9](https://openlayers.org/) 封装的二维 GIS 核心库，提供地图初始化、多源图层加载、空间查询、要素编辑与几何运算等能力。  
+> 当前版本：`1.0.49`  
+> npm 包名：`ym-gis-2d`
+
+---
+
+## 目录
+
+- [简介](#简介)
+- [安装与依赖](#安装与依赖)
+- [快速开始](#快速开始)
+- [模块导入方式](#模块导入方式)
+- [核心类 OLMap](#核心类-olmap)
+- [图层配置 IMapService](#图层配置-imapservice)
+- [支持的图层类型](#支持的图层类型)
+- [要素管理 FeatureManager](#要素管理-featuremanager)
+- [地图交互 Interaction](#地图交互-interaction)
+- [地图控件 Control](#地图控件-control)
+- [服务元数据 capabilities](#服务元数据-capabilities)
+- [空间查询 tasks](#空间查询-tasks)
+- [几何工具 GeometryUtil](#几何工具-geometryutil)
+- [坐标系 RegisterProjUtil](#坐标系-registerprojutil)
+- [KML 转换](#kml-转换)
+- [类型定义 entity](#类型定义-entity)
+- [完整示例](#完整示例)
+- [注意事项](#注意事项)
+
+---
+
+## 简介
+
+`ym-gis-2d` 是对 OpenLayers 的业务封装，主要能力包括：
+
+| 能力 | 说明 |
+|------|------|
+| 地图视图 | 默认 CGCS2000（EPSG:4490），支持中心点、范围、缩放级别等初始化 |
+| 图层加载 | ArcGIS / GeoServer / 天地图 / XYZ 瓦片等多种服务 |
+| 临时矢量层 | 点/线/面三套临时图层，用于绘制、选中、定位高亮 |
+| 空间编辑 | 绘制、选择、修改、吸附、分割、挖除、修补等交互 |
+| 空间查询 | 支持 ArcGIS 与 GeoServer 服务的属性/空间查询 |
+| 几何运算 | WKT/GeoJSON 转换、缓冲、求交、合并、分割等 |
+| 服务解析 | 自动读取 WMS/WMTS/WFS/ArcGIS MapServer 元数据 |
+
+推荐与 UI 组件库 `ym-giswidget-2d` 配合使用，也可单独集成到 Vue / React / 原生 JS 项目。
+
+---
+
+## 安装与依赖
+
+```bash
+npm install ym-gis-2d
+# 或
+pnpm add ym-gis-2d
+```
+
+###  peer 依赖
+
+本包内部依赖以下库，请确保项目中版本兼容：
+
+| 依赖 | 用途 |
+|------|------|
+| `ol` ^9.x | 地图渲染核心 |
+| `axios` | HTTP 请求 |
+| `proj4` | 坐标系转换 |
+| `@turf/turf` | 部分几何运算 |
+| `jsts` | 拓扑运算（分割、合并等） |
+
+### 样式引入
+
+地图组件会自动引入 OpenLayers 与包内样式，若样式未生效，请手动引入：
+
+```typescript
+import 'ol/ol.css';
+import 'ym-gis-2d/assets/main.css';
+```
+
+---
+
+## 快速开始
+
+```html
+<div id="map" style="width: 100%; height: 500px;"></div>
+```
+
+```typescript
+import OLMap from 'ym-gis-2d/mapView/Map';
+import type { IMapService } from 'ym-gis-2d/entity';
+
+// 1. 创建地图（默认 EPSG:4490，中心合肥附近）
+const map = new OLMap('map', {
+  projection: 4490,
+  center: [117.22, 31.82],
+  zoom: 10,
+  extent: [89.7, 26.7, 94.8, 29.8], // 可选：初始 fit 到范围
+});
+
+// 2. 加载天地图矢量
+const vecLayer: IMapService = {
+  id: 'tdt-vec',
+  title: '天地图矢量',
+  url: 'http://t0.tianditu.gov.cn/vec_c/wmts?tk=YOUR_TOKEN',
+  sublayers: ['vec'],
+  layerType: 'tdt-c',
+  opacity: 1,
+  mapIndex: 0,
+  checked: true,
+  thumbnail: '',
+};
+
+await map.addMapLayer(vecLayer);
+
+// 3. 叠加 WKT 并定位
+map.addWKT(
+  'POINT(91.1 29.6)',
+  'EPSG:4490',
+  'marker',
+  true,
+  { name: '拉萨' },
+  { color: '#f03437', opacity: 0.5, outlineColor: 'red', outlineWidth: 2 }
+);
+```
+
+---
+
+## 模块导入方式
+
+包采用**子路径导入**（与源码目录结构一致），常用入口如下：
+
+```typescript
+// 地图
+import OLMap, { OlMapOptions, ChangeLayerEvent } from 'ym-gis-2d/mapView/Map';
+import OLView from 'ym-gis-2d/mapView/View';
+
+// 类型
+import type { IMapService, IMapServiceTree, ILayerField } from 'ym-gis-2d/entity';
+import Feature from 'ym-gis-2d/entity/Feature';
+import type IStyle from 'ym-gis-2d/entity/style/IStyle';
+
+// 要素 / 交互 / 工具
+import FeatureManager from 'ym-gis-2d/feature/FeatureManager';
+import Draw from 'ym-gis-2d/interaction/Draw';
+import Select from 'ym-gis-2d/interaction/Select';
+import { selectFeaturesByGeo } from 'ym-gis-2d/utils/tasks';
+import { fromWKT, toWKT, getArea, getLength } from 'ym-gis-2d/utils/GeometryUtil';
+import { getWmtsLayers, getWmsLayers } from 'ym-gis-2d/capabilities';
+import { toKml, toGeoJSON } from 'ym-gis-2d/conver/kml';
+```
+
+> 根入口 `ym-gis-2d` 仅导出 `Map2D` 别名，实际项目请使用上述子路径。
+
+---
+
+## 核心类 OLMap
+
+`OLMap` 继承自 `ol/Map`，是地图操作的中心入口。
+
+### 构造函数
+
+```typescript
+new OLMap(
+  element: string | HTMLElement,
+  options?: OlMapOptions,
+  view?: OLView
+)
+```
+
+#### OlMapOptions
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `projection` | `number` | `4490` | 坐标系 WKID，如 4490、4326 |
+| `center` | `number[]` | `[117.22, 31.82]` | 地图中心 `[x, y]` |
+| `extent` | `number[]` | - | 初始范围 `[xmin, ymin, xmax, ymax]`，设置后自动 fit |
+| `zoom` | `number` | `10` | 初始缩放级别 |
+| `minZoom` | `number` | `0` | 最小缩放 |
+| `maxZoom` | `number` | `28` | 最大缩放 |
+| `minResolution` | `number` | - | 最小分辨率 |
+| `maxResolution` | `number` | - | 最大分辨率 |
+| `constrainResolution` | `boolean` | `false` | 是否强制整数缩放级别 |
+
+### 实例属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `currentEditLayer` | `IMapService` | 当前编辑目标图层，配合 FeatureManager 使用 |
+| `interactionManager` | `InteractionManager` | 交互管理器 |
+| `controlManager` | `ControlManager` | 控件管理器 |
+
+### 图层方法
+
+| 方法 | 说明 |
+|------|------|
+| `addMapLayer(layerInfo)` | 按 `layerType` 异步创建并添加图层 |
+| `addMapLayers(layerInfo[])` | 批量添加图层 |
+| `addLayer(layer, fitLayer?)` | 直接添加 OpenLayers 图层 |
+| `removeLayerById(id)` | 按 id 移除图层 |
+| `removeLayerByIds(ids[])` | 批量移除 |
+| `getLayerById(id)` | 按 id 查找图层 |
+| `getLayerByLayerTag(layerTag)` | 按 layerTag 查找 |
+| `getLayersByIds(ids[])` | 批量查找 |
+| `fitLayer(layer)` | 缩放到图层范围 |
+| `fitLayerById(id)` | 按 id 缩放 |
+| `fitFilterByLayerTag(layerTag, filter, isSelected?, tag?)` | 查询并定位到过滤结果 |
+| `refresh()` | 刷新地图渲染 |
+
+### WKT / 定位方法
+
+| 方法 | 说明 |
+|------|------|
+| `addWKT(wkt, proj, tag?, location?, properties?, style?)` | 添加 WKT 到临时图层 |
+| `addWKTs(wkts[], proj, tag?, location?, style?, properties?)` | 批量添加 WKT |
+| `locationWKT(wkt, proj?, ratio?, isFlash?)` | 定位到 WKT |
+| `locationWKTs(wkts[], proj?, ratio?, isFlash?)` | 定位到多个 WKT |
+| `locationGeometry(geometry, proj?, ratio?, isFlash?)` | 定位到 Geometry |
+| `locationGeometrys(geometrys[], proj?, ratio?, isFlash?)` | 定位到多个 Geometry |
+
+#### addWKT 参数示例
+
+```typescript
+map.addWKT(
+  'POLYGON((117.0 31.0, 117.1 31.0, 117.1 31.1, 117.0 31.1, 117.0 31.0))',
+  'EPSG:4490',
+  'plot-001',          // tag：用于后续按标签清除
+  true,                // 是否自动定位
+  { id: 1 },           // 属性
+  {
+    color: 'rgba(255,0,0,0.2)',
+    opacity: 0.2,
+    outlineColor: 'red',
+    outlineWidth: 2,
+  }
+);
+```
+
+### 临时图层
+
+| 方法 | 说明 |
+|------|------|
+| `getPointTempLayer()` | 临时点图层 |
+| `getLineTempLayer()` | 临时线图层 |
+| `getPolygonTempLayer()` | 临时面图层 |
+| `getTempLayerByGeoType(geoType)` | 按几何类型获取临时层 |
+| `getTempLayerById(id)` | 按 id 获取/创建临时层 |
+| `sortTemLayer()` | 调整临时层叠放顺序 |
+
+### 其他方法
+
+| 方法 | 说明 |
+|------|------|
+| `getExtent()` | 获取当前视图范围 |
+| `createOverlay(id, element?)` | 创建地图 Overlay |
+| `resetViewProjection(projection)` | 切换视图坐标系，如 `'EPSG:4326'` |
+| `getView()` | 返回扩展的 `OLView` 实例 |
+
+### 图层变更事件
+
+添加/移除图层时会派发 `ChangeLayerEvent`：
+
+```typescript
+map.on('changelayer', (evt: ChangeLayerEvent) => {
+  console.log(evt.changetype); // 'add' | 'remove' | 'update'
+  console.log(evt.layerIds);
+});
+```
+
+---
+
+## 图层配置 IMapService
+
+图层统一使用 `IMapService` 描述，核心字段如下：
+
+```typescript
+interface IMapService {
+  id: string;              // 唯一 id
+  title: string;           // 显示名称
+  url?: string;            // 服务地址
+  sublayers?: string[];    // 子图层名 / 图层索引
+  layerType?: string;      // 服务类型（见下表）
+  layerTypeName?: string;  // 类型名称
+  layerTag?: string;       // 业务标识，用于查询/过滤
+  mapIndex?: number;       // 图层层级（zIndex）
+  opacity?: number;        // 透明度 0~1
+  geometryType?: number;   // 1 点 / 2 线 / 3 面
+  editType?: boolean;      // 是否可编辑
+  selectIndex?: string;    // 空间查询图层名
+  tableName?: string;      // 数据源表名
+  primaryKey?: string;     // 主键字段
+  loadFilter?: string;     // 加载过滤 CQL/SQL
+  minScale?: number;       // 最小显示比例尺（-1 不限）
+  maxScale?: number;       // 最大显示比例尺（-1 不限）
+  checked?: boolean;       // 是否默认加载
+  thumbnail: string;       // 缩略图路径
+  legend?: ILegend[];      // 自定义图例
+  showLegend?: boolean;
+  parentId?: string;       // 目录树父节点
+  showIndex?: number;      // 目录树排序
+}
+```
+
+---
+
+## 支持的图层类型
+
+通过 `map.addMapLayer()` 加载，`layerType` 取值如下：
+
+| layerType | 说明 | url 示例 | sublayers |
+|-----------|------|----------|-----------|
+| `tdt-c` | 天地图 WMTS（4490） | `http://t0.tianditu.gov.cn/vec_c/wmts?tk=xxx` | `['vec']` / `['img']` / `['cva']` |
+| `tile` | XYZ 瓦片 | `http://host/tile/{x}/{y}/{z}.png` | - |
+| `geoserver-wms` | GeoServer WMS | `http://host/geoserver/wms` | `['workspace:layer']` |
+| `geoserver-wmts` | GeoServer WMTS | `http://host/geoserver/gwc/service/wmts` | `['layer']` |
+| `geoserver-wfs` | GeoServer WFS 矢量 | `http://host/geoserver/wfs` | `['workspace:layer']` |
+| `geoserver-vector-tile` | GeoServer 矢量切片 | WMTS 地址 | `['layer']` |
+| `arcgis-dynamic` | ArcGIS 动态地图 | MapServer 根地址 | 图层 id 字符串数组 |
+| `arcgis-tile` | ArcGIS 切片 | MapServer 根地址 | - |
+| `arcgis-feature` | ArcGIS 要素 | MapServer 根地址 | 图层 id 数组 |
+| `arcgis-wms` | ArcGIS WMS | WMS 地址 | `['layer']` |
+| `arcgis-wmts` | ArcGIS WMTS | WMTS 地址 | `['layer']` |
+| `supermap-rest` | 超图 iServer REST 地图 | `http://host/iserver/services/map-xxx/rest/maps/mapName` 或 `.rjson` 地址 | 可选，url 为 maps 根地址时传地图名 |
+
+### 天地图示例
+
+```typescript
+await map.addMapLayer({
+  id: '001',
+  title: '天地图矢量',
+  url: 'http://t0.tianditu.gov.cn/vec_c/wmts?tk=YOUR_TOKEN',
+  sublayers: ['vec'],
+  layerType: 'tdt-c',
+  opacity: 1,
+  mapIndex: 0,
+  checked: true,
+  thumbnail: './img/vec.png',
+});
+```
+
+### GeoServer WMS 示例
+
+```typescript
+await map.addMapLayer({
+  id: 'wms-001',
+  title: '市界',
+  url: 'http://192.168.1.185:8082/geoserver/qinghai/wms',
+  sublayers: ['qinghai_sheng_yy'],
+  layerType: 'geoserver-wms',
+  layerTag: 'boundary',
+  selectIndex: 'qinghai_sheng_yy',
+  geometryType: 3,
+  opacity: 1,
+  mapIndex: 4,
+  editType: true,
+  thumbnail: '',
+});
+```
+
+### XYZ 瓦片示例
+
+```typescript
+await map.addMapLayer({
+  id: 'xyz-001',
+  title: '自定义影像',
+  url: 'http://host/vt/x={x}&y={y}&z={z}&scale=1.jpg',
+  layerType: 'tile',
+  opacity: 1,
+  mapIndex: 0,
+  thumbnail: '',
+});
+```
+
+> XYZ 模板支持 OpenLayers 占位符：`{x}` `{y}` `{z}` `{-y}`（TMS Y 轴翻转）。
+
+### 超图 iServer REST 地图示例
+
+```typescript
+await map.addMapLayer({
+  id: 'supermap-001',
+  title: '通化子项目矢量',
+  url: 'http://10.3.50.13:8090/iserver/services/map-TongHua/rest/maps/通化子项目矢量@通化.rjson',
+  layerType: 'supermap-rest',
+  opacity: 1,
+  mapIndex: 0,
+  checked: true,
+  thumbnail: '',
+});
+```
+
+> `url` 支持 `.rjson` / `.json` 后缀，或不带后缀的 `rest/maps/{mapName}` 地址。若 `url` 为 `rest/maps` 根地址，可通过 `sublayers: ['地图名']` 指定地图。
+
+---
+
+## 要素管理 FeatureManager
+
+```typescript
+import FeatureManager from 'ym-gis-2d/feature/FeatureManager';
+
+const fm = new FeatureManager(map);
+
+// 设置当前编辑图层
+map.currentEditLayer = layerInfo;
+
+// 获取可编辑要素
+const editFeatures = fm.getEditFeatures();
+const editFeaturesFiltered = fm.getEditFeatures('status', ['draft']);
+
+// 获取选中要素
+const selected = fm.getSelectedFeatures();           // 全部
+const byLayer = fm.getSelectedFeatures('layer-id');  // 指定图层
+
+// 闪烁高亮
+fm.flashFeatures(features, 3);
+fm.flashGeometrys([geometry], 3);
+
+// 清除临时要素
+fm.clearTempFeatures();       // 清除全部
+fm.clearTempFeatures('tag');  // 按 tag 清除
+
+// KML 导入
+const features = await fm.kmlImport(kmlString);
+```
+
+### Feature 扩展属性
+
+`ym-gis-2d/entity/Feature` 在 OpenLayers Feature 基础上扩展：
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `isSelected` | `boolean` | 是否选中 |
+| `fromType` | `'draw' \| 'import' \| 'cut' \| ...` | 来源类型 |
+| `layerId` | `string` | 关联图层 id |
+| `tag` | `string` | 业务标签 |
+| `tempLayer` | `VectorLayer` | 所在临时图层 |
+
+---
+
+## 地图交互 Interaction
+
+所有交互通过 `map.interactionManager` 注册：
+
+```typescript
+map.interactionManager.addInteraction('draw', drawInstance);
+map.interactionManager.removeInteraction('draw');
+map.interactionManager.getInteraction('draw');
+map.interactionManager.removeAllInteractions();
+```
+
+### Draw — 绘制
+
+```typescript
+import Draw from 'ym-gis-2d/interaction/Draw';
+import GeometryType from 'ym-gis-2d/entity/GeometryType';
+
+const draw = new Draw(map, GeometryType.Polygon, {
+  style: { color: 'rgba(0,0,255,0.2)', outlineColor: 'blue', outlineWidth: 2 },
+  showTip: true,
+  tipText: '点击绘制多边形',
+});
+
+draw.on('drawEnd', (evt) => {
+  const feature = evt.feature;
+});
+
+map.interactionManager.addInteraction('draw', draw);
+draw.setActive(true);
+```
+
+支持的 `GeometryType`：
+
+| 常量 | 说明 |
+|------|------|
+| `Point` | 点 |
+| `PolyLine` | 折线 |
+| `Polygon` | 多边形 |
+| `Rectangle` | 矩形 |
+| `Circle` | 圆 |
+| `Curve` | 曲线 |
+| `Arrow` / `ArrowAttack` / `ArrowPincerlike` | 箭头类 |
+| 等 | 见 `entity/GeometryType.ts` |
+
+Draw 事件：`drawStart` `drawEnd` `drawAbort` `drawAddPoint` `drawMoving`
+
+### Select — 选择 / 查询
+
+```typescript
+import Select from 'ym-gis-2d/interaction/Select';
+
+const select = new Select(map, {
+  pixelDistance: 5,
+  addTempLayer: true,
+});
+
+select.on('selected', (evt) => {
+  console.log(evt.features);
+});
+
+map.interactionManager.addInteraction('select', select);
+```
+
+### 其他交互
+
+| 类 | 导入路径 | 说明 |
+|----|----------|------|
+| `Modify` | `interaction/Modify` | 节点编辑 |
+| `Snap` | `interaction/Snap` | 吸附 |
+| `Split` | `interaction/Split` | 面分割 |
+| `Difference` | `interaction/Difference` | 挖除/差集 |
+| `Repair` | `interaction/Repair` | 面修补 |
+| `AreaMeasure` | `interaction/AreaMeasure` | 面积量测 |
+| `DistanceMeasure` | `interaction/DistanceMeasure` | 距离量测 |
+
+量测单位配置见 `entity/measure/AreaMeasureUnits`、`DistanceMeasureUnits`。
+
+---
+
+## 地图控件 Control
+
+通过 `map.controlManager` 管理，用法与 `interactionManager` 类似。
+
+| 类 | 导入路径 | 说明 |
+|----|----------|------|
+| `MousePositionControl` | `controls/MousePositionControl` | 鼠标坐标显示 |
+| `LegendControl` | `controls/LegendControl` | 图例 |
+| `SwipeLayerControl` | `controls/SwipeLayerControl` | 卷帘对比 |
+
+```typescript
+import MousePositionControl from 'ym-gis-2d/controls/MousePositionControl';
+
+const mousePos = new MousePositionControl({
+  fractionDigits: 4,
+  showSpheroid: true,
+});
+
+map.controlManager.addControl('mousePosition', mousePos);
+```
+
+---
+
+## 服务元数据 capabilities
+
+用于管理后台解析服务能力、图层列表与字段信息：
+
+```typescript
+import {
+  getWmtsLayers,
+  getWmsLayers,
+  getWfLayers,
+  getArcgisDynamicLayers,
+  getArcgisDynamicLayerFields,
+  getWmsLayerFields,
+  getSourceLayerFields,
+  getDynamicLayerInfo,
+  getWMTSLayerCapabilities,
+  getWMSLayerCapabilities,
+  getWFSLayerCapabilities,
+} from 'ym-gis-2d/capabilities';
+
+// 获取 WMTS 图层列表
+const layers = await getWmtsLayers('http://host/geoserver/gwc/service/wmts');
+
+// 获取图层字段
+const fields = await getSourceLayerFields(url, 'workspace:layer', 'geoserver-wfs');
+```
+
+---
+
+## 空间查询 tasks
+
+```typescript
+import { selectFeaturesByGeo } from 'ym-gis-2d/utils/tasks';
+
+const features = await selectFeaturesByGeo(
+  geometry,           // 查询几何（可选）
+  'EPSG:4490',        // 几何坐标系
+  serviceUrl,
+  layerName,          // selectIndex / 图层名
+  'geoserver-wms',    // 服务类型
+  "id=1",             // 属性过滤（可选）
+  resolution          // 当前地图分辨率（栅格 WMS 查询时使用）
+);
+```
+
+支持的服务类型：`arcgis-dynamic`、`arcgis-feature`、`geoserver-wfs`、`geoserver-wms`、`geoserver-wmts`。
+
+---
+
+## 几何工具 GeometryUtil
+
+```typescript
+import {
+  fromWKT, toWKT,
+  fromWKTs,
+  fromGeoJSON, toGeoJSON,
+  fromEsriJSON, toEsriJSON,
+  getArea, getLength,
+  bufferOp, bufferPixel,
+  contains, crosses, intersects, intersection,
+  union, unions, difference,
+  jstlSplit, splitLineByLine,
+  expandExtent,
+  polygonToLines,
+  getGeometryCenter,
+  isGeometryEmpty,
+} from 'ym-gis-2d/utils/GeometryUtil';
+```
+
+常用示例：
+
+```typescript
+const geom = fromWKT('POINT(117 31)', 'EPSG:4490', 'EPSG:4490');
+const wkt = toWKT(geom);
+const area = getArea(polygon, 'EPSG:4490', true);  // 第三个参数：是否椭球面积
+const len = getLength(line, 'EPSG:4490', true);
+const merged = union(geom1, geom2);
+```
+
+---
+
+## 坐标系 RegisterProjUtil
+
+```typescript
+import { registerProj, isSpheroid, getSpheroidProjection } from 'ym-gis-2d/utils/RegisterProjUtil';
+
+// 注册坐标系（OLMap 构造时会自动注册 projection 选项）
+registerProj('EPSG:4490');
+registerProj('EPSG:4326');
+
+// 判断是否大地坐标系
+isSpheroid(projection);
+```
+
+### GCJ-02 转换
+
+```typescript
+import { gcj02towgs84, wgs84togcj02 } from 'ym-gis-2d/utils/gcj02Util';
+const [lng, lat] = gcj02towgs84(116.404, 39.915);
+```
+
+---
+
+## KML 转换
+
+```typescript
+import { toKml, toGeoJSON } from 'ym-gis-2d/conver/kml';
+
+// GeoJSON → KML 字符串
+const kml = toKml(geojson, options);
+
+// KML → GeoJSON（支持字符串、URL、Blob、KMZ）
+const geojson = await toGeoJSON(kmlString, null);
+```
+
+---
+
+## 类型定义 entity
+
+```typescript
+import type {
+  IMapService,
+  IMapServiceTree,
+  IMapServiceQuery,
+  IMapServiceType,
+  ILayerField,
+} from 'ym-gis-2d/entity';
+
+import type IStyle from 'ym-gis-2d/entity/style/IStyle';
+```
+
+### IStyle 样式
+
+```typescript
+interface IStyle {
+  color?: string | number[];       // 填充色
+  opacity?: number;                // 填充透明度
+  outlineColor?: string | number[];
+  outlineOpacity?: number;
+  outlineWidth?: number;
+  imgurl?: string;                 // 点图标
+  radius?: number;                 // 点半径（米）
+  scale?: number;                  // 图标缩放
+  rotation?: number;               // 图标旋转
+  text?: string;                   // 标注文字
+  font?: IFont;
+}
+```
+
+### 图层目录树
+
+```typescript
+import { mapServiceTreeTransform } from 'ym-gis-2d/utils/LayerUtil';
+
+const tree: IMapServiceTree[] = mapServiceTreeTransform(flatLayerList);
+```
+
+---
+
+## 完整示例
+
+Vue 3 集成示例（参考 `comm-web` 项目）：
+
+```vue
+<template>
+  <div id="map"></div>
+</template>
+
+<script setup lang="ts">
+import { onMounted } from 'vue';
+import OLMap from 'ym-gis-2d/mapView/Map';
+import type { IMapService } from 'ym-gis-2d/entity';
+import Draw from 'ym-gis-2d/interaction/Draw';
+import GeometryType from 'ym-gis-2d/entity/GeometryType';
+import FeatureManager from 'ym-gis-2d/feature/FeatureManager';
+
+const layers: IMapService[] = [
+  {
+    id: 'vec',
+    title: '天地图矢量',
+    url: 'http://t0.tianditu.gov.cn/vec_c/wmts?tk=YOUR_TOKEN',
+    sublayers: ['vec'],
+    layerType: 'tdt-c',
+    mapIndex: 0,
+    opacity: 1,
+    checked: true,
+    thumbnail: '',
+  },
+  {
+    id: 'boundary',
+    title: '行政边界',
+    url: 'http://host/geoserver/wms',
+    sublayers: ['ws:boundary'],
+    layerType: 'geoserver-wms',
+    layerTag: 'boundary',
+    selectIndex: 'ws:boundary',
+    geometryType: 3,
+    editType: true,
+    mapIndex: 1,
+    opacity: 1,
+    thumbnail: '',
+  },
+];
+
+onMounted(async () => {
+  const map = new OLMap('map', {
+    projection: 4490,
+    extent: [89.7, 26.7, 94.8, 29.8],
+  });
+
+  for (const layer of layers) {
+    await map.addMapLayer(layer);
+  }
+
+  map.currentEditLayer = layers[1];
+
+  const draw = new Draw(map, GeometryType.Polygon);
+  draw.on('drawEnd', () => {
+    const fm = new FeatureManager(map);
+    console.log(fm.getEditFeatures());
+  });
+  map.interactionManager.addInteraction('draw', draw);
+});
+</script>
+
+<style>
+#map { width: 100%; height: 100vh; }
+</style>
+```
+
+---
+
+## 注意事项
+
+1. **坐标系**：默认 EPSG:4490（CGCS2000），与天地图 `tdt-c` 服务匹配；使用 WGS84 服务时需设置 `projection: 4326`。
+2. **跨域**：WMS/WMTS/XYZ 服务需配置 CORS，或在开发环境使用代理。
+3. **天地图 Token**：`tdt-c` 类型 URL 需携带有效 `tk` 参数。
+4. **异步加载**：`addMapLayer` 为异步方法，WMS/WMTS 会先请求 GetCapabilities，请使用 `await` 或 `.then()`。
+5. **临时图层**：绘制、选中、定位高亮均写入临时矢量层，不会直接修改服务端数据；持久化需自行对接后端。
+6. **发布产物**：npm 包为编译后的 JS + `.d.ts` 声明文件，子路径导入方式与源码一致。
+7. **UI 组件**：工具栏、图例、卷帘等 UI 在 `ym-giswidget-2d` 包中，本包仅提供 GIS 核心能力。
+
+---
+
+## 相关包
+
+| 包名 | 说明 |
+|------|------|
+| `ym-giswidget-2d` | 二维 GIS UI 组件（工具栏、图例、量测、导入导出等） |
+| `ol` | OpenLayers 官方库 |
+
+如有问题，请联系包维护者或查阅 monorepo 内 `comm-web`、`gis-2d-docs` 示例项目。