vjmap（唯杰地图 2D）二次开发技能

面向 vjmap (map2d) Web 地图底座的二次开发。CAD 绘图扩展（MapCadLayer）见 vjmapext skill；三维见 vjmap3d skill；纯 CAD 编辑器见 vjcad skill。

〇、文档与示例来源（路径约定）

本 skill 的 references/ 是自带离线参考，已按 vjmap@1.0.161 的 dist/vjmap.d.ts 与官方示例核对。仍需更深细节时按下列来源查证，冲突时以 npm 包 .d.ts 与 playground 示例为准：

示例代码中的 env.serviceUrl / env.accessToken / env.exampleMapId 是 playground 注入的环境变量；自己项目里替换为你的服务地址与 token（公有云 https://vjmap.com/server/api/v1，私有化 http://<ip>:27660/api/v1）。不要把 token 写进提交的代码。

一、适用范围

二、安装与引入

npm（推荐用于工程化项目）：

npm i vjmap          # vjmapext 需另装：npm i vjmap vjmapext

import vjmap from "vjmap";
import "vjmap/dist/vjmap.min.css";

CDN / 全局对象（单 HTML 直跑；unpkg / jsdelivr 均可，版本号按需替换）：

<link rel="stylesheet" href="https://unpkg.com/vjmap@1.0.161/dist/vjmap.min.css">
<script src="https://unpkg.com/vjmap@1.0.161/dist/vjmap.min.js"></script>
<!-- 全局对象 vjmap；官方 demo CDN 亦可用：https://vjmap.com/demo/js/vjmap/vjmap.min.js -->

起步模板（复制即用）：templates/vite-app/（npm + Vite，README）与 templates/cdn/（单 HTML），均含完整 openMap→attach→onLoad 初始化代码，只需替换 serviceUrl / accessToken / mapid。

三、心智模型

       [DWG / 互联网底图]
              |
              v
+-----------+       +-----------------+
|  Service  |---->  |  GeoProjection  |          创建顺序：
| (后台API) |       | (图范围/经纬度) |          1. new vjmap.Service(url, token)
+-----------+       +-----------------+          2. await svc.openMap({mapid, fileid, mapopenway, style})
        \              /                          3. new vjmap.GeoProjection(GeoBounds.fromString(res.bounds))
         v            v                           4. new vjmap.Map({container, style, center, zoom})
         +----------------+                       5. map.attach(svc, prj)
         |  vjmap.Map      | (WebGL 渲染)         6. await map.onLoad()
         |  - sources       |                      7. (可选) vjmapext MapCadLayer → 见 vjmapext skill
         |  - layers        |
         |  - Marker/Popup  |
         |  - events        |
         +-----------------+

关键认知：

1. vjmap.Map 遵循主流 WebGL 地图框架的 source/layer/event API 风格，另外扩展了 attach/toLngLat/fromLngLat/onLoad/getGeoBounds/enableVectorLayerHoverHighlight/... 等 vjmap 专有接口。
2. 渲染用的经纬度只有在以互联网地图为底图时才有真实地理意义；以 CAD 图为底图时，它只是把 CAD 原始坐标映射到 (-180,180) × (-85.0511,85.0511) 的渲染区间。
3. 几何计算用 CAD 几何坐标，绘制用 经纬度坐标；坐标往返永远通过 map.toLngLat / map.fromLngLat（或 prj.toLngLat / prj.fromLngLat）。
4. 需要保存坐标到后台时，一律保存 CAD 坐标；加载时再 toLngLat 转为渲染经纬度。

四、最小可运行模板（MRT）

CDN 版（HTML 直接粘贴运行）：

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://vjmap.com/demo/js/vjmap/vjmap.min.css">
  <script src="https://vjmap.com/demo/js/vjmap/vjmap.min.js"></script>
</head>
<body style="margin:0">
<div id="map" style="position:absolute;left:0;top:0;right:0;bottom:0"></div>
<script>
window.onload = async () => {
  const svc = new vjmap.Service(
    "https://vjmap.com/server/api/v1",   // 换成你的服务地址
    "YOUR_TOKEN"                          // 换成你的 token
  );
  const res = await svc.openMap({
    mapid: "sys_zp",
    mapopenway: vjmap.MapOpenWay.GeomRender,
    style: vjmap.openMapDarkStyle()
  });
  if (res.error) { console.error(res.error); return; }

  const prj = new vjmap.GeoProjection(res.bounds);
  const map = new vjmap.Map({
    container: "map",
    style: svc.vectorStyle(),
    center: prj.toLngLat(prj.getMapExtent().center()),
    zoom: 2,
    renderWorldCopies: false
  });
  map.attach(svc, prj);
  await map.onLoad();

  const center = prj.toLngLat(prj.getMapExtent().center());
  new vjmap.Marker()
    .setLngLat(center)
    .setPopup(new vjmap.Popup().setHTML("<b>hello vjmap</b>"))
    .addTo(map);
};
</script>
</body>
</html>

npm 版：npm i vjmap + import vjmap from "vjmap"; import "vjmap/dist/vjmap.min.css";，其余代码一致。Vue3 工程集成见 setup/integrations 与 map2d/vjmap-vue3/ 示例。

vjmapext 版（CAD 实体 / 绘图命令 / 编辑交互）：见 vjmapext skill 的 MRT。

五、按用户场景速查

标 【vjmapext】 的条目属于 CAD 绘图扩展，对应文件在 ../vjmapext/references/（两个 skill 并列安装时链接可直接跳转）。

六、完整文件地图

环境初始化 (setup/)
overview · install · container · integrations · dispose

打开图 (open-map/)
overview · open-dwg · map-open-way · blank-map · bounds-and-projection · switching

坐标转换 (coord/)
overview · concepts · projection-api · gis-transforms · internet-basemap-align · cad-epsg · overlay-coords · query-coords

后台服务 (backend/)
overview · service-basics · rest-interface · common-map-methods · query-sql · query-expression · query-features · query-fulltext · query-cases · svr-style-var · map-management · upload-create-map · map-sources · map-power · export-dwg · export-formats · recognizer · ai-features

Marker (marker/)
overview · create · options · builtin-icons · custom-dom · anchor-offset · zoom-behavior · animation · drag · events · cluster · with-popup · performance-tips

Popup (popup/)
overview · create · options · track-pointer · marker-binding · styling · dynamic-content

Symbol (symbol/)
overview · layer-types · circle-symbol · icon-symbol · text-symbol · expression · marker-vs-symbol

Primitive (primitive/)
overview · line · polygon-fill · polyline-api · circle-arc · geojson-source · editing · svg-div-overlay

批量 (batch/)
geojson-bulk（实体级批量在 vjmapext skill）

互联网地图 (internet-map/)
overview · tianditu · gaode · baidu · tencent · osm-overseas · raster-tile · vector-tile · label-overlay · zoom-level-map

叠加 (overlay/)
overview · multi-map · deckgl · leaflet · openlayers · cesium · annotation · legend-north-scale · sync-view

交互工具 (interaction/)
overview · context-menu · measure · draw-tools · draw-action · select-feature · controls · mouse-keyboard · drag-rotate-zoom · snap-ortho

地图样式 (map-style/)
overview · style-spec · layer-styles · expressions · data-driven · extrusion-3d · fog-sky-atmosphere · sprite-glyphs · theme-switch

事件 (event/)
overview · map-interaction · map-lifecycle · map-view · layer-events · cleanup（EventBus entity:*/command:* 事件在 vjmapext skill）

性能 (perf/)
overview · large-markers · event-throttling · memory-leaks · profiling（实体渲染桶 / FX 特效性能在 vjmapext skill）

常见坑 (trouble/)
overview · container-collapse · cdn-order · token-cors · bounds-parse · coord-offset-gaode · marker-duplicate · listener-leak · vue-react-dispose

七、约定、命名与红旗

命名

• svc = vjmap.Service 实例；map = vjmap.Map 实例；prj = vjmap.GeoProjection 实例；mapcadLayer = vjmapext.MapCadLayer 实例（见 vjmapext skill）。
• res = await svc.openMap(...) 要包 try/catch（HTTP 非 2xx——403 token 失效、404 图不存在——直接 reject，不进 res.error），成功返回后再立刻检查 res.error（带内错误，如密码图）。

异步初始化顺序

1. new vjmap.Service(url, token)
2. await svc.openMap({mapid, fileid, mapopenway, style}) → 得 res.bounds
3. new vjmap.GeoProjection(res.bounds)（或 vjmap.LnglatProjection 用于互联网底图）
4. new vjmap.Map({container, style, center, zoom, ...})
5. map.attach(svc, prj)
6. await map.onLoad() — 之后才能 加 source/layer/Marker/Control
7. （可选）new vjmapext.MapCadLayer(...) → map.addControl(cad) — 详见 vjmapext skill

Top 10 红旗

1. 容器 <div> 没有宽高或 position 未设 relative/absolute → 首屏黑屏。
2. <script> 里把 vjmapext 写在 vjmap 之前 → 依赖未就绪。
3. openMap 没 try/catch、之后也没检查 res.error 就继续。
4. 互联网底图上画 CAD 数据不做 GCJ02/BD09 纠偏 → 整体偏移。
5. 批量 addEntity 在循环里每次都 setDirty() / 单独 commit → 卡顿（vjmapext）。
6. Vue/React 组件卸载时没 map.remove() + 清监听 → Marker 重影、内存泄漏。
7. map.on('click', handler) 没对应 map.off → 长期运行内存膨胀。
8. 10 万点标注用 DOM Marker 而不是 Symbol 图层 → 帧率崩。
9. setData 每帧都重建 FeatureCollection → 重复创建 GeoJSON worker。
10. 动画层和实体层混用（应放到 fx GPU 图层，vjmapext）→ 重绘抖动。

保存 / 加载坐标的规矩

• 保存至后台：使用 map.fromLngLat(lngLatObj) 转为 CAD 几何坐标后保存。
• 从后台加载：使用 map.toLngLat(cadObj) 转为渲染经纬度后绘制。
• 几何计算（相交、插值、偏移…）：用 CAD 坐标算，只在最后绘制时转经纬度。