---
title: "<ScriptGoogleMapsStaticMap> - Nuxt Scripts 中文文档"
canonical_url: "https://nuxt-scripts.zhcndoc.com/scripts/google-maps/api/static-map"
last_updated: "2026-08-11T09:33:15.634Z"
meta:
  description: "直接从 Google 渲染一张 Google Maps 静态 API 图片。"
  "og:description": "直接从 Google 渲染一张 Google Maps 静态 API 图片。"
  "og:title": "<ScriptGoogleMapsStaticMap>  -  Nuxt Scripts 中文文档"
---

Nuxt Scripts home

在 GitHub 上查看 Nuxt Scripts

**Api**

# **\<ScriptGoogleMapsStaticMap>**

[复制给 LLM](https://nuxt-scripts.zhcndoc.com/scripts/google-maps/api/static-map.md)

渲染一张 [**~~Google Maps 静态 API~~**](https://developers.google.com/maps/documentation/maps-static) 图片。单独使用用于静态地图预览，或放入 [`<ScriptGoogleMaps>`](https://nuxt-scripts.zhcndoc.com/scripts/google-maps/api/script-google-maps) 的 `#placeholder` 插槽中作为加载占位符。

## 用法

### 独立使用

显示静态地图，无需加载交互式 Google Maps JavaScript API。

```
<template>
  <ScriptGoogleMapsStaticMap
    center="51.95,19.13"
    :zoom="7"
    width="100%"
    height="300"
  />
</template>
```

### 作为占位符

在 [`<ScriptGoogleMaps>`](https://nuxt-scripts.zhcndoc.com/scripts/google-maps/api/script-google-maps) 内部使用，以便在交互式地图加载时显示静态地图。

```
<template>
  <ScriptGoogleMaps
    :map-options="{
      center,
      zoom: 7,
    }"
  >
    <template #placeholder>
      <ScriptGoogleMapsStaticMap
        :center="center"
        :zoom="7"
        loading="eager"
        maptype="satellite"
      />
    </template>
  </ScriptGoogleMaps>
</template>
```

## 属性

| **属性** | **类型** | **默认值** | **描述** |
| --- | --- | --- | --- |
| `center` | `string \| { lat: number, lng: number }` |  | 地图中心，可使用地址、`"lat,lng"` 字符串或 `LatLngLiteral`。 |
| `zoom` | `number` | `15` | 缩放级别（0 到 21）。 |
| `size` | `` `${number}x${number}` `` | auto | API 请求的明确像素尺寸。省略时，在挂载时测量已渲染容器的尺寸。在 SSR 期间回退为 `640x400`。 |
| `scale` | `1 \| 2` | `2` | 设备像素比。 |
| `format` | `StaticMapFormat` |  | 图像格式：`png`、`jpg`、`gif`、`png8`、`png32`、`jpg-baseline`。 |
| `maptype` | `StaticMapType` |  | 地图类型：`roadmap`、`satellite`、`terrain`、`hybrid`。 |
| `mapId` | `string` |  | 基于云端的地图样式 ID。 |
| `markers` | `string \| string[]` |  | [**~~标记描述符~~**](https://developers.google.com/maps/documentation/maps-static/start#Markers)。 |
| `path` | `string \| string[]` |  | [**~~折线路径描述符~~**](https://developers.google.com/maps/documentation/maps-static/start#Paths)。 |
| `visible` | `string \| string[]` |  | 地图上应显示的地点。 |
| `style` | `string \| string[] \| MapTypeStyle[]` |  | 地图样式。接受原始 Static Maps API 样式字符串或 Google Maps JS API `MapTypeStyle[]` 对象。 |
| `language` | `string` |  | 地图标签的语言代码。 |
| `region` | `string` |  | 区域偏向。 |
| `signature` | `string` |  | 用于直接请求的 [**~~Google Maps URL 签名~~**](https://developers.google.com/maps/digital-signature)。将其与明确的 `apiKey` 一起使用；签名不能替代密钥。 |
| `apiKey` | `string` |  | API 密钥覆盖值。省略时回退到公开的 `googleMaps` 注册表密钥。 |
| `width` | `number \| string` | `640` | 容器的 CSS 宽度。 |
| `height` | `number \| string` | `400` | 容器的 CSS 高度。 |
| `loading` | `'eager' \| 'lazy'` | `'lazy'` | 图像加载策略。 |
| `objectFit` | `string` | `'cover'` | 容器内 `<img>` 的对象适配方式。 |
| `imgAttrs` | `ImgHTMLAttributes` |  | `<img>` 元素的其他属性。 |

## 尺寸处理

当未提供 `size` 时，组件：

1. **客户端**：在挂载时测量容器的像素尺寸，并限制在 [**~~静态地图 API 限制~~**](https://developers.google.com/maps/documentation/maps-static/start) 的 640x640 以内（保持纵横比）。
2. **SSR**：如果 `width`/ `height` 属性都是像素值，则从中派生。
3. **回退**：使用 `640x400`。

明确设置 `size` 以绕过自动测量。

## API 密钥安全

该组件直接从 `maps.googleapis.com` 加载图像。在生产环境使用前，请将密钥限制为仅适用于您的网站和 Maps Static API。请参阅 [**~~Google Maps Platform 安全指南~~**](https://developers.google.com/maps/api-security-best-practices)。

Google 数字签名涵盖完整的请求 URL。传递 `signature` 时，也请显式传递 `size`，并确保每个已签名的参数保持稳定。请在受信任的服务器上生成签名。切勿将 URL 签名密钥暴露给浏览器。

## 插槽

**default**

使用自定义模板覆盖 `<img>` 元素。接收包含计算后的静态地图 URL 的 `{ src }`。

```
<template>
  <ScriptGoogleMapsStaticMap center="51.95,19.13" :zoom="7">
    <template #default="{ src }">
      <img :src="src" alt="自定义静态地图" class="rounded-lg shadow">
    </template>
  </ScriptGoogleMapsStaticMap>
</template>
```

[编辑此页](https://github.com/nuxt/scripts/edit/main/docs/content/scripts/google-maps/2.api/1b.static-map.md)

[供 LLM 使用的 Markdown](https://nuxt-scripts.zhcndoc.com/scripts/google-maps/api/static-map.md)

[**useScriptGoogleMaps()** 加载 Google 地图 SDK，并直接从组合式函数访问其 API。](https://nuxt-scripts.zhcndoc.com/scripts/google-maps/api/use-script-google-maps) [**\<ScriptGoogleMapsMarker>** 添加一个支持响应式的高级标记，可选择使用自定义 Vue 内容。](https://nuxt-scripts.zhcndoc.com/scripts/google-maps/api/marker)

**本页内容 **

- 用法
- 属性
- 尺寸处理
- API 密钥安全
- 插槽