重写组件
Starlight 的默认 UI 和配置选项被设计成能灵活地适用于各种内容。大部分 Starlight 的默认外观可以通过 CSS 和 配置选项 进行自定义。
当你的需求超出了默认提供的功能时,Starlight 支持使用你自己的自定义组件来扩展或重写(完全替换)它的默认组件。
什么时候重写
重写 Starlight 的默认组件在以下情况下很有用:
- 你想要修改 Starlight 的一部分 UI 的样式,但是无法通过使用自定义 CSS 实现。
- 你想要修改 Starlight 的一部分 UI 的行为。
- 你想要在 Starlight 的现有 UI 旁边添加一些额外的 UI。
如何重写
-
选择你想要重写的 Starlight 组件。 你可以在重写参考中找到完整的组件列表。
本示例将重写 Starlight 页面导航栏中的
SocialIcons
组件。 -
创建一个 Astro 组件来替换 Starlight 组件。 本示例渲染了一个联系方式链接。
src/components/EmailLink.astro ---const email = 'houston@example.com';---<a href=`mailto:${email}`>E-mail Me</a> -
在
astro.config.mjs
的components
配置选项中告诉 Starlight 使用你的自定义组件:astro.config.mjs import { defineConfig } from 'astro/config';import starlight from '@astrojs/starlight';export default defineConfig({integrations: [starlight({title: 'My Docs with Overrides',components: {// 重写默认的 `SocialIcons` 组件。SocialIcons: './src/components/EmailLink.astro',},}),],});
复用内置组件
你可以像使用自己的组件一样使用 Starlight 的默认 UI 组件:导入并在你自己的自定义组件中渲染它们。这样你就可以在你的设计中保留 Starlight 的基本 UI,同时在它们旁边添加额外的 UI。
下面的示例是一个自定义组件,它渲染了一个电子邮件链接以及默认的 SocialIcons
组件:
---import Default from '@astrojs/starlight/components/SocialIcons.astro';---
<a href="mailto:houston@example.com">E-mail Me</a><Default><slot /></Default>
在自定义组件中渲染内置组件时,在默认组件中添加一个 <slot />
。这样可以确保如果组件传入了任何子元素,Astro 就知道在哪里渲染它们。
如果你要复用包含 命名插槽 的 PageFrame
或 TwoColumnContent
组件,你还需要 传递 这些插槽。
下面的示例展示了一个自定义组件,它复用了 TwoColumnContent
组件,该组件需要传递一个额外的 right-sidebar
命名插槽:
---import Default from '@astrojs/starlight/components/TwoColumnContent.astro';---
<Default> <slot /> <slot name="right-sidebar" slot="right-sidebar" /></Default>
使用页面数据
当重写 Starlight 组件时,你可以访问包含当前页面所有数据的全局 starlightRoute
对象。
这使得你可以使用这些值来控制你的组件模板的渲染方式。
在下面的示例中,一个 PageTitle
组件显示当前页面的标题,该标题在内容的前端元数据中设置:
---const { title } = Astro.locals.starlightRoute.entry.data;---
<h1 id="_top">{title}</h1>
<style> h1 { font-family: 'Comic Sans'; }</style>
了解更多关于所有可用属性的信息,请参阅 路由数据参考。
仅在特定页面上重写
组件重写在所有页面上生效。但是,你可以使用 starlightRoute
中的值来条件性渲染,决定何时显示你的自定义 UI,何时显示 Starlight 的默认 UI,甚至何时显示完全不同的内容。
在下面的示例中,一个重写 Footer
的组件只在首页上显示“Built with Starlight 🌟”,在其他页面上显示默认的页脚:
---import Default from '@astrojs/starlight/components/Footer.astro';
const isHomepage = Astro.locals.starlightRoute.id === '';---
{ isHomepage ? ( <footer>Built with Starlight 🌟</footer> ) : ( <Default> <slot /> </Default> )}
了解更多关于条件渲染的内容,请参阅 Astro 模板语法指南。