---
title: "MapboxTooltip"
description: "图层要素弹窗，按 trigger 以悬浮或点击触发，slot 暴露命中要素。"
seo_title: "MapboxTooltip Component"
seo_description: "MapboxTooltip shows a popup over a target layer's features on hover or click, exposing the active feature and a close handler to its slot."
canonical_url: "https://mapbox.mhaibaraai.cn/docs/core/tooltip"
---
# MapboxTooltip

> 图层要素弹窗，按 trigger 以悬浮或点击触发，slot 暴露命中要素。

## 简介

`MapboxTooltip` 为 `layerId` 指定图层的要素挂载弹窗：默认 `trigger="hover"` 时跟随指针显示、移出即消失。默认插槽暴露命中要素（`feature`）与 `close`，可渲染其属性；按 `layerId` 委托到地图级监听，因此目标图层晚于本组件挂载也能命中。

`trigger` 支持 `hover` / `click` / `none`，其中 `none` 不绑定任何监听，可用于标绘等模式下临时停用。

## 用法

悬浮圆点图层显示要素信息，slot 取 `feature.properties`：

```vue [TooltipExample.vue]
<script setup lang="ts">
import type { FeatureCollection } from 'geojson'

const data: FeatureCollection = {
  type: 'FeatureCollection',
  features: [
    { type: 'Feature', properties: { name: '天安门', type: '地标' }, geometry: { type: 'Point', coordinates: [116.397, 39.908] } },
    { type: 'Feature', properties: { name: '国贸', type: '商圈' }, geometry: { type: 'Point', coordinates: [116.461, 39.909] } },
    { type: 'Feature', properties: { name: '中关村', type: '科技园' }, geometry: { type: 'Point', coordinates: [116.316, 39.983] } }
  ]
}
</script>

<template>
  <div class="h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MapboxMap :options="{ style: 'mapbox://styles/mapbox/light-v11', center: [116.39, 39.93], zoom: 11 }">
      <MapboxLayer
        layer-id="poi"
        type="circle"
        :source="{ type: 'geojson', data }"
        :paint="{ 'circle-radius': 9, 'circle-color': '#f43f5e', 'circle-stroke-width': 2, 'circle-stroke-color': '#fff' }"
      />
      <!-- 悬浮 poi 图层要素时跟随显示，slot 暴露命中要素 -->
      <MapboxTooltip layer-id="poi">
        <template #default="{ feature }">
          <div v-if="feature" class="px-1 text-sm">
            <span class="font-semibold">{{ feature.properties?.name }}</span>
            <span class="text-muted"> · {{ feature.properties?.type }}</span>
          </div>
        </template>
      </MapboxTooltip>
    </MapboxMap>
  </div>
</template>
```

## `trigger` `v1.2.0+`

`trigger="click"` 时弹窗常驻，直到点击其它要素或关闭按钮：

```vue [TooltipClickExample.vue]
<script setup lang="ts">
import type { FeatureCollection } from 'geojson'

const data: FeatureCollection = {
  type: 'FeatureCollection',
  features: [
    { type: 'Feature', properties: { name: '天安门', type: '地标' }, geometry: { type: 'Point', coordinates: [116.397, 39.908] } },
    { type: 'Feature', properties: { name: '国贸', type: '商圈' }, geometry: { type: 'Point', coordinates: [116.461, 39.909] } },
    { type: 'Feature', properties: { name: '中关村', type: '科技园' }, geometry: { type: 'Point', coordinates: [116.316, 39.983] } }
  ]
}
</script>

<template>
  <div class="h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MapboxMap :options="{ style: 'mapbox://styles/mapbox/light-v11', center: [116.39, 39.93], zoom: 11 }">
      <MapboxLayer
        layer-id="poi"
        type="circle"
        :source="{ type: 'geojson', data }"
        :paint="{ 'circle-radius': 9, 'circle-color': '#f43f5e', 'circle-stroke-width': 2, 'circle-stroke-color': '#fff' }"
      />
      <MapboxTooltip layer-id="poi" trigger="click">
        <template #default="{ feature, close }">
          <div v-if="feature" class="w-44 px-1 py-0.5">
            <p class="font-semibold">
              {{ feature.properties?.name }}
            </p>
            <p class="mt-0.5 text-sm text-muted">
              {{ feature.properties?.type }}
            </p>
            <UButton class="mt-2" size="xs" color="neutral" variant="subtle" @click="close">
              收起
            </UButton>
          </div>
        </template>
      </MapboxTooltip>
    </MapboxMap>
  </div>
</template>
```

> \[\!NOTE\]
> 
> click
> 
>  模式默认给出关闭按钮，但
> 
> 不
> 
> 启用 
> 
> closeOnClick
> 
>  —— 否则弹窗会被开启它的那一次点击立即关闭。确有需要可经 
> 
> options
> 
>  覆盖。

> \[\!TIP\]
> 
> 组件内部只有一个 Popup 实例，因此同一时刻只展示一个要素的弹窗。若要让多个要素的弹窗同时常驻，见 
> 
> MapboxPopup
> 
>  的「多弹窗共存」。

## API

### Props

```ts
/**
 * Props for the MapboxTooltip component
 */
interface MapboxTooltipProps {
  /**
   * 目标图层 id
   */
  layerId: string;
  /**
   * Popup 选项（hover 模式下 closeButton/closeOnClick 由组件接管）
   */
  options?: mapboxgl.PopupOptions | undefined;
  /**
   * 悬浮时鼠标指针样式
   * @default "\"pointer\""
   */
  cursor?: string | undefined;
  /**
   * 触发时机；'none' 表示不绑定任何监听，可用于临时停用
   * @default "\"hover\""
   */
  trigger?: PopupTrigger | undefined;
}
```

### Slots

```ts
/**
 * Slots for the MapboxTooltip component
 */
interface MapboxTooltipSlots {
  default(): any;
}
```

### Expose

通过 [`useTemplateRef`](https://vuejs.org/api/composition-api-helpers.html#usetemplateref){rel="[\"nofollow\"]"} 访问组件实例。

| Name      | Type                                           |
| --------- | ---------------------------------------------- |
| `hovered` | `() => GeoJSONFeature | undefined`   
 当前激活的要素 |

## Changelog

See commit history for [src/runtime/components/MapboxTooltip.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/MapboxTooltip.vue).


## Sitemap

See the full [sitemap](/sitemap.md) for all pages.