---
title: "useLayerTree"
description: "读取地图的图层树，在侧栏等处自绘图层面板，读写即写回各图层组的 v-model。"
canonical_url: "https://maplibre.mhaibaraai.cn/docs/composables/use-layer-tree"
---
# useLayerTree

> 读取地图的图层树，在侧栏等处自绘图层面板，读写即写回各图层组的 v-model。

## 简介

`useLayerTree` 返回地图中所有带 `title` 的 [`MaplibreLayerGroup`](https://maplibre.mhaibaraai.cn/docs/core/layer-group)，顺序即声明顺序。每项的 `setVisible`、`setOpacity` 写回对应组的 `v-model`，因此自绘面板与 [MaplibreLayerControl](https://maplibre.mhaibaraai.cn/docs/controls/layer-control)、[MaplibreLegend](https://maplibre.mhaibaraai.cn/docs/controls/legend) 始终同步。适合把图层面板放在应用侧栏、使用 Nuxt UI 等组件库搭建界面的场景。

> [!NOTE]
> 
> 在 
> 
> <MaplibreMap>
> 
>  子树外使用时，通过 
> 
> options.mapId
> 
>  指定目标地图，并为该地图设置 
> 
> map-id
> 
> 。

## 用法

右侧为用 `USwitch`、`USlider` 自绘的图层面板：

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

const mapId = 'use-layer-tree-demo'
// 地图子树外通过 mapId 读取图层树
const tree = useLayerTree({ mapId })

const zone: 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]]] } }]
}
const river: FeatureCollection = {
  type: 'FeatureCollection',
  features: [{ type: 'Feature', properties: {}, geometry: { type: 'LineString', coordinates: [[116.33, 39.93], [116.39, 39.91], [116.47, 39.92]] } }]
}
</script>

<template>
  <div class="grid h-115 w-full grid-cols-[1fr_12rem] overflow-hidden rounded-(--ui-radius) border border-default">
    <MaplibreMap :map-id="mapId" :options="{ style: 'https://tiles.openfreemap.org/styles/positron', center: [116.4, 39.92], zoom: 11 }">
      <MaplibreLayerGroup title="规划片区">
        <MaplibreLayer layer-id="tree-zone" type="fill" :source="{ type: 'geojson', data: zone }" :paint="{ 'fill-color': '#f59e0b', 'fill-opacity': 0.4 }" />
      </MaplibreLayerGroup>
      <MaplibreLayerGroup title="河流">
        <MaplibreLayer layer-id="tree-river" type="line" :source="{ type: 'geojson', data: river }" :paint="{ 'line-color': '#0ea5e9', 'line-width': 4 }" />
      </MaplibreLayerGroup>
    </MaplibreMap>
    <aside class="flex flex-col gap-3 border-l border-default p-3">
      <div v-for="item in tree" :key="item.id" class="flex flex-col gap-1">
        <USwitch :model-value="item.visible" :label="item.title" size="sm" @update:model-value="item.setVisible($event)" />
        <USlider
          :model-value="item.opacity"
          :min="0"
          :max="1"
          :step="0.05"
          size="sm"
          :disabled="!item.visible"
          @update:model-value="item.setOpacity($event ?? 1)"
        />
      </div>
    </aside>
  </div>
</template>
```

## API

### `useLayerTree()`

**options.mapId** (`string`): 目标地图 id；在 <MaplibreMap> 子树外使用时必填。

返回 `ComputedRef<LayerTreeItem[]>`，每项包含：

**id** (`string`): 组的唯一标识。

**title** (`string`): 组标题。

**visible** (`boolean`): 组自身的显隐开关。

**opacity** (`number`): 组自身的透明度，范围 0..1。

**legend** (`LegendItem[]`): 图例项，legend prop 优先，否则由子图层颜色推导。

**setVisible** (`(visible: boolean) => void`): 写回组的 v-model:visible。

**setOpacity** (`(opacity: number) => void`): 写回组的 v-model:opacity，超出 0..1 的值会被钳制。

## Changelog

See commit history for [src/runtime/composables/useLayerTree.ts](https://github.com/mhaibaraai/movk-maplibre/commits/main/src/runtime/composables/useLayerTree.ts).


## Sitemap

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