用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/ming1zhou88/minemap-skills --skill minemap-marker-and-popup命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
基于 SOC 职业分类
| 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