高德地图工具库设计与实现

Promise520
0 阅读4分钟

项目仓库地址

gdmap-utils

背景与痛点

公司主要服务于环卫企业，涉及城市道路清洁与保养业务。这类业务有较多地图可视化展现场景，如"作业区域收运点、运营区域公厕、压缩站与焚烧厂"等，地图使用频率非常高。

随着项目数量增加以及规模扩大，地图使用逐渐暴露出以下问题：

  • 地图使用未形成统一的风格（项目地图点位创建有多种风格），导致多人协作时代码一致性较差，增加了维护和阅读成本；
  • 早期版本大屏可视化地图覆盖物类别较多，采取的方案是为每种覆盖物独立编写一套控制逻辑；
  • 各覆盖物的控制逻辑调用链过长，业务代码逻辑重复且未封装，导致代码冗余且难以维护；
  • 覆盖物的新增与修改需要改动的代码量较大。

目标

  1. 统一地图常用功能的使用风格；
  2. 复用业务逻辑，实现图层创建、显示、销毁逻辑的集中管理；
  3. 提升开发效率与代码复用率；
  4. 通过 npm 包发布工具库。

设计原则

  1. 扩展性强：图层支持插件机制，可自定义图层；
  2. 原始地图实例功能增强：无缝接入高德地图，支持将已有实例包装成工具函数；
  3. 统一接口管理层：分类工具，按功能封装 Map 实例方法与 AMap 静态方法；
  4. TypeScript 全支持：提供完整的类型定义和泛型支持。

工具库架构设计

功能概述

本工具库的功能是针对公司地图业务需求开发的。例如，图层常用覆盖物仅有三种，因此图层管理设计仅管理这三类覆盖物，后续可根据使用情况扩展图层或常用方法。

  1. 将 AMap.Marker、AMap.LabelMarker、AMap.MarkerCluster 统一封装为图层，支持图层显示/隐藏、覆盖物增删查改、事件绑定等功能；
  2. 数据驱动的覆盖物更新：图标和标签与数据属性关联，属性发生变化时，调用 refreshOverlayIcon / refreshOverlayLabel 即可实现刷新；
  3. 灵活的初始化方式：支持创建新地图实例或包装已有实例（装饰器模式）；
  4. 统一接口抽象层：封装常用的 Map 实例方法和 AMap 静态工具方法（支持根据需要自定义形参默认值，需手动修改）；
  5. TypeScript 全支持：提供完整的类型定义和泛型支持。

架构分层

架构分层图

分层说明

1. 业务应用层

业务应用层功能说明如下：

  1. 地图实例方法封装：将 on、clearInfoWindow、setZoomAndCenter 等方法封装为 bindMapClickEvent、setZoomAndCenter、clearInfoWindow 等，定义常用默认值，避免直接与工具函数耦合；
  2. 静态方法包装：对 AMap 常用静态方法（如 AMap.Marker、AMap.Icon、AMap.Size、AMap.Pixel 等）进行包装；
  3. 图层管理：提供统一的接口函数用于创建图层。mapUtils 函数内部会收集创建的图层，以便进行统一管理（包括图层全部隐藏/显示、指定图层显示与隐藏等）。
2. 图层管理服务层

图层管理服务层直接面向用户，以避免与高德地图 API 直接耦合。现有两类图层如下：

  1. baseMarkerLayer：用于创建 marker 覆盖物，对应高德的 Marker 和 LabelMarker；
  2. clusterMarkerLayer：用于创建海量点覆盖物，对应高德的 MarkerClusterLayer。
3. 原生 API 层

原生 API 层封装了 LabelMarkerLayer、MarkerLayer、MarkerClusterLayer 的常用方法，为图层管理服务层提供基础服务。

项目结构说明

src/
├── index.ts                      # 入口文件，导出所有公共 API
├── MapUtils.ts                   # MapUtils 核心类，封装地图实例方法和静态工具
├── LayerManager.ts               # 图层管理器，统一管理图层创建与销毁
├── MapSourceImport.ts            # 高德地图 SDK 加载器
├── gdMap/
│   └── gdHelper.ts               # 高德地图辅助函数（AMap静态方法）
├── layers/
│   ├── index.ts                  # 图层模块统一导出
│   ├── baseMarkerLayer/
│   │   ├── index.ts              # BaseMarkerLayer 统一创建入口
│   │   ├── MarkerLayer.ts        # Marker 图层实现
│   │   └── LabelMarkerLayer.ts   # LabelMarker 图层实现
│   └── clusterMarkerLayer/
│       ├── index.ts              # ClusterMarkerLayer 统一导出
│       └── MarkerClusterLayer.ts # MarkerCluster 图层实现
└── types/
    ├── index.d.ts                # 类型统一导出
    ├── amap.d.ts                 # 高德地图 API 类型扩展
    ├── MapUtils.d.ts             # MapUtils 相关类型
    ├── baseMarkerLayer.d.ts      # BaseMarkerLayer 图层类型
    └── clusterMarkerLayer.d.ts   # ClusterMarkerLayer 图层类型

总结

完整地编写并发布了工具库到 npm，其下载体验比文件 copy 方式好太多。在本次开发中，接触到分层架构、设计模式等概念并进行了实际应用，整个过程收获颇丰。

avatar
文章
阅读
粉丝