HTML 覆盖物

CesiumHtmlOverlay 用于将任意 HTML 内容定位到 Cesium 地图中的指定经纬度。它适合承载动态文字、状态标签、操作按钮或带动画的复杂标记。

组件只负责坐标与屏幕位置同步，不包含具体业务样式。图标、文字和交互通过默认插槽由业务页面实现。

在线案例

基础用法

<template>
  <CesiumMap>
    <CesiumHtmlOverlay
      :position="[116.404, 39.915]"
      :pixel-offset="[0, -16]"
    >
      <button class="plot-marker" @click="handleSelect">
        <img src="/marker.png" alt="" />
        <span>{{ plot.varietyName }}</span>
      </button>
    </CesiumHtmlOverlay>
  </CesiumMap>
</template>

<script setup lang="ts">
import { CesiumHtmlOverlay, CesiumMap } from "scene-mapping-gis/3d";

const plot = { varietyName: "富士" };
function handleSelect() {
  // 处理地块选中逻辑
}
</script>

属性

属性	类型	默认值	说明
position	CesiumPositionInput	—	覆盖物绑定的经纬度坐标，必填
show	boolean	true	是否显示
pixelOffset	[number, number]	[0, 0]	相对坐标点的像素偏移
zIndex	number	1	HTML 层级
pointerEvents	boolean	true	是否允许插槽内容响应鼠标事件

行为说明

• 相机移动、缩放、旋转时，组件会自动更新 HTML 内容的位置。
• 点位离开当前画布范围或 show=false 时，组件会自动隐藏。
• 默认以内容底部中心对齐坐标点；需要微调时使用 pixelOffset。
• 需要呼吸、浮动、Hover 或选中动画时，直接在插槽内容中使用 Vue、Tailwind 或业务样式实现即可。

暴露方法

方法	说明
updatePosition()	手动刷新覆盖物位置，适用于插槽内容尺寸变化后的立即同步