---
title: "MapboxLayerGroup"
description: "图层组，为子图层提供统一的插入锚点与组级显隐开关。"
seo_title: "MapboxLayerGroup Component"
seo_description: "MapboxLayerGroup groups child layers under a shared beforeId insertion anchor and a single group-level visibility toggle."
canonical_url: "https://mapbox.mhaibaraai.cn/docs/core/layer-group"
---
# MapboxLayerGroup

> 图层组，为子图层提供统一的插入锚点与组级显隐开关。

## 简介

`MapboxLayerGroup` 把多个子 [MapboxLayer](/docs/core/layer) 归为一组：经 `beforeId` 提供统一的缺省插入锚点，经 `visible` 做组级显隐开关（组开关优先于子图层自身的 `layout.visibility`）。适合「一组相关图层一起显示/隐藏」的场景。

## 用法

切换 `visible` 即可整组开关，无需逐层设置可见性：

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

const visible = ref(true)

const data: FeatureCollection = {
  type: 'FeatureCollection',
  features: [{
    type: 'Feature',
    properties: {},
    geometry: {
      type: 'Polygon',
      coordinates: [[[116.36, 39.95], [116.44, 39.95], [116.44, 39.89], [116.36, 39.89], [116.36, 39.95]]]
    }
  }]
}
</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.4, 39.92], zoom: 11 }">
      <div class="absolute left-3 top-3 z-10">
        <UButton size="xs" color="neutral" variant="solid" @click="visible = !visible">
          {{ visible ? 'Hide group' : 'Show group' }}
        </UButton>
      </div>
      <!-- 组级 visible 统一开关子图层，无需逐层设置 layout.visibility -->
      <MapboxLayerGroup :visible="visible">
        <MapboxLayer
          layer-id="zone-fill"
          type="fill"
          :source="{ type: 'geojson', data }"
          :paint="{ 'fill-color': '#f43f5e', 'fill-opacity': 0.3 }"
        />
        <MapboxLayer
          layer-id="zone-line"
          type="line"
          :source="{ type: 'geojson', data }"
          :paint="{ 'line-color': '#f43f5e', 'line-width': 2 }"
        />
      </MapboxLayerGroup>
    </MapboxMap>
  </div>
</template>
```

## API

### Props

```ts
/**
 * Props for the MapboxLayerGroup component
 */
interface MapboxLayerGroupProps {
  /**
   * 组内图层缺省插入到该图层之前
   */
  beforeId?: string | undefined;
  /**
   * 组级显隐
   * @default "true"
   */
  visible?: boolean | undefined;
}
```

### Slots

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

## Changelog

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


## Sitemap

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