重写参考

你可以通过在 Starlight 的 components 配置选项中提供替代组件的路径来替换掉 (即重写) Starlight 的内置组件。本页面列出了所有可被重写的组件和它们默认实现的 GitHub 链接。

组件参数

所有组件都可以使用标准的 Astro.props 对象，该对象包含有关当前页面的信息。

从 Starlight 导入 Props 类型来为你的自定义组件定义类型：

---
import type { Props } from '@astrojs/starlight/props';

const { hasSidebar } = Astro.props;
//      ^ type: boolean
---

这样当使用 Astro.props 时就会有自动补全和类型提示。

参数

Starlight 会将以下参数传递给你的自定义组件。

`dir`

类型： 'ltr' | 'rtl'

当前页面的文本方向。

`lang`

类型： string

当前页面的 BCP-47 语言标签，例如 en、zh-CN 或 pt-BR。

`locale`

类型： string | undefined

当前语言的根路径。对于默认语言来说是 undefined。

`siteTitle`

类型： string

根据页面语言设置的网站标题。

`siteTitleHref`

类型： string

网站标题的 href 属性值，链接回首页，例如 /。对于多语言站点，将包含当前的语言环境，例如 /en/ 或 /zh-cn/。

`slug`

类型： string

从内容文件名生成的页面 slug。

`id`

类型： string

基于内容文件名的页面的唯一 ID。

`isFallback`

类型： true | undefined

如果此页面在当前语言中未翻译，回退到使用默认语言的内容，则为 true。仅在多语言站点中使用。

`entryMeta`

类型： { dir: 'ltr' | 'rtl'; lang: string }

页面内容的语言环境元数据 (locale metadata)。当页面使用回退内容时可以与顶级语言环境设置值不同。

`entry`

当前页面所对应的 Astro 内容集合条目。在 entry.data 中包含当前页面的 frontmatter 内容。

entry: {
  data: {
    title: string;
    description: string | undefined;
    // 等
  }
}

在 Astro 的集合条目类型参考中了解更多关于此对象的信息。

`sidebar`

类型： SidebarEntry[]

当前页面的侧边栏条目。

`hasSidebar`

类型： boolean

当前页面是否应该显示侧边栏。

`pagination`

类型： { prev?: Link; next?: Link }

如果启用了，当前页面在侧边栏中的上一页和下一页的链接。

`toc`

类型： { minHeadingLevel: number; maxHeadingLevel: number; items: TocItem[] } | undefined

如果启用了，当前页面的目录 (table of contents)。

`headings`

类型： { depth: number; slug: string; text: string }[]

从当前页面提取的所有 Markdown 标题的数组。如果你想要构建一个遵循 Starlight 配置选项的目录组件，请使用 toc。

`lastUpdated`

类型： Date | undefined

如果启用了，表示此页面最后更新时间的 JavaScript Date 对象。

`editUrl`

类型： URL | undefined

如果启用了，表示可以编辑此页面的地址的 JavaScript URL 对象。

`labels`

类型： Record<string, string>

一个包含为当前页面本地化的 UI 字符串的对象。请参阅 “翻译 Starlight UI” 指南以获取所有可用键的列表。

组件

头部

这些组件在每个页面的 <head> 元素内渲染。它们应只包含允许在 <head> 中使用的元素。

`Head`

默认组件： Head.astro

在每个页面的 <head> 元素内渲染的组件。包含 <title> 和 <meta charset="utf-8"> 等重要标签。

重写此组件应作为最后手段。如果可能，请优先使用 Starlight 配置中的 head 选项。

`ThemeProvider`

默认组件： ThemeProvider.astro

在 <head> 内渲染的用于提供暗色/亮色主题支持的组件。默认实现包括一个内联脚本和一个 <template>，该脚本在 <ThemeSelect /> 中使用该模板。

无障碍

`SkipLink`

默认组件： SkipLink.astro

在 <body> 内渲染的第一个元素，它链接到主页面内容以实现无障碍访问。默认实现默认为隐藏状态，只有在用户使用键盘通过 tab 键聚焦到它时才会显示。

布局

这些组件负责在不同的断点 (breakpoints) 上布局 Starlight 的组件、管理视图。重写这些组件会有很大的复杂性。如果可能，请优先重写较低级别的组件。

`PageFrame`

默认组件： PageFrame.astro

包在绝大部分页面内容外的布局组件。默认实现提供了头部—侧边栏—主内容的布局，并包含 header 和 sidebar 命名插槽以及主内容的默认插槽。它还渲染了 <MobileMenuToggle /> 以支持在小 (移动) 视口 (viewports) 上切换侧边栏导航。

`MobileMenuToggle`

默认组件： MobileMenuToggle.astro

在 <PageFrame> 内渲染的负责在小 (移动) 视口上切换侧边栏导航的组件。

`TwoColumnContent`

默认组件： TwoColumnContent.astro

包在主内容列和右侧栏 (目录) 外的布局组件。默认实现实现了在单列、小视口布局和两列、较大视口布局之间的切换。

全局侧边栏

Starlight 的全局侧边栏包含了主站点导航。在较窄的视口上，它会隐藏在下拉菜单中。

`Sidebar`

默认组件： Sidebar.astro

在页面内容之前渲染的包含全局导航的组件。默认实现在足够宽的视口上显示为侧边栏，在小 (移动) 视口上显示为下拉菜单。它还渲染了 <MobileMenuFooter /> 以在移动菜单中显示额外的项目。

`MobileMenuFooter`

默认组件： MobileMenuFooter.astro

在移动下拉菜单最底部中渲染的组件。默认实现渲染了 <ThemeSelect /> 和 <LanguageSelect />。

页面侧边栏

Starlight 的页面侧边栏负责显示当前页面的子标题的目录。在较窄的视口上，它会缩为一个固定的下拉菜单。

`PageSidebar`

默认组件： PageSidebar.astro

在页面内容之前渲染的包含目录的组件。默认实现渲染了 <TableOfContents /> 和 <MobileTableOfContents />。

`TableOfContents`

默认组件： TableOfContents.astro

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

`MobileTableOfContents`

默认组件： MobileTableOfContents.astro

在小 (移动) 视口上渲染当前页面的目录的组件。

内容

这些组件在页面主内容列中渲染。

`Banner`

默认组件： Banner.astro

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

`ContentPanel`

默认组件： ContentPanel.astro

包在页面主内容列中的段落外的布局组件。

`PageTitle`

默认组件： PageTitle.astro

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

自定义实现应确保在 <h1> 元素上设置 id="_top"，就像默认实现中一样。

`DraftContentNotice`

默认组件： DraftContentNotice.astro

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

`FallbackContentNotice`

默认组件： FallbackContentNotice.astro

在本页面当前语言没有翻译时显示给用户的通知。仅在多语言站点中使用。

`Hero`

默认组件： Hero.astro

当设置了 frontmatter 中的 hero 时在页面顶部渲染的组件。默认实现显示了一个大标题、标语、动作链接 (call-to-action links) 和可选的图片。

`MarkdownContent`

默认组件： MarkdownContent.astro

在页面主内容列中渲染 Markdown 内容的组件。默认实现为 Markdown 内容提供了基本的样式。

Markdown 内容样式也暴露在 @astrojs/starlight/style/markdown.css 中，并且作用域限制在 .sl-markdown-content CSS 类中。

页脚

这些组件在页面主内容列的底部渲染。

`Footer`

默认组件： Footer.astro

页脚 (Footer) 组件在每个页面的底部渲染。默认实现显示了 <LastUpdated />、<Pagination /> 和 <EditLink />。

`LastUpdated`

默认组件： LastUpdated.astro

在页脚中渲染的组件，用于显示最后更新日期。

`EditLink`

默认组件： EditLink.astro

在页脚中渲染的组件，用于显示指向页面编辑地址的链接。

`Pagination`

默认组件： Pagination.astro

在页脚中渲染的组件，用于显示上一页和下一页的导航箭头。

重写参考

组件参数

参数

dir

lang

locale

siteTitle

siteTitleHref

slug

id

isFallback

entryMeta

entry

sidebar

hasSidebar

pagination

toc

headings

lastUpdated

editUrl

labels

组件

头部

Head

ThemeProvider

无障碍

SkipLink

布局

PageFrame

MobileMenuToggle

TwoColumnContent

导航

Header

SiteTitle

Search

SocialIcons

ThemeSelect

LanguageSelect

全局侧边栏

Sidebar

MobileMenuFooter

页面侧边栏

PageSidebar

TableOfContents

MobileTableOfContents

内容

Banner

ContentPanel

PageTitle

DraftContentNotice

FallbackContentNotice

Hero

MarkdownContent

页脚

Footer

LastUpdated

EditLink

Pagination

`dir`

`lang`

`locale`

`siteTitle`

`siteTitleHref`

`slug`

`id`

`isFallback`

`entryMeta`

`entry`

`sidebar`

`hasSidebar`

`pagination`

`toc`

`headings`

`lastUpdated`

`editUrl`

`labels`

`Head`

`ThemeProvider`

`SkipLink`

`PageFrame`

`MobileMenuToggle`

`TwoColumnContent`

`Header`

`SiteTitle`

`Search`

`SocialIcons`

`ThemeSelect`

`LanguageSelect`

`Sidebar`

`MobileMenuFooter`

`PageSidebar`

`TableOfContents`

`MobileTableOfContents`

`Banner`

`ContentPanel`

`PageTitle`

`DraftContentNotice`

`FallbackContentNotice`

`Hero`

`MarkdownContent`

`Footer`

`LastUpdated`

`EditLink`

`Pagination`