القائمة
MineMap 的 Marker 与 Popup 规范。涵盖 DOM 覆盖物、三维高度、distanceDisplayCondition、拖拽、内容 API、地形场景与常见失败场景。
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
استنادا إلى تصنيف SOC المهني
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/ming1zhou88/minemap-skills --skill minemap-marker-and-popupيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
عرض SKILL.md
MineMap 3D 公告板（Billboard）专题。覆盖 BillboardMaterial / BillboardGeometry / BillboardInstance 动画、拾取高亮、动态纹理更新与轨迹对象联动；不与 DOM 覆盖物 Marker 混淆。
MineMap 云与大气渲染链。用于启用体积云（多层 CloudLayer）、单片实例化云（map.cloudCollection）、大气散射与太阳 / 天空辐照度，重点说明主分支公开参数与禁用字段。
MineMap 事件订阅模型、图层事件代理、once/off 管理、矢量与三维对象拾取。
| name | minemap-marker-and-popup |
| description | MineMap 的 Marker 与 Popup 规范。涵盖 DOM 覆盖物、三维高度、distanceDisplayCondition、拖拽、内容 API、地形场景与常见失败场景。 |
const marker = new minemap.Marker({
color: "#ff4d4f",
draggable: true,
offset: [-13.5, -35]
})
.setLngLat([116.39, 39.9])
.setAltitude(120)
.addTo(map);
const popup = new minemap.Popup({
closeOnClick: false,
closeButton: false,
offset: [0, -40]
})
.setText("我是带三维高度的 DOM 标注")
.setLngLat([116.39, 39.9])
.setAltitude(120);
marker.setPopup(popup).togglePopup();
Marker 和 Popup 都是 DOM 覆盖物它们的定位很明确：
SceneModel / SceneTileset因此它们的优点和边界也很明确：
对 Popup 来说，这个约束尤其重要：
这条结论对 Marker 也成立：
适合场景：
不适合场景：
这类场景应改用：
circle / symbol layerPointPrimitiveCollectionSceneModel / SceneTilesetMarker 的时候Popup 的时候Marker 支持两种创建方式：
HTMLElement + 配置element：自定义 DOMscale：仅默认 marker 生效，默认 1anchoroffsetcolor：默认 marker 颜色，默认 #3FB1CEdraggable：默认 falseclickTolerancerotation：默认 0rotationAlignment：默认 autopitchAlignment：默认 auto，内部会跟随 rotationAlignmentdistanceDisplayConditionanchor 和 offsetanchor 决定的是：
setLngLat() 指定的经纬度落在 marker 元素的哪个锚点上可选值：
centertopbottomleftrighttop-lefttop-rightbottom-leftbottom-rightoffset 是像素偏移，计算原点是元素中心。
默认 marker 特别要注意：
[-13.5, -35]基础位置：
setLngLat([lng, lat])三维高度：
setAltitude(heightToSurface)高度语义是：
常见写法：
marker.setLngLat([116.39, 39.9]).setAltitude(80);
这是 MineMap 里 Marker 很实用的一点。
源码里的拖拽逻辑会区分 terrain：
也就是说：
这很适合：
Marker 最常见的工作流：
setPopup(popup)togglePopup()关键细节：
offset，源码会为默认 marker 自动推导一套合适偏移offsetsetDraggable(true | false)enableDragging()disableDragging()isDraggable()getDraggable()使用建议：
setRotation(rotation)getRotation()setRotationAlignment(alignment)getRotationAlignment()setPitchAlignment(alignment)getPitchAlignment()对齐语义：
rotationAlignment = 'map'：更像固定在地图平面rotationAlignment = 'viewport'：更像始终朝向观察者pitchAlignment = 'map'：贴地图平面pitchAlignment = 'viewport'：立在视口前Marker 支持 distanceDisplayCondition。
作用：
适合：
addTo(map)remove()getLngLat()setLngLat()getAltitude()setAltitude()getElement()setPopup()getPopup()togglePopup()getMap()closeButton：默认 truecloseOnClick：默认 truecloseOnMove：默认 falsefocusAfterOpen：默认 trueanchoroffsetclassNamemaxWidth：默认 240pxdistanceDisplayConditionsetText(text)：安全文本，不插原始 HTMLsetHTML(html)：直接插 HTML，只能用于可信内容setDOMContent(node)：直接放 DOM 节点setMaxWidth(width)推荐规则：
setText()setHTML()setDOMContent()setLngLat([lng, lat])setAltitude(heightToSurface)getAltitude()三维高度写法：
popup.setLngLat([116.39, 39.9]).setAltitude(120);
重要边界：
Popup 支持高度语义所以它更适合：
而不适合：
trackPointer() 会把 popup 绑定到鼠标指针位置，而不是固定经纬度。
它会替代 setLngLat() 的常规定位行为。
推荐搭配：
closeOnClick: falsecloseButton: false典型场景：
offset 支持三种写法：
PointLike对象写法适合复杂气泡：
addClassName(className)removeClassName(className)toggleClassName(className)这是做业务皮肤最稳的入口，不要直接依赖内部 DOM 结构做过深选择器耦合。
addTo(map)remove()isOpen()Popup 也支持 distanceDisplayCondition。
这在三维场景里很有用：
const popup = new minemap.Popup({ closeOnClick: false }).setText("站点 A");
new minemap.Marker({ color: "#ff0000" }).setLngLat([116.39, 39.9]).setPopup(popup).addTo(map);
const marker = new minemap.Marker({ element: el, offset: [-12, -38] })
.setLngLat([116.39, 39.9])
.setAltitude(60)
.addTo(map);
const popup = new minemap.Popup({ offset: [0, -50], closeOnClick: false })
.setHTML("<div>高空设备</div>")
.setLngLat([116.39, 39.9])
.setAltitude(60);
marker.setPopup(popup);
关键点：
Marker 和 Popup 高度最好同时设const marker = new minemap.Marker({ draggable: true }).setLngLat([116.39, 39.9]).addTo(map);
terrain 开启时，拖拽会走地表 pick，高度可能自动更新。
const hoverPopup = new minemap.Popup({
closeButton: false,
closeOnClick: false
}).trackPointer();
map.on("mousemove", "poi-layer", (e) => {
hoverPopup.setText(e.features[0].properties.name).addTo(map);
});
这类场景不要手动每帧 setLngLat() 去模拟跟随。
Marker 充当大量点图层大量 DOM 会明显拖慢交互和布局。大批量点位应改用：
circlesymbolPointPrimitiveCollection结果是 marker 在高处，popup 还贴在地面参考位置附近，看起来像断开了。
Popup 不支持深度测试，不能指望它像 mesh 一样被模型自然裁掉。
setHTML()源码不会替你做 HTML 清洗，setHTML() 只能喂可信内容。
setLngLat()如果需要鼠标跟随，应优先用 trackPointer()，而不是自己不断 patch 经纬度。
这会增加误操作和多余的事件处理。拖拽能力应只在编辑态开放。
distanceDisplayConditionMarker / Popup 相关公开资料建议一起查：
https://minedata.cn/https://minedata.cn/nce-support/guide-3D-Ultrahttps://minedata.cn/nce-support/api-3D-Ultrahttps://minedata.cn/nce-support/demoCenter-3D-Ultrahttps://map.minedata.cn/main-user/login当前公开页面能确认：
当前不能确认：
所以在项目 onboarding 里，应该写成“账号登录 / 试用 / 开通申请”，不要写成“官网直接注册”。
Marker / Popup 资料怎么查推荐顺序：
source/api/Marker.js、source/api/Popup.js 核对真实行为demo/ 搜更接近当前版本的案例不要只看官网的原因：
Popup 不支持深度测试这类边界，应以源码注释和实现为准最相关的官方栏目通常是：
如果官网示例只展示基本用法，没有覆盖三维高度、距离显隐或 terrain 联动：
minemap-official-resources-and-onboardingsource/ + demo/ 收敛minemap-official-resources-and-onboardingminemap-fundamentalsminemap-widget-and-controlsminemap-events-and-pickingminemap-scene-componentsminemap-terrain-and-analysis