---
title: "useMapExport"
description: "导出当前地图为图片 dataURL 或直接触发浏览器下载，免 preserveDrawingBuffer 改造。"
seo_title: "useMapExport"
seo_description: "Export the current map as an image dataURL or trigger a browser download, reading the canvas inside the render callback without preserveDrawingBuffer."
canonical_url: "https://mapbox.mhaibaraai.cn/docs/composables/use-map-export"
---
# useMapExport

> 导出当前地图为图片 dataURL 或直接触发浏览器下载，免 preserveDrawingBuffer 改造。

## 简介

`useMapExport` 把当前地图导出为图片：`exportImage` 返回 dataURL，`download` 直接触发浏览器下载。它在 `render` 回调内同步读取画布，无需为地图开启 `preserveDrawingBuffer`（WebGL 缓冲区在帧渲染后即被清空，故必须在该时机取 `toDataURL`）。

> \[\!NOTE\]
> 
> 在 
> 
> <MapboxMap>
> 
>  子树外使用时经 
> 
> options.mapId
> 
>  指定目标地图。导出含外部瓦片的地图可能受跨域画布污染限制。

## 用法

截图预览与下载 PNG：

```vue [UseMapExportExample.vue]
<script setup lang="ts">
const mapId = 'use-map-export-demo'

const preview = ref('')
const { exportImage, download } = useMapExport({ mapId })

async function snapshot() {
  preview.value = await exportImage()
}
</script>

<template>
  <div class="relative h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MapboxMap :map-id="mapId" :options="{ style: 'mapbox://styles/mapbox/light-v11', center: [116.397, 39.908], zoom: 11 }" />
    <div class="absolute left-2 top-2 z-10 flex gap-1">
      <UButton size="sm" @click="snapshot">
        截图预览
      </UButton>
      <UButton size="sm" variant="soft" @click="download({ fileName: 'map.png' })">
        下载 PNG
      </UButton>
    </div>
    <img v-if="preview" :src="preview" alt="地图截图" class="absolute bottom-2 right-2 z-10 h-28 rounded ring ring-default">
  </div>
</template>
```

## API

### `useMapExport()`

创建导出助手。

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

返回 `UseMapExportReturn`：

**exportImage** (`(options?: ExportImageOptions) => Promise<string>`): 导出当前地图为 dataURL。

**download** (`(options?: DownloadOptions) => Promise<void>`): 导出并触发浏览器下载。

### `ExportImageOptions`

**format** (`'image/png' | 'image/jpeg' | 'image/webp'`): 图像格式，默认 'image/png'。

**quality** (`number`): 有损格式质量 0-1，默认 0.92。

### `DownloadOptions`

继承 `ExportImageOptions`，额外：

**fileName** (`string`): 下载文件名，默认 'map.png'。

## Changelog

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


## Sitemap

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