MyOl 类

MyOl 是地图的核心类，作为整个库的入口点，负责地图的初始化、配置管理、模块加载以及基础的地图操作（如定位、重置）。它采用了模块化设计，按需加载各个功能模块（如点、线、面要素管理）。

导入

import { MyOl } from 'my-openlayer';
// 或者
import MyOl from 'my-openlayer';

构造函数

constructor(id: string | HTMLElement, options?: Partial<MapInitType>)

初始化一个新的地图实例。

参数说明

参数名	类型	必填	默认值	描述
id	string | HTMLElement	是	-	地图容器的 DOM ID 字符串或 HTMLElement 对象。
options	Partial<MapInitType>	否	{}	地图初始化配置选项，详见下表。

MapInitType 配置选项

属性名	类型	描述
center	number[]	地图初始中心点坐标 [经度, 纬度]，默认为 [0, 0]。
zoom	number	地图初始缩放级别，默认为 2。
minZoom	number	最小缩放级别。
maxZoom	number	最大缩放级别。
token	string	天地图 API Token，用于加载天地图底图。
annotation	boolean	是否显示注记图层（如地名标注），默认为 false。
layers	LayerItem[]	自定义初始图层数组。如果设置了此项，内置底图管理可能受到影响。
mapClipData	MapJSONData	地图裁剪数据（GeoJSON 格式），用于仅显示特定区域。
enableLog	boolean	是否启用内部日志输出，默认为 false。
logLevel	'debug' | 'info' | 'warn' | 'error'	日志级别，默认为 'error'。
projection	object	自定义投影坐标系配置。
projection.code	string	投影代码，如 'EPSG:4549'。
projection.def	string	proj4 定义字符串。
projection.extent	number[]	投影范围。
projection.worldExtent	number[]	投影对应的经纬度世界范围。
projection.units	Units	显式覆盖投影单位，通常不需要传；优先让 proj4.def 自动推导。

内置坐标系

MyOl 初始化时会显式注册以下内置坐标系，并在 register(proj4) 前保证 EPSG:4326 存在，因此业务项目不需要手动调用 proj4.defs('EPSG:4326', ...)：

坐标系	说明
EPSG:4326	WGS84 经纬度坐标，作为输入经纬度和投影转换的基础坐标系。
EPSG:4490	CGCS2000 经纬度坐标，默认视图投影。
EPSG:4549	CGCS2000 3 度带投影，可通过 projection.code 使用。

自定义投影传入 projection.def 后，MyOl 会先写入 proj4.defs，再统一调用 OpenLayers register(proj4)。如果只传 code 和 def，视图会复用注册后的投影对象，保留 proj4 从定义字符串中推导出的单位，例如 +units=m 会保持为米制，不会被默认经纬度元数据覆盖。

静态方法

createView

创建 OpenLayers 的 View 实例。

static createView(options: MapInitType): View

参数名	类型	描述
options	MapInitType	地图配置选项，主要使用其中的 center, zoom, projection 等属性。

实例方法

模块获取

MyOl 提供了懒加载的模块获取方法，只有在首次调用时才会初始化对应模块。

getPoint

获取点要素操作模块。

getPoint(): Point

返回值: Point 实例，用于添加、删除、管理点要素。

getLine

获取线要素操作模块。

getLine(): Line

返回值: Line 实例，用于绘制线条。

getPolygon

获取面要素操作模块。

getPolygon(): Polygon

返回值: Polygon 实例，用于绘制多边形。

getMapBaseLayers

获取底图管理模块。

getMapBaseLayers(): MapBaseLayers

返回值: MapBaseLayers 实例，用于切换底图类型（矢量、影像、地形）。

getTools

获取地图工具模块。

getTools(): MapTools

返回值: MapTools 实例，包含地图截图、裁剪等工具。

getSelectHandler

获取要素选择处理器模块。

getSelectHandler(): SelectHandler

返回值: SelectHandler 实例，用于处理地图要素的点击、悬停选择交互。

地图操作

locationAction

定位到指定坐标，支持动画过渡。

locationAction(longitude: number, latitude: number, zoom: number = 20, duration: number = 3000): void

参数名	类型	默认值	描述
longitude	number	-	目标经度。
latitude	number	-	目标纬度。
zoom	number	20	目标缩放级别。
duration	number	3000	动画持续时间（毫秒）。

resetPosition

重置地图位置到初始化时设置的中心点。

resetPosition(duration: number = 3000): void

参数名	类型	默认值	描述
duration	number	3000	动画持续时间（毫秒）。

管理器访问

getEventManager

获取事件管理器，用于监听地图事件。

getEventManager(): EventManager

getErrorHandler

获取错误处理器，用于自定义错误处理逻辑。

getErrorHandler(): ErrorHandler

getConfigManager

获取配置管理器。

getConfigManager(): ConfigManager

getMapOptions

获取当前地图的只读配置副本。

getMapOptions(): Readonly<MapInitType>

销毁

destroy

销毁地图实例，清理所有事件监听和资源。

destroy(): void

使用示例

完整初始化

import { MyOl } from 'my-openlayer';

// 定义配置
const options = {
  // 杭州市中心
  center: [120.15507, 30.274085],
  zoom: 12,
  minZoom: 5,
  maxZoom: 18,
  
  // 天地图 Token
  token: 'YOUR_TIANDITU_TOKEN',
  
  // 开启注记
  annotation: true,
  
  // 开启调试日志
  enableLog: true,
  logLevel: 'debug'
};

// 初始化地图
const map = new MyOl('map-container', options);

// 监听加载完成
map.getEventManager().on('rendercomplete', () => {
  console.log('Map loaded!');
});

使用自定义投影

import { MyOl } from 'my-openlayer';

const map = new MyOl('map', {
  projection: {
    code: 'EPSG:4549', // CGCS2000 3度带
    def: '+proj=tmerc +lat_0=0 +lon_0=120 +k=1 +x_0=500000 +y_0=0 +ellps=GRS80 +units=m +no_defs',
    extent: [...], // 可选，仅在需要限制投影范围时传入
    worldExtent: [...] // 可选，经纬度世界范围
  }
});

自定义投影传入 projection.def 时，MyOl 会先写入 proj4.defs，再统一注册到 OpenLayers。这样可以保证 center 从 EPSG:4326 转换到目标投影时已有完整转换关系。

projection.extent 和 projection.worldExtent 只会在显式传入时补充到已注册投影；projection.units 只有在确实需要覆盖 proj4.def 推导结果时才传入。米制投影一般只需要在 def 中包含 +units=m，不需要额外传 units。