---
title: "<ScriptGoogleMapsStaticMap> - Nuxt Scripts 中文文档"
canonical_url: "https://nuxt-scripts.zhcndoc.com/scripts/google-maps/api/static-map"
last_updated: "2026-09-23T10:33:11.981Z"
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。

```vue
<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) 内部使用，以便在交互式地图加载时显示静态地图。

```vue
<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 }**`。

```vue
<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/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 密钥安全](#api)
- 插槽

## Sitemap

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