mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
4b465465dd
Generated-By: mintlify-agent Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
139 lines
4.6 KiB
Plaintext
139 lines
4.6 KiB
Plaintext
---
|
||
title: "横幅"
|
||
description: "在文档站点顶部添加可关闭的横幅，用于显示重要公告、发行说明或通知。"
|
||
keywords: ["banner", "announcements", "site-wide"]
|
||
boost: 3
|
||
---
|
||
|
||
使用横幅在整个文档站点显示重要公告、更新或通知。横幅会显示在每个页面顶部，支持 Markdown 格式，并且你可以将其设置为可关闭。默认情况下，横幅使用你的 `docs.json` 中 `colors.dark` 属性定义的颜色。你可以使用 `type` 属性更改外观，或使用 `color` 完全覆盖背景。
|
||
|
||
要添加横幅，请在你的 `docs.json` 中使用 `banner` 属性：
|
||
|
||
<CodeGroup>
|
||
```json Product announcements wrap
|
||
"banner": {
|
||
"content": "🚀 2.0 版本现已上线！查看我们的[更新日志](/changelog)了解详情。",
|
||
"dismissible": true
|
||
}
|
||
```
|
||
|
||
```json Maintenance notices wrap
|
||
"banner": {
|
||
"content": "⚠️ 计划维护：API 将于 12 月 15 日 02:00–04:00（UTC）不可用",
|
||
"type": "warning",
|
||
"dismissible": false
|
||
}
|
||
```
|
||
|
||
```json Critical notices wrap
|
||
"banner": {
|
||
"content": "**需要操作：** 请在 1 月 1 日前轮换你的 API 密钥。[迁移指南](/migration)",
|
||
"type": "critical",
|
||
"dismissible": true
|
||
}
|
||
```
|
||
|
||
```json Custom color wrap
|
||
"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
|
||
{
|
||
"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`。
|