---
title: "MaplibreControl"
description: "通用控件容器，把任意 Vue 内容放进地图控件槽位，可折叠为图标按钮。"
canonical_url: "https://maplibre.mhaibaraai.cn/docs/controls/control"
---
# MaplibreControl

> 通用控件容器，把任意 Vue 内容放进地图控件槽位，可折叠为图标按钮。

## 简介

`MaplibreControl` 把插槽内容挂到 maplibre 的控件槽位（四角停靠，与内置控件一起排列），内容仍在 Vue 组件树内，可以直接使用响应式状态和注入的地图上下文。`MaplibreLayerControl`、`MaplibreBasemapControl`、`MaplibreLegend` 都基于它实现。

- **可折叠**：设置 `collapsible` 后收起为 `#trigger` 插槽提供的图标按钮，点击展开；面板右上角的关闭按钮或 Esc 收起，`dismissible` 为真时点击控件外部也会收起。
- **状态**：`v-model:open` 可受控，不绑定时组件自行维护。

> [!NOTE]
> 
> 控件内的按钮会受 maplibre 控件组样式（
> 
> .maplibregl-ctrl-group button
> 
>  固定 29px 方块）影响，自定义按钮样式时请用不低于它的选择器，或设置 
> 
> :group="false"
> 
>  去掉控件组样式。

## 用法

左上角为常驻控件，右上角为可折叠控件：

```vue [ControlExample.vue]
<script setup lang="ts">
const zoom = ref(11)
</script>

<template>
  <div class="h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MaplibreMap v-model:zoom="zoom" :options="{ style: 'https://tiles.openfreemap.org/styles/liberty', center: [116.397, 39.908] }">
      <!-- 常驻控件：任意 Vue 内容，可直接读取响应式状态 -->
      <MaplibreControl position="top-left">
        <div class="px-2 py-1 text-xs tabular-nums">
          Zoom {{ zoom.toFixed(1) }}
        </div>
      </MaplibreControl>
      <!-- 可折叠控件：收起为图标按钮，点击展开 -->
      <MaplibreControl position="top-right" collapsible label="说明">
        <template #trigger>
          <UIcon name="i-lucide-info" class="size-4" />
        </template>
        <p class="w-44 text-xs">
          MaplibreControl 把任意 Vue 内容放进地图控件槽位，点击外部、按 Esc 或右上角按钮收起。
        </p>
      </MaplibreControl>
    </MaplibreMap>
  </div>
</template>
```

## API

### Props

```ts
/**
 * Props for the MaplibreControl component
 */
interface MaplibreControlProps {
  /**
   * 控件停靠位置；省略用地图默认位置
   */
  position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | undefined;
  /**
   * 是否使用 maplibre 控件组样式（白底圆角卡片）
   * @default true
   */
  group?: boolean | undefined;
  /**
   * 是否可折叠：收起时只显示触发按钮，点击展开，面板内关闭按钮或 Esc 收起
   * @default false
   */
  collapsible?: boolean | undefined;
  /**
   * 可折叠时点击控件外部是否收起；常驻展示的内容（如图例）应关闭
   * @default true
   */
  dismissible?: boolean | undefined;
  /**
   * 折叠按钮的无障碍标签
   */
  label?: string | undefined;
  /**
   * 可折叠时的展开状态
   * @default false
   */
  open?: boolean | undefined;
}
```

### Emits

```ts
/**
 * Emitted events for the MaplibreControl component
 */
interface MaplibreControlEmits {
  update:open: (payload: [value: boolean]) => void;
}
```

### Slots

```ts
/**
 * Slots for the MaplibreControl component
 */
interface MaplibreControlSlots {
  /**
   * 控件内容；可折叠时为展开后的面板
   */
  default(): any;
  /**
   * 折叠按钮内容（通常是图标）
   */
  trigger(): any;
}
```

## Changelog

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


## Sitemap

See the full [sitemap](https://maplibre.mhaibaraai.cn/sitemap.md) for all pages.