---
title: "useMaplibreImage"
description: "注册 symbol 图层可用的命名图片，样式切换后自动补回，卸载时移除。"
canonical_url: "https://maplibre.mhaibaraai.cn/docs/composables/use-maplibre-image"
---
# useMaplibreImage

> 注册 symbol 图层可用的命名图片，样式切换后自动补回，卸载时移除。

## 简介

`useMaplibreImage` 加载远程图片并注册为样式图片，供 symbol 图层经 `icon-image` 引用。`setStyle` 清空样式图片后会经 `onReady` 自动补回，`url` 变化时原地换图，组件卸载时移除。返回 `loaded` 状态便于在加载完成前给出占位反馈。

> [!NOTE]
> 
> 设 
> 
> sdf: true
> 
>  注册为 SDF 图标后，可经 
> 
> icon-color
> 
>  着色。在 
> 
> <MaplibreMap>
> 
>  子树外使用时经 
> 
> options.mapId
> 
>  指定目标地图。

## 用法

注册一张远程图片，symbol 图层经 `icon-image` 引用：

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

const mapId = 'use-maplibre-image-demo'

const data: FeatureCollection = {
  type: 'FeatureCollection',
  features: [
    { type: 'Feature', properties: {}, geometry: { type: 'Point', coordinates: [116.397, 39.908] } }
  ]
}

const { loaded } = useMaplibreImage('demo-cat', 'https://upload.wikimedia.org/wikipedia/commons/7/7c/201408_cat.png', { mapId })
</script>

<template>
  <div class="relative h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MaplibreMap :map-id="mapId" :options="{ style: 'https://tiles.openfreemap.org/styles/positron', center: [116.397, 39.908], zoom: 13 }">
      <MaplibreLayer
        v-if="loaded"
        layer-id="cats"
        type="symbol"
        :source="{ type: 'geojson', data }"
        :layout="{ 'icon-image': 'demo-cat', 'icon-size': 0.25, 'icon-allow-overlap': true }"
      />
    </MaplibreMap>
    <div class="absolute left-2 top-2 z-10 rounded bg-default/90 px-2 py-1 text-xs text-default ring ring-default">
      图片加载：{{ loaded ? '完成' : '加载中…' }}
    </div>
  </div>
</template>
```

## API

### `useMaplibreImage()`

注册命名图片。

**name** (`string`) *required*: 图片注册名称，供 icon-image 引用。

**url** (`MaybeRefOrGetter<string>`) *required*: 图片 URL 地址；变化时加载新图并替换同名图片，期间 loaded 保持 true，加载失败则保留旧图。

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

**options.sdf** (`boolean`): 作为 SDF 图标（可经 icon-color 着色）。

**options.pixelRatio** (`number`): 像素密度，默认 1。

返回 `{ loaded: Ref<boolean> }`：图片是否已加载完成。

## Changelog

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


## Sitemap

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