> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-docs-automation-github-pr-review.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 横幅

> 在文档站点顶部添加可关闭的横幅，用于显示重要公告、发行说明或通知。

使用横幅在整个文档站点显示重要公告、更新或通知。横幅会显示在每个页面顶部，支持 Markdown 格式，并且你可以将其设置为可关闭。默认情况下，横幅使用你的 `docs.json` 中 `colors.dark` 属性定义的颜色。你可以使用 `type` 属性更改外观，或使用 `color` 完全覆盖背景。

要添加横幅，请在你的 `docs.json` 中使用 `banner` 属性：

<CodeGroup>
  ```json Product announcements wrap theme={null}
  "banner": {
    "content": "🚀 2.0 版本现已上线！查看我们的[更新日志](/changelog)了解详情。",
    "dismissible": true
  }
  ```

  ```json Maintenance notices wrap theme={null}
  "banner": {
    "content": "⚠️ 计划维护：API 将于 12 月 15 日 02:00–04:00（UTC）不可用",
    "type": "warning",
    "dismissible": false
  }
  ```

  ```json Critical notices wrap theme={null}
  "banner": {
    "content": "**需要操作：** 请在 1 月 1 日前轮换你的 API 密钥。[迁移指南](/migration)",
    "type": "critical",
    "dismissible": true
  }
  ```

  ```json Custom color wrap theme={null}
  "banner": {
    "content": "🎉 欢迎参加我们的年度大会！",
    "color": {
      "light": "#7C3AED",
      "dark": "#5B21B6"
    },
    "dismissible": true
  }
  ```
</CodeGroup>

<Note>
  你也可以通过在 `navigation.languages` 中设置 `banner` 来按语言配置横幅。参见[特定语言横幅](#language-specific-banners)。
</Note>

<div id="properties">
  ## 属性
</div>

<ResponseField name="content" type="string" required>
  横幅中显示的文本内容。支持基本的 MDX 格式，包括链接、粗体和斜体文本。不支持自定义组件。
</ResponseField>

<ResponseField name="dismissible" type="boolean">
  是否允许用户关闭横幅。为 `true` 时，会显示关闭按钮。如果用户关闭了横幅，横幅将对该用户保持隐藏，直到你更新横幅内容。默认值为 `false`。
</ResponseField>

<ResponseField name="type" type="string">
  横幅的视觉样式。控制背景颜色，让访客能够快速识别消息的紧急程度。默认值为 `info`。

  * `info`：使用主要品牌色。最适合产品公告和常规更新。
  * `warning`：使用琥珀色背景。最适合警示性通知，例如计划维护或即将到来的弃用。
  * `critical`：使用红色背景。最适合需要立即关注的紧急通知，例如服务中断或必需操作。
</ResponseField>

<ResponseField name="color" type="object">
  使用自定义十六进制值覆盖横幅背景颜色。设置后，将优先于 `type` 所暗示的颜色。横幅文本为白色，因此请选择足够深的背景以保持可读性。

  <Expandable title="color 属性">
    <ResponseField name="light" type="string">
      在浅色模式下使用的十六进制颜色。如果只提供 `dark`，则也会在浅色模式下使用。
    </ResponseField>

    <ResponseField name="dark" type="string">
      在深色模式下使用的十六进制颜色。如果只提供 `light`，则也会在深色模式下使用。
    </ResponseField>
  </Expandable>
</ResponseField>

<div id="language-specific-banners">
  ## 语言特定横幅
</div>

在文档中为每种语言配置不同的横幅内容。在 `docs.json` 的 `navigation.languages` 数组中定义语言特定的横幅。

```json theme={null}
{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "banner": {
          "content": "🚀 Version 2.0 is now live! See our [changelog](/en/changelog) for details.",
          "dismissible": true
        },
        "groups": [
          {
            "group": "Getting started",
            "pages": ["en/overview", "en/quickstart"]
          }
        ]
      },
      {
        "language": "es",
        "banner": {
          "content": "🚀 ¡La versión 2.0 ya está disponible! Consulta nuestro [registro de cambios](/es/changelog) para más detalles.",
          "dismissible": true
        },
        "groups": [
          {
            "group": "Getting started",
            "pages": ["es/overview", "es/quickstart"]
          }
        ]
      }
    ]
  },
  "banner": {
    "content": "🚀 Version 2.0 is now live!",
    "dismissible": true
  }
}
```

<div id="fallback-behavior">
  ### 回退行为
</div>

横幅在确定要显示哪个内容时遵循以下优先顺序：

1. **特定语言横幅**：如果当前语言有 `banner` 配置，则以该配置为准。
2. **全局横幅**：如果不存在特定语言横幅，则显示全局 `banner`。