mintlify__docs/zh/customize/custom-scripts.mdx

---
title: "自定义脚本"
description: "为你的文档站点添加自定义 JavaScript 和 CSS 脚本，用于分析、小组件、样式覆盖和第三方集成。"
keywords: ["CSS", "JavaScript", "Tailwind CSS", "样式定制"]
---

使用 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-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="access-authenticated-user-data">
  ### 访问已登录用户的数据
</div>

如果你的站点启用了[身份验证](/zh/deploy/authentication-setup)，自定义脚本可以通过 `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.

  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>