覆盖参考

你可以通过在 Starlight 的 components 配置项中提供替换组件的路径，来覆盖 Starlight 的内置组件。本页列出了所有可覆盖的组件，并链接到它们在 GitHub 上的默认实现。

在覆盖组件指南中了解更多信息。

组件

头部 (Head)

这些组件呈现在每个页面的 <head> 元素内。它们应该只包含在 <head> 内允许的元素。

`头部 (Head)`

默认组件： Head.astro

在每个页面的 <head> 内呈现的组件。

仅在万不得已时才覆盖此组件。如果可能，请优先使用 head 配置选项、head frontmatter 字段或路由数据中间件来自定义由默认组件呈现的路由数据。

`主题提供器`

默认组件： ThemeProvider.astro

在 <head> 内呈现的组件，用于设置深色/浅色主题支持。默认实现包含一个内联脚本和一个被 <ThemeSelect /> 中脚本使用的 <template>。

无障碍性

`跳转链接`

默认组件： SkipLink.astro

作为 <body> 内的第一个元素呈现的组件，它链接到主页面内容以提高无障碍性。默认实现是隐藏的，直到用户通过键盘 Tab 键聚焦到它。

布局

这些组件负责 Starlight 组件的布局，并管理不同断点下的视图。覆盖它们会带来显著的复杂性。如果可能，请优先覆盖更低级别的组件。

`页面框架`

默认组件： PageFrame.astro
具名插槽： header, sidebar

包裹大部分页面内容的布局组件。默认实现设置了“页眉-侧边栏-主内容”布局，并包含 header 和 sidebar 具名插槽，以及一个用于主内容的默认插槽。它还呈现 <MobileMenuToggle /> 以支持在小（移动端）视口上切换侧边栏导航。

`移动端菜单切换`

默认组件： MobileMenuToggle.astro

在 <PageFrame> 内呈现的组件，负责在小（移动端）视口上切换侧边栏导航。

`双列内容`

默认组件： TwoColumnContent.astro
具名插槽： right-sidebar

包裹主内容列和右侧边栏（目录）的布局组件。默认实现处理在单列、小视口布局和双列、大视口布局之间的切换。

这些组件呈现 Starlight 的顶部导航栏。

`页眉`

默认组件： Header.astro

在每个页面顶部显示的页眉组件。默认实现会显示 <SiteTitle />、<Search />、<SocialIcons />、<ThemeSelect /> 和 <LanguageSelect />。

`网站标题`

默认组件： SiteTitle.astro

在网站页眉开始处呈现的组件，用于显示网站标题。默认实现包含用于呈现在 Starlight 配置中定义的徽标的逻辑。

`搜索`

默认组件： Search.astro

用于呈现 Starlight 搜索界面的组件。默认实现包括页眉中的按钮以及在点击时显示搜索模态框和加载 Pagefind 的 UI 的代码。

当 pagefind 被禁用时，默认的搜索组件将不会被呈现。但是，如果你覆盖了 Search，你的自定义组件将始终被呈现，即使 pagefind 配置选项为 false。这允许你在禁用 Pagefind 时为其他搜索提供商添加 UI。

`社交图标`

默认组件： SocialIcons.astro

在网站页眉中呈现的组件，包含社交图标链接。默认实现使用 Starlight 配置中的 social 选项来呈现图标和链接。

`主题选择`

默认组件： ThemeSelect.astro

在网站页眉中呈现的组件，允许用户选择他们偏好的配色方案。

`语言选择`

默认组件： LanguageSelect.astro

在网站页眉中呈现的组件，允许用户切换到不同的语言。

Starlight 的全局侧边栏包含主网站导航。在窄视口上，它被隐藏在下拉菜单后面。

`侧边栏`

默认组件： Sidebar.astro

在页面内容之前呈现的组件，包含全局导航。默认实现在足够宽的视口上显示为侧边栏，在小（移动端）视口上显示在下拉菜单内。它还呈现 <MobileMenuFooter /> 以在移动菜单中显示附加项目。

`移动端菜单页脚`

默认组件： MobileMenuFooter.astro

在移动下拉菜单底部呈现的组件。默认实现呈现 <ThemeSelect /> 和 <LanguageSelect />。

Starlight 的页面侧边栏负责显示一个目录，概述当前页面的子标题。在窄视口上，它会折叠成一个粘性的下拉菜单。

`页面侧边栏`

默认组件： PageSidebar.astro

在主页面内容之前呈现的组件，用于显示目录。默认实现呈现 <TableOfContents /> 和 <MobileTableOfContents />。

`目录`

默认组件： TableOfContents.astro

在较宽视口上呈现当前页面目录的组件。

`移动端目录`

默认组件： MobileTableOfContents.astro

在小（移动端）视口上呈现当前页面目录的组件。

内容

这些组件呈现在页面内容的主列中。

`横幅`

默认组件： Banner.astro

在每个页面顶部呈现的横幅组件。默认实现使用页面的 banner frontmatter 值来决定是否呈现。

`内容面板`

默认组件： ContentPanel.astro

用于包裹主内容列中各个部分的布局组件。

`页面标题`

默认组件： PageTitle.astro

包含当前页面 <h1> 元素的组件。

实现时应确保在 <h1> 元素上设置 id="_top"，与默认实现一致。

`草稿内容通知`

默认组件： DraftContentNotice.astro

当当前页面被标记为草稿时，在开发过程中向用户显示的通知。

`回退内容通知`

默认组件： FallbackContentNotice.astro

在当前语言的翻译不可用时向用户显示的通知。仅在多语言网站上使用。

`Hero 组件`

默认组件： Hero.astro

当在 frontmatter 中设置了 hero 时，在页面顶部呈现的组件。默认实现会显示一个大标题、标语和号召性用语链接，以及一个可选的图片。

`Markdown 内容`

默认组件： MarkdownContent.astro

围绕每个页面的主内容呈现的组件。默认实现设置了应用于 Markdown 内容的基本样式。

Markdown 内容样式也通过 @astrojs/starlight/style/markdown.css 暴露，并作用于 .sl-markdown-content CSS 类。

这些组件呈现在页面内容主列的底部。

`页脚`

默认组件： Footer.astro

在每个页面底部显示的页脚组件。默认实现会显示 <LastUpdated />、<Pagination /> 和 <EditLink />。

`最后更新时间`

默认组件： LastUpdated.astro

在页面页脚中呈现的组件，用于显示最后更新日期。

`编辑链接`

默认组件： EditLink.astro

在页面页脚中呈现的组件，用于显示一个链接，指向可以编辑该页面的地方。

`分页`

默认组件： Pagination.astro

在页面页脚中呈现的组件，用于显示上一页/下一页之间的导航箭头。