mintlify__docs/zh/customize/custom-scripts.mdx

---
title: "自定义脚本"
description: "为你的文档站点添加自定义 JavaScript 和 CSS，用于分析、小组件、样式覆盖、第三方集成和 API Playground 服务器变量。支持身份验证、租户切换和注销后的运行时更新，值仅保存在当前会话内存中，不会写入浏览器存储。"
keywords: ["CSS", "JavaScript", "Tailwind CSS", "样式定制", "API Playground", "服务器变量"]
---

使用 CSS 为 HTML 元素设置样式，或添加自定义 CSS 和 JavaScript，全面定制文档的外观与使用体验。

<div id="style-with-tailwind-css">
  ## 使用 Tailwind CSS 进行样式设计
</div>

使用 Tailwind CSS v3 为 HTML 元素设置样式。你可以控制布局、间距、颜色及其他视觉属性。常见的类包括：

* `w-full` - 宽度占满
* `aspect-video` - 16:9 比例
* `rounded-xl` - 大圆角
* `block`, `hidden` - 显示控制
* `dark:hidden`, `dark:block` - 深色模式下的可见性

不支持 Tailwind CSS 的任意值语法。若需自定义值，请改用 `style` 属性。

```html
<img style={{ width: '350px', margin: '12px auto' }} src="/path/image.jpg" />
```

<Warning>
  使用 `style` 属性可能会在页面加载时导致布局位移，尤其是在自定义模式的页面中。请改用 Tailwind CSS 类或自定义 CSS 文件，以避免位移或闪烁。
</Warning>

<div id="add-custom-css">
  ## 添加自定义 CSS
</div>

Mintlify 会自动在你的文档站点的每个页面中包含内容目录下的任何 `.css` 文件，方式与包含自定义 `.js` 文件相同。你无需在 `docs.json` 或 MDX 文件中导入或引用该文件。

要添加自定义样式，请在内容目录的任意层级创建一个 `.css` 文件（例如 `style.css`）。你在其中定义的任何类名、ID 选择器或元素选择器都可以在所有 MDX 文件中使用。

例如，在 `style.css` 中定义一个类：

```css
.my-callout {
  border-radius: 1rem;
  background: #f0f9ff;
  padding: 1rem;
}
```

然后在任意 MDX 文件中通过 `className` 属性使用它：

```mdx
<div className="my-callout">
  内容在这里。
</div>
```

你可以在同一个元素上将自定义类名与 [Tailwind CSS](/zh/customize/custom-scripts#style-with-tailwind-css) 类组合使用。

自定义 CSS 会应用于站点的每个页面，包括自定义模式页面和落地页。若要将样式限定到特定页面或部分，请使用 [数据属性](#data-attributes)中介绍的 `html[data-current-path="..."]` 属性选择器。

引用和常用元素的样式可能会发生变化。请谨慎使用自定义样式，因为未来更新中可能出现不兼容的变更。

例如，你可以添加以下 `style.css` 文件以自定义导航栏和页脚的样式。

```css
#navbar {
  background: #fffff2;
  padding: 1rem;
}

footer {
  margin-top: 2rem;
}
```

Mintlify 提供两种类型的 CSS 定位钩子：

- **ID 选择器**：页面级唯一元素，在 CSS 中使用 `#value { }` 定位
- **元素选择器**：组件和布局元素，在 CSS 中使用 `value { }` 定位（无 `#` 或 `.` 前缀）

<Tip>
  使用"检查元素"来定位你要自定义的元素引用。
</Tip>

<div id="id-selectors">
  ### ID 选择器
</div>

每个 ID 在每个页面上只出现一次。在 CSS 中使用 `#value` 来定位。例如，`#navbar { background: red; }`。

<AccordionGroup>
<Accordion title="页面布局">
  - `#body-content`—页面主体的最外层容器。
  - `#content-area`—主要内容区域，不包括侧边栏和目录。
  - `#content`—内容区域内的内部内容元素。
  - `#header`—页面级头部元素。
  - `#banner`—显示在导航栏上方的公告横幅。
  - `#footer`—页脚。也可用作元素选择器：`footer`。
  - `#page-title`—每个页面顶部的 `<h1>` 标题。
  - `#pagination`—底部分页栏，包含上一页和下一页链接。
  - `#panel`—浮动面板覆盖层。也可用作元素选择器：`panel`。
  - `#background-color`—页面背景颜色元素。
</Accordion>
<Accordion title="导航">
  - `#navbar`—顶部导航栏。
  - `#topbar-cta-button`—顶栏中的行动号召按钮。
  - `#mobile-nav`—移动端导航覆盖层。
  - `#mobile-nav-content`—移动端导航覆盖层内的内容区域。
</Accordion>
<Accordion title="侧边栏">
  - `#sidebar`—侧边栏导航面板。
  - `#sidebar-content`—侧边栏内可滚动的内容区域。
</Accordion>
<Accordion title="目录">
  - `#table-of-contents`—页面右侧的目录面板。
  - `#table-of-contents-layout`—目录的布局容器。
  - `#table-of-contents-content`—目录内可滚动的内容。
</Accordion>
<Accordion title="搜索">
  - `#search-bar-entry`—顶栏中的搜索栏触发器。
  - `#search-bar-entry-mobile`—移动端的搜索栏触发器。
  - `#search-input`—搜索模态框内的文本输入字段。
</Accordion>
<Accordion title="AI 助手">
  - `#assistant-entry`—顶栏中的 AI 助手按钮。
  - `#assistant-entry-mobile`—移动端的 AI 助手按钮。
  - `#chat-assistant-sheet`—AI 助手聊天面板。
  - `#chat-assistant-textarea`—AI 助手面板内的文本输入。
</Accordion>
<Accordion title="API 参考">
  - `#request-example`—API playground 中的请求示例面板。
  - `#response-example`—API playground 中的响应示例面板。
  - `#api-playground-input`—API playground 的输入区域。
  - `#endpoints-menu-trigger`—打开端点选择器下拉菜单的按钮。
</Accordion>
<Accordion title="代码块">
  - `#ask-assistant-code-block-button`—代码块上显示的“询问助手”按钮。
  - `#code-snippet-feedback-button`—代码片段上的反馈按钮。
  - `#code-snippet-feedback-textarea`—代码片段反馈表单内的文本区域。
</Accordion>
<Accordion title="反馈">
  - `#feedback-thumbs-up`—页面底部的点赞按钮。
  - `#feedback-thumbs-down`—页面底部的点踩按钮。
  - `#feedback-form`—点踩后显示的反馈表单。
  - `#feedback-form-input`—反馈表单内的文本输入。
  - `#feedback-form-cancel`—反馈表单内的取消按钮。
  - `#feedback-form-submit`—反馈表单内的提交按钮。
</Accordion>
<Accordion title="页面上下文菜单">
  - `#page-context-menu`—当前页面的上下文选项菜单。
  - `#page-context-menu-button`—触发页面上下文菜单的按钮。
</Accordion>
<Accordion title="本地化">
  - `#localization-select-trigger`—打开语言选择器的按钮。
  - `#localization-select-content`—语言选择器的下拉内容。
  - `#localization-select-item`—选择器中的单个语言选项。
</Accordion>
<Accordion title="变更日志">
  - `#changelog-filters`—变更日志页面上的过滤控件。
  - `#changelog-filters-content`—变更日志过滤面板内的内容区域。
</Accordion>
<Accordion title="多视图">
  - `#multi-view-dropdown`—用于切换文档视图的下拉菜单。
</Accordion>
<Accordion title="文本选择">
  - `#text-selection-tooltip`—在页面上选择文本时显示的提示框。
  - `#text-selection-tooltip-button`—文本选择提示框内的操作按钮。
</Accordion>
</AccordionGroup>

<div id="element-selectors">
  ### 元素选择器
</div>

这些元素可以在页面上出现多个实例。在 CSS 中使用 `value` 来定位。例如，`accordion { border: 1px solid red; }`。

<AccordionGroup>
  <Accordion title="内容组件">
    - `accordion`—可折叠的手风琴项。
    - `accordion-group`—包含多个手风琴的容器。
    - `callout`—标注块（Note、Warning、Tip 等）。
    - `card`—单个卡片元素。
    - `card-group`—包含多个卡片的容器。已弃用，推荐使用 `columns`，但为向后兼容而保留。
    - `columns`—多列布局容器。
    - `code-block`—代码块元素。
    - `code-block-icon`—代码块头部显示的图标。
    - `code-block-copy-button`—代码块上显示的复制按钮。可通过 `.code-block-copy-button { display: none; }` 隐藏。
    - `code-block-fade-overlay`—折叠代码块底部显示的渐隐遮罩。
    - `code-group`—带标签页的代码块组。
    - `expandable`—可展开区域元素。
    - `frame`—用于图片或嵌入内容的框架容器。
    - `icon`—内联图标元素。
    - `mermaid`—Mermaid 图表容器。
    - `step`—步骤序列中的单个步骤。
    - `steps`—编号步骤容器。
    - `tab-icon`—标签页中显示的图标。
    - `tabs`—标签页内容容器。
    - `tile`—Tile 组件元素。
    - `tooltip`—提示框元素。
    - `update`—变更日志更新条目。
  </Accordion>
  <Accordion title="页面布局">
    - `mdx-content`—已渲染的 MDX 内容区域。
    - `panel`—浮动面板组件。也可用作 ID 选择器：`#panel`。
    - `eyebrow`—页面标题上方显示的小标签。
    - `link`—锚点链接元素。
    - `breadcrumb-list`—面包屑导航列表。
    - `breadcrumb-item`—单个面包屑项。
  </Accordion>
  <Accordion title="顶栏导航">
    - `nav-logo`—导航栏中的 Logo。
    - `navbar-link`—导航栏内的链接元素。
    - `nav-anchors`—顶栏中锚点链接的容器。
    - `nav-anchor`—顶栏中的单个锚点链接。
    - `nav-tabs`—顶部导航中的标签页栏。
    - `nav-tabs-item`—顶部导航标签页栏中的单个标签页项。
    - `mobile-nav-tabs-item`—移动导航标签页栏中的标签页项。
    - `topbar-right-container`—顶栏的右侧部分。
    - `nav-tag-pill`—导航中显示的标签徽章。
    - `nav-tag-pill-text`—导航标签徽章中的文本。
  </Accordion>
  <Accordion title="顶栏下拉菜单">
    - `nav-dropdown-trigger`—打开导航下拉菜单的按钮。
    - `nav-dropdown-content`—导航下拉菜单的内容容器。
    - `nav-dropdown-item`—导航下拉菜单中的单个项。
    - `nav-dropdown-item-text-container`—下拉菜单项中的文本容器。
    - `nav-dropdown-item-title`—下拉菜单项中的标题文本。
    - `nav-dropdown-item-description`—下拉菜单项中的描述文本。
    - `nav-dropdown-item-icon`—下拉菜单项中的图标。
  </Accordion>
  <Accordion title="产品选择器">
    - `nav-dropdown-products-selector-trigger`—打开产品选择器下拉菜单的按钮。
    - `nav-dropdown-products-selector-content`—产品选择器的内容容器。
    - `nav-dropdown-products-selector-item`—选择器中的单个产品。
    - `nav-dropdown-products-selector-item-title`—产品选择器项的标题。
    - `nav-dropdown-products-selector-item-description`—产品选择器项的描述。
    - `nav-dropdown-products-selector-item-icon`—产品选择器项的图标。
  </Accordion>
  <Accordion title="侧边栏">
    - `sidebar-group`—侧边栏中的相关链接分组。
    - `sidebar-group-icon`—侧边栏分组的图标。
    - `sidebar-group-header`—侧边栏分组的标题标签。
    - `sidebar-title`—侧边栏中的顶级标题。
    - `sidebar-nav-group-divider`—侧边栏导航分组之间的分隔线。
  </Accordion>
  <Accordion title="目录">
    - `toc`—目录容器。
    - `toc-item`—目录中的单个标题条目。
  </Accordion>
  <Accordion title="页脚">
    - `footer`—标准页脚。也可用作 ID 选择器：`#footer`。
    - `advanced-footer`—包含额外列或内容的扩展页脚。
  </Accordion>
  <Accordion title="分页">
    - `pagination-prev`—分页栏中的上一页链接。
    - `pagination-next`—分页栏中的下一页链接。
    - `pagination-title`—分页栏中显示的页面标题。
  </Accordion>
  <Accordion title="API 参考">
    - `api-section`—单个 API 端点的完整部分。
    - `api-section-heading`—API 端点部分的标题区域。
    - `api-section-heading-title`—API 端点部分标题中的标题文本。
    - `api-section-heading-subtitle`—API 端点部分标题中的副标题。
    - `field`—API 参考中的参数或属性字段。
    - `option-dropdown`—用于在 API 选项之间选择的下拉菜单。
    - `tryit-button`—打开 API playground 的 "Try it" 按钮。
    - `method-pill`—端点上的 HTTP 方法徽章（GET、POST 等）。
    - `method-nav-pill`—侧边栏导航中显示的 HTTP 方法徽章。
    - `prompt`—API 参考中的 prompt 组件。
  </Accordion>
  <Accordion title="AI 助手">
    - `chat-assistant-sheet`—AI 助手面板容器。
    - `chat-assistant-sheet-header`—AI 助手面板的头部。
    - `chat-assistant-sheet-content`—AI 助手面板的内容区域。
    - `chat-assistant-input`—AI 助手面板内的文本输入。
    - `chat-assistant-floating-input`—AI 助手的浮动输入变体。
    - `chat-assistant-send-button`—AI 助手面板中的发送按钮。
    - `chat-assistant-disclaimer-text`—AI 助手面板中显示的免责声明文本。
    - `chat-assistant-payload-item`—助手面板中的单条消息或结果项。
    - `starter-question-text`—空助手面板中显示的建议起始问题。
  </Accordion>
  <Accordion title="反馈">
    - `feedback-toolbar`—包含页面反馈控件的工具栏。
    - `contextual-feedback-container`—上下文内联反馈的容器。
    - `contextual-feedback-form`—内联上下文反馈表单。
    - `contextual-feedback-form-title`—上下文反馈表单的标题。
    - `contextual-feedback-input`—上下文反馈表单内的文本输入。
    - `contextual-feedback-button`—上下文反馈表单内的操作按钮。
    - `contextual-feedback-form-submit-button`—上下文反馈表单的提交按钮。
  </Accordion>
  <Accordion title="代码片段反馈">
    - `code-snippet-feedback-popover-content`—代码片段反馈的弹出内容。
    - `code-snippet-feedback-form`—代码片段的反馈表单。
    - `code-snippet-feedback-textarea`—代码片段反馈表单内的文本区域。
    - `code-snippet-feedback-form-title`—代码片段反馈表单的标题。
    - `code-snippet-feedback-form-description`—代码片段反馈表单中的描述文本。
    - `code-snippet-feedback-form-submit-button`—代码片段反馈表单的提交按钮。
  </Accordion>
  <Accordion title="身份验证">
    - `login-link`—发起登录流程的链接。
    - `logout-link`—发起登出流程的链接。
  </Accordion>
  <Accordion title="多视图">
    - `multi-view-item`—多视图切换器中的单个视图选项。
    - `multi-view-dropdown`—用于在多个视图之间选择的下拉菜单。
    - `multi-view-dropdown-trigger`—打开多视图下拉菜单的按钮。
    - `multi-view-dropdown-content`—多视图下拉菜单的内容区域。
    - `multi-view-dropdown-item`—多视图下拉菜单中的单个项。
  </Accordion>
  <Accordion title="目录页">
    - `directory`—目录页的根容器。
    - `directory-group`—目录内的相关页面分组。
    - `directory-page`—目录中的单个页面条目。
    - `directory-card`—目录中以卡片形式显示的页面条目。
  </Accordion>
  <Accordion title="404 页面">
    - `not-found-container`—404 页面的根容器。
    - `not-found-status-code`—404 页面上的状态码显示。
    - `not-found-title`—404 页面上的标题。
    - `not-found-description`—404 页面上的描述文本。
    - `not-found-recommended-pages-list`—404 页面上显示的推荐页面列表。
    - `not-found-recommended-page-link`—推荐页面列表中的单个链接。
  </Accordion>
  <Accordion title="颜色">
    - `color`—色彩样本元素。
    - `color-row`—色彩样本分组行。
    - `color-item`—颜色行中的单个颜色项。
  </Accordion>
  <Accordion title="文件树">
    - `tree`—文件树容器。
    - `tree-folder`—文件树中的文件夹条目。
    - `tree-file`—文件树中的文件条目。
  </Accordion>
  <Accordion title="数据属性">
    部分元素暴露了可用作 CSS 选择器的数据属性。

    激活状态 (`data-active`)：

    - `nav-dropdown-item[data-active]`—导航下拉菜单中的激活项。
    - `mobile-nav-tabs-item[data-active]`—移动导航中的激活标签页。
    - `sidebar-group[data-active]`—激活的侧边栏分组。
    - `#sidebar-content li[data-active]`—激活的侧边栏链接。
    - `.nav-tabs-item[data-active]`—激活的顶部导航标签页。仅适用于简单标签页；带有下拉菜单的标签页不会接收 `data-active`。注意前导的 `.`：它针对的是标准 `<a>` 元素上的类，与大多数使用自定义元素名称的其他组件不同。
    - `toc-item[data-active]`—激活的目录项。
    - `toc-item[data-active-deepest]`—最深层激活的目录项。仅出现在当前可见的确切标题上，与 `data-active` 不同，后者也会设置在其父级标题上。

    组件名称 (`data-component-name`)：

    使用 `data-component-name` 来定位特定的 UI 组件，该选择器在内部类名更改后仍然有效。

    - `[data-component-name="mermaid-container"]`—Mermaid 图表容器，包含缩放控件覆盖层。
    - `[data-component-name="mermaid-controls-wrapper"]`—Mermaid 缩放和平移控件。
    - `[data-component-name="primary-header-button"]`—主要头部按钮。仅限 Sequoia 主题。
    - `[data-component-name="theme-toggle"]`—主题切换开关。

    组件部分 (`data-component-part`)：

    使用 `data-component-part` 来定位组件内的子元素。

    - `[data-component-part="contact-support-button"]`—助手面板中联系支持链接的 `<a>` 包装器。
    - `[data-component-part="contact-support-icon"]`—包裹图标的 `<span>`。
    - `[data-component-part="contact-support-text"]`—包含标签的 `<p>` 元素。

    Badge 属性：

    - `[data-badge]`—任何 badge 元素。
    - `[data-badge][data-color="blue"]`—按颜色筛选的 badge。
    - `[data-badge][data-size="sm"]`—按尺寸筛选的 badge。

    当前路径 (`data-current-path`)：

    使用 `data-current-path` 在特定页面或子路径上应用自定义 CSS 样式。

    - `html[data-current-path="/"]`—匹配根页面。
    - `html[data-current-path="/quickstart"]`—匹配特定页面。
    - `html[data-current-path^="/api-reference/"]`—匹配某个部分下的任何页面。
  </Accordion>
</AccordionGroup>

<div id="custom-javascript">
  ## 自定义 JavaScript
</div>

自定义 JS 允许你在全局添加自定义可执行代码，相当于在每个页面都插入一个包含 JS 代码的 `<script>` 标签。

Mintlify 会将文档站点的 content 目录中的任何 `.js` 文件注入到每个文档页面，包括自定义模式页面和落地页。自定义 JavaScript 文件会在页面变为可交互后运行，无法将其作用范围限定到特定页面；当存在多个 `.js` 文件时，它们都会执行，但执行顺序无法保证。

若要加载第三方脚本，请从你的自定义 JavaScript 文件中注入 `<script>` 元素，而不是在 MDX 中直接添加原始的 `<script src="...">` 标签：

```js
const script = document.createElement('script');
script.src = 'https://example.com/widget.js';
script.async = true;
document.head.appendChild(script);
```

比如，你可以添加下面的 `ga.js` 文件，在整个文档站点启用 [Google Analytics](https://marketingplatform.google.com/about/analytics)。

```js
window.dataLayer = window.dataLayer || [];
function gtag() {
  dataLayer.push(arguments);
}
gtag('js', new Date());

gtag('config', 'TAG_ID');
```

<Warning>
  请谨慎使用，避免造成安全漏洞。
</Warning>

<div id="set-api-playground-server-variables">
  ### 设置 API Playground 服务器变量
</div>

使用 `window.mintlify.api.playground.setServerVariables`，通过自定义 JavaScript 预填充 [OpenAPI 服务器变量](/zh/api-playground/openapi-setup)。当页面加载后才能获得这些值时使用此方法，例如身份验证 SDK 初始化完成或租户发生变化时。该方法会立即更新已打开的 API Playground，也会应用到之后打开的 Playground。

传入一个值为字符串的对象。每次调用都会替换完整的运行时覆盖值。省略的键会被移除，无效值会被忽略。运行时值优先于 OpenAPI 默认值和已保存的服务器变量。

```js Set API Playground server variables
window.mintlify.api.playground.setServerVariables({
  tenantDomain: 'example.us.auth0.com',
});
```

当这些值不再适用时调用 `window.mintlify.api.playground.clearServerVariables()`，例如注销后。清除后，API Playground 会回退到其他已配置的值。

```js Clear API Playground server variables
window.mintlify.api.playground.clearServerVariables();
```

在客户端初始化之前发出的调用会进入队列，并在客户端初始化时应用。覆盖值仅在当前页面会话的内存中保留。不会写入 `localStorage` 或凭据存储。完整刷新页面会移除覆盖值。

<Warning>
  只能从客户端代码设置非机密值。不要在服务器变量中包含 API 密钥、令牌或其他凭据。
</Warning>

<div id="access-personalized-user-data">
  ### 访问个性化用户数据
</div>

如果你的站点启用了[认证](/zh/deploy/authentication-setup)或[个性化](/zh/create/personalization)，自定义脚本可以通过 `window.mintlify.user` 读取已识别的访客。它与 MDX 页面中暴露的 [`user` 变量](/zh/create/personalization#dynamic-mdx-content)是同一个对象，因此对应你用户数据中的 `content` 字段。

由于自定义脚本会在用户信息解析之前运行，请监听 `mintlify:user` 事件，以便在用户对象可用时做出响应。该事件会在用户信息解析时触发，之后每次发生变化也会再次触发。事件的 `detail` 是用户对象；当访客处于未登录或未识别状态时，则为 `null`。

```js Read the user after it resolves
window.addEventListener('mintlify:user', (event) => {
  const user = event.detail;
  if (!user) return; // Signed out or unidentified.

  renderAppLauncher(user);
});
```

如果你的脚本运行时用户已经解析完成，可直接读取 `window.mintlify.user`。

```js Read the current user
const user = window.mintlify?.user;
if (user) {
  renderAppLauncher(user);
}
```

在用户信息解析完成之前，以及访客处于未登录或未识别状态时，`window.mintlify.user` 都为 `undefined`。读取嵌套字段时请使用可选链操作符。

<Warning>
  你放入用户 `content` 字段的所有内容都会暴露给客户端脚本。不要在其中包含不应在浏览器中被读取的机密或凭据。
</Warning>