MerosCoreJS

基于 ShinetekView2D/3D 的前端功能辅助库——类似 lodash 的地图业务函数集

MerosCoreJS 不是对 ShinetekView2D 的二次封装，而是在 ShinetekView2D 的基础上，结合 MerosServer，面向插件管理与实际业务需求进行功能扩展。

核心原则：

• 用户不能通过 MerosCoreJS 对 Map 进行直接操作，MerosCoreJS 的所有 Map 操作都会返回 ShinetekView2D 的 Map 对象，用户可通过该对象进行 Map 操作
• MerosCoreJS 只提供针对业务层面的功能辅助函数（如图层管理）和插件功能辅助函数

运行时依赖

| 依赖 | 全局变量 | 说明 | |------|---------|------| | ShinetekView2D | window.ShinetekView2D | 2D 地图引擎，创建 2D 地图时必须 | | ShinetekView3D | window.ShinetekView3D | 3D 地图引擎（Cesium），创建 3D 地图时必须 | | lodash | window._ | 工具函数库（webpack external，不打包） | | PubSub-JS | window.PubSub | 消息订阅/发布（webpack external，不打包） |

⚠️ 以上依赖需在使用 MerosCoreJS 之前加载为全局变量。

安装

npm install meroscore

或在 HTML 中直接引入构建产物：

<script src="path/to/lodash.js"></script>
<script src="path/to/pubsub.js"></script>
<script src="path/to/shinetekview2d.js"></script>
<script src="path/to/meroscore.js"></script>

快速启动

<script>
  // 1. 加载服务端配置
  window.MEROSCONFIG = JSON.parse(atob('$$MEROSCONFIG$$'))
  window.EXTENSIONS = JSON.parse(atob('$$EXTENSIONCONFIG$$'))

  // 2. 链式调用：加载配置 → 加载插件
  MerosCore
    .loadConfig(window.MEROSCONFIG)
    .loadExtension(window.EXTENSIONS)

  // 3. 监听插件加载失败
  MerosCore.on(MerosCore.EventTopic.EXTENSION.LOADERROR, (data) => {
    console.error('插件加载失败', data.error, data.extension)
  })
</script>

初始化插件（如 meros-init） 在 AFTERLOAD 回调中创建地图，创建完成后发布 MAPVIEW_READY：

// meros-init.js
MerosCore.on(MerosCore.EventTopic.EXTENSION.AFTERLOAD, function () {
  MerosCore
    .createMulti2DMap({
      container: 'meros-view.map',
      grid: [100, 100],
      position: {
        "olA": [1, 1, 59, 100],
        "olB": [60, 1, 100, 49],
        "olC": [60, 50, 100, 100],
      }
    })
    .create3DMap('meros-view.map', {})

  // 添加初始图层
  for (var p in MerosCore.map2DItem) {
    MerosCore.map2DItem[p].addTileLayer({ ... })
  }

  // 发布地图就绪事件（必须手动 emit）
  MerosCore.emit(MerosCore.EventTopic.CORE.MAPVIEW_READY)
})

⚠️ 初始化插件必须在地图创建完成后手动 emit MAPVIEW_READY，否则业务插件将无法感知地图就绪时机。此事件不由库自动发布。

业务插件 监听 MAPVIEW_READY 后操作地图：

// meros-pole-product.js
MerosCore.on(MerosCore.EventTopic.CORE.MAPVIEW_READY, function () {
  var map = MerosCore.map2DItem['meros-view.map']
  map.addLayer(...)
})

核心概念

链式调用

loadConfig、create2DMap、createMulti2DMap、create3DMap、createMulti3DMap、createMap、createMultiMap、loadExtension 均返回 MerosCore 自身，支持链式调用：

MerosCore
  .loadConfig(config)
  .create2DMap('map-container')
  .loadExtension(extensions)

布局系统

使用 CSS Grid 实现多地图布局。通过 grid 定义网格精度，position 定义每个子容器占据的网格区域：

MerosCore.createMulti2DMap({
  container: 'map-container',  // 容器 ID 或 HTMLElement
  grid: [100, 100],            // [列数, 行数]
  position: {
    "mapA": [1, 1, 50, 100],   // [起始列, 起始行, 列跨度, 行跨度]
    "mapB": [51, 1, 50, 50],
    "mapC": [51, 51, 50, 50],
  }
})

事件系统

MerosCoreJS 内置了分类事件主题（EventTopic），提供 on/once/off/emit 事件 API，插件无需引入 PubSub 即可完成全部事件操作：

// 订阅内置事件（推荐使用 EventTopic 常量）
const token = MerosCore.on(MerosCore.EventTopic.SHINETEKVIEW.MAP_ZOOM, (data) => {
  console.log('地图缩放', data)
})

// 订阅一次后自动退订
MerosCore.once(MerosCore.EventTopic.CORE.MAPVIEW_CREATE, (data) => {
  console.log('地图创建', data)
})

// 退订
MerosCore.off(token)

// 发布事件
MerosCore.emit(MerosCore.EventTopic.CORE.PROD_SELECT, { productId: '12345' })

// 注册插件自定义事件
MerosCore.registerEvent('myExtension', 'EVENT_dataUpdated')
// 注册后可通过 EventTopic 访问，并使用 on/emit 操作
MerosCore.on(MerosCore.EventTopic.myExtension.EVENT_DATA_UPDATED, (data) => { ... })
MerosCore.emit(MerosCore.EventTopic.myExtension.EVENT_DATA_UPDATED, { result: 'ok' })

图层管理

MerosCoreJS 按 zIndex 范围自动分类图层，并提供只读属性查询：

| 图层类型 | zIndex 安全范围 | 访问属性 | |---------|---------------|---------| | Map | 1 – 1000 | MerosCore.maplayers | | Base | 1001 – 2000 | MerosCore.baselayers | | Image | 2001 – 3000 | MerosCore.imageLayers | | Other | 3001 – 4000 | MerosCore.otherLayers | | Vector | 4001 – 5000 | MerosCore.vectorLayers | | Boundary | 5001 – 6000 | MerosCore.boundaryLayers |

// 获取所有图层
MerosCore.layers

// 获取某类型图层的最大 zIndex
MerosCore.imageMaxZIndex  // → 2001（无图层时返回安全范围起始值）

API 总览

📖 详细的函数签名、参数说明和示例代码请参阅 API 参考文档

配置管理

| 方法 | 说明 | 返回值 | |------|------|--------| | loadConfig(config) | 加载并解析服务端配置 | MerosCore（链式） | | getConfig(...node) | 获取指定路径的配置值 | any | | relativePath(path) | 解析相对于当前脚本的路径 | string | | config | 当前配置对象（只读） | MerosConfigInterface |

地图创建（2D）

| 方法 | 说明 | 返回值 | |------|------|--------| | create2DMap(containerID, [viewParams], [extendParams], [eventParams]) | 创建单个 2D 地图 | MerosCore（链式） | | createMulti2DMap(layoutOpt, [viewParams], [extendParams], [eventParams]) | 创建多个 2D 地图（网格布局） | MerosCore（链式） | | map2DItem | 所有 2D 地图实例字典（只读） | { [containerID]: ShinetekView2D } |

地图创建（3D）

| 方法 | 说明 | 返回值 | |------|------|--------| | create3DMap(containerID, [viewParams]) | 创建单个 3D 地图 | MerosCore（链式） | | createMulti3DMap(layoutOpt, [viewParams]) | 创建多个 3D 地图（网格布局） | MerosCore（链式） | | map3DItem | 所有 3D 地图实例字典（只读） | { [containerID]: ShinetekView3D } |

地图创建（统一入口）

| 方法 | 说明 | 返回值 | |------|------|--------| | createMap(containerID, type, [viewParams], [extendParams], [eventParams]) | 按类型创建地图（'ol' / 'cesium' / 'mapbox'） | MerosCore（链式） | | createMultiMap(layoutOpt, params) | 按类型创建多个地图（支持混合 2D/3D） | MerosCore（链式） |

插件管理

| 方法 | 说明 | 返回值 | |------|------|--------| | loadExtension(extensions) | 顺序加载插件列表 | MerosCore（链式） |

事件注册与订阅

| 方法 | 说明 | 返回值 | |------|------|--------| | registerEvent(extensionName, events) | 为插件注册自定义事件主题 | void | | EventTopic | 内置事件主题字典（只读） | EventCategories | | on(topic, callback) | 订阅事件，插件无需引入 PubSub | string（token） | | once(topic, callback) | 订阅一次后自动退订 | string（token） | | off(token) | 退订事件 | void | | emit(topic, data) | 发布事件 | boolean |

图层管理

| 属性 | 说明 | 类型 | |------|------|------| | layers | 所有已注册图层 | LayerInterface[] | | maplayers | Map 类型图层 | LayerInterface[] | | baselayers | Base 类型图层 | LayerInterface[] | | imageLayers | Image 类型图层 | LayerInterface[] | | otherLayers | Other 类型图层 | LayerInterface[] | | vectorLayers | Vector 类型图层 | LayerInterface[] | | boundaryLayers | Boundary 类型图层 | LayerInterface[] | | unknownLayers | 未知类型图层 | LayerInterface[] | | mapMaxZIndex | Map 类型最大 zIndex | number | | baseMaxZIndex | Base 类型最大 zIndex | number | | imageMaxZIndex | Image 类型最大 zIndex | number | | otherMaxZIndex | Other 类型最大 zIndex | number | | vectorMaxZIndex | Vector 类型最大 zIndex | number | | boundaryMaxZIndex | Boundary 类型最大 zIndex | number |

TypeScript

本库提供 TypeScript 类型声明文件，安装后自动生效：

import MerosCore from 'meroscore'

MerosCore.loadConfig(config).create2DMap('map-container')

版本历史

详见 CHANGELOG.md

许可证

ISC