mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
273 lines
8.8 KiB
Plaintext
273 lines
8.8 KiB
Plaintext
---
|
||
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>
|
||
|
||
将 CSS 文件添加到你的存储库中，这些文件中定义的类名会在你所有的 MDX 文件中生效并可用。
|
||
|
||
<div id="adding-stylecss">
|
||
### 添加 `style.css`
|
||
</div>
|
||
|
||
例如，你可以添加以下 `style.css` 文件以自定义导航栏和页脚的样式。
|
||
|
||
```css
|
||
#navbar {
|
||
background: #fffff2;
|
||
padding: 1rem;
|
||
}
|
||
|
||
footer {
|
||
margin-top: 2rem;
|
||
}
|
||
```
|
||
|
||
|
||
<div id="using-identifiers-and-selectors">
|
||
### 使用标识符和选择器
|
||
</div>
|
||
|
||
Mintlify 提供了一组常用的标识符和选择器，帮助你为 UI 中的重要元素添加标签。
|
||
|
||
<Tip>
|
||
使用“检查元素”来定位你要自定义的元素引用。
|
||
</Tip>
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="标识符">
|
||
* APIPlaygroundInput: `api-playground-input`
|
||
* AssistantEntry: `assistant-entry`
|
||
* AssistantEntryMobile: `assistant-entry-mobile`
|
||
* Banner: `banner`
|
||
* BodyContent: `body-content`
|
||
* ChangelogFilters: `changelog-filters`
|
||
* ChangelogFiltersContent: `changelog-filters-content`
|
||
* ChatAssistantSheet: `chat-assistant-sheet`
|
||
* ChatAssistantTextArea: `chat-assistant-textarea`
|
||
* ContentArea: `content-area`
|
||
* ContentContainer: `content-container`
|
||
* ContentSideLayout: `content-side-layout`
|
||
* FeedbackForm: `feedback-form`
|
||
* FeedbackFormCancel: `feedback-form-cancel`
|
||
* FeedbackFormInput: `feedback-form-input`
|
||
* FeedbackFormSubmit: `feedback-form-submit`
|
||
* FeedbackThumbsDown: `feedback-thumbs-down`
|
||
* FeedbackThumbsUp: `feedback-thumbs-up`
|
||
* Footer: `footer`
|
||
* Header: `header`
|
||
* NavBarTransition: `navbar-transition`
|
||
* NavigationItems: `navigation-items`
|
||
* Navbar: `navbar`
|
||
* PageContextMenu: `page-context-menu`
|
||
* PageContextMenuButton: `page-context-menu-button`
|
||
* PageTitle: `page-title`
|
||
* Pagination: `pagination`
|
||
* Panel: `panel`
|
||
* RequestExample: `request-example`
|
||
* ResponseExample: `response-example`
|
||
* SearchBarEntry: `search-bar-entry`
|
||
* SearchBarEntryMobile: `search-bar-entry-mobile`
|
||
* SearchInput: `search-input`
|
||
* Sidebar: `sidebar`
|
||
* SidebarContent: `sidebar-content`
|
||
* TableOfContents: `table-of-contents`
|
||
* TableOfContentsContent: `table-of-contents-content`
|
||
* TableOfContentsLayout: `table-of-contents-layout`
|
||
* TopbarCtaButton: `topbar-cta-button`
|
||
</Accordion>
|
||
|
||
<Accordion title="选择器">
|
||
* Accordion: `accordion`
|
||
* AccordionGroup: `accordion-group`
|
||
* AlmondLayout: `almond-layout`
|
||
* AlmondNavBottomSection: `almond-nav-bottom-section`
|
||
* AlmondNavBottomSectionDivider: `almond-nav-bottom-section-divider`
|
||
* Anchor: `nav-anchor`
|
||
* Anchors: `nav-anchors`
|
||
* APISection: `api-section`
|
||
* APISectionHeading: `api-section-heading`
|
||
* APISectionHeadingSubtitle: `api-section-heading-subtitle`
|
||
* APISectionHeadingTitle: `api-section-heading-title`
|
||
* Callout: `callout`
|
||
* Card: `card`
|
||
* CardGroup: `card-group`
|
||
* ChatAssistantSheet: `chat-assistant-sheet`
|
||
* ChatAssistantSheetHeader: `chat-assistant-sheet-header`
|
||
* ChatAssistantSheetContent: `chat-assistant-sheet-content`
|
||
* ChatAssistantInput: `chat-assistant-input`
|
||
* ChatAssistantSendButton: `chat-assistant-send-button`
|
||
* CodeBlock: `code-block`
|
||
* CodeGroup: `code-group`
|
||
* Content: `mdx-content`
|
||
* DropdownTrigger: `nav-dropdown-trigger`
|
||
* DropdownContent: `nav-dropdown-content`
|
||
* DropdownItem: `nav-dropdown-item`
|
||
* DropdownItemTextContainer: `nav-dropdown-item-text-container`
|
||
* DropdownItemTitle: `nav-dropdown-item-title`
|
||
* DropdownItemDescription: `nav-dropdown-item-description`
|
||
* DropdownItemIcon: `nav-dropdown-item-icon`
|
||
* Expandable: `expandable`
|
||
* Eyebrow: `eyebrow`
|
||
* FeedbackToolbar: `feedback-toolbar`
|
||
* Field: `field`
|
||
* Frame: `frame`
|
||
* Icon: `icon`
|
||
* Link: `link`
|
||
* LoginLink: `login-link`
|
||
* Logo: `nav-logo`
|
||
* Mermaid: `mermaid`
|
||
* MethodNavPill: `method-nav-pill`
|
||
* MethodPill: `method-pill`
|
||
* NavBarLink: `navbar-link`
|
||
* NavTagPill: `nav-tag-pill`
|
||
* NavTagPillText: `nav-tag-pill-text`
|
||
* OptionDropdown: `option-dropdown`
|
||
* PaginationNext: `pagination-next`
|
||
* PaginationPrev: `pagination-prev`
|
||
* PaginationTitle: `pagination-title`
|
||
* Panel: `panel`
|
||
* SidebarGroup: `sidebar-group`
|
||
* SidebarGroupIcon: `sidebar-group-icon`
|
||
* SidebarGroupHeader: `sidebar-group-header`
|
||
* SidebarNavGroupDivider: `sidebar-nav-group-divider`
|
||
* SidebarTitle: `sidebar-title`
|
||
* Step: `step`
|
||
* Steps: `steps`
|
||
* Tab: `tab`
|
||
* Tabs: `tabs`
|
||
* TabsBar: `nav-tabs`
|
||
* TabsBarItem: `nav-tabs-item`
|
||
* TableOfContents: `toc`
|
||
* TableOfContentsItem: `toc-item`
|
||
* Tooltip: `tooltip`
|
||
* TopbarRightContainer: `topbar-right-container`
|
||
* TryitButton: `tryit-button`
|
||
* Update: `update`
|
||
|
||
**数据属性**
|
||
|
||
部分元素暴露了可用作 CSS 选择器的数据属性。
|
||
|
||
激活状态 (`data-active`)：
|
||
|
||
- DropdownItem: `nav-dropdown-item[data-active]`
|
||
- MobileNavTabsBarItem: `mobile-nav-tabs-item[data-active]`
|
||
- SidebarGroup: `sidebar-group[data-active]`
|
||
- SidebarNavItem: `#sidebar-content li[data-active]`
|
||
- TableOfContentsItem: `toc-item[data-active]`
|
||
- TableOfContentsItem（最深层）: `toc-item[data-active-deepest]` — 仅出现在当前可见的确切标题上，与 `data-active` 不同，后者也会设置在其父级标题上
|
||
|
||
Badge 属性：
|
||
|
||
- Badge: `[data-badge]`
|
||
- 按颜色选择 Badge: `[data-badge][data-color="blue"]`
|
||
- 按尺寸选择 Badge: `[data-badge][data-size="sm"]`
|
||
|
||
</Accordion>
|
||
</AccordionGroup>
|
||
|
||
<Warning>
|
||
随着平台演进，引用和常用元素的样式可能会发生变化。请谨慎使用自定义样式。
|
||
</Warning>
|
||
|
||
<div id="custom-javascript">
|
||
## 自定义 JavaScript
|
||
</div>
|
||
|
||
自定义 JS 允许你在全局添加自定义可执行代码，相当于在每个页面都插入一个包含 JS 代码的 `<script>` 标签。
|
||
|
||
<div id="adding-custom-javascript">
|
||
### 添加自定义 JavaScript
|
||
</div>
|
||
|
||
Mintlify 会将文档站点的 content 目录中的任何 `.js` 文件注入到每个文档页面。比如，你可以添加下面的 `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="external-scripts">
|
||
## 外部脚本
|
||
</div>
|
||
|
||
通过 `docs.json` 中的 `integrations.customScripts` 配置，在文档的每个页面上从 URL 加载外部脚本。这对于添加托管在 CDN 上的第三方分析或追踪脚本非常有用。
|
||
|
||
<Note>
|
||
外部脚本需要为你的项目启用 custom scripts 权限。如需访问权限，请联系支持团队。
|
||
</Note>
|
||
|
||
<div id="configuration">
|
||
### 配置
|
||
</div>
|
||
|
||
在 `docs.json` 的 `integrations` 中添加 `customScripts` 数组：
|
||
|
||
```json docs.json
|
||
{
|
||
"integrations": {
|
||
"customScripts": [
|
||
{
|
||
"src": "https://cdn.example.com/analytics.js",
|
||
"strategy": "afterInteractive"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
每个脚本对象接受以下属性：
|
||
|
||
<ResponseField name="src" type="string" required>
|
||
要加载的脚本的 HTTPS URL。必须指向有效的 JavaScript 文件。
|
||
</ResponseField>
|
||
|
||
<ResponseField name="strategy" type="string" default="afterInteractive">
|
||
控制脚本的加载时机。接受 `afterInteractive`（页面可交互后加载）或 `lazyOnload`（空闲时加载）。
|
||
</ResponseField>
|
||
|
||
最多可以添加 20 个外部脚本。
|
||
|
||
<Warning>
|
||
只加载来自可信来源的脚本。外部脚本可以完全访问页面，可能影响性能和安全性。
|
||
</Warning>
|