重写组件

Starlight 的默认 UI 和配置选项被设计成能灵活地适用于各种内容。大部分 Starlight 的默认外观可以通过 CSS 和 配置选项 进行自定义。

当你的需求超出了默认提供的功能时，Starlight 支持使用你自己的自定义组件来扩展或重写（完全替换）它的默认组件。

什么时候重写

重写 Starlight 的默认组件在以下情况下很有用：

• 你想要修改 Starlight 的一部分 UI 的样式，但是无法通过使用自定义 CSS 实现。
• 你想要修改 Starlight 的一部分 UI 的行为。
• 你想要在 Starlight 的现有 UI 旁边添加一些额外的 UI。

如何重写

1. 选择你想要重写的 Starlight 组件。 你可以在重写参考中找到完整的组件列表。

   提示

   不确定你需要重写哪个组件？使用 交互式 Starlight 重写地图 来发现 Starlight UI 组件的名称。

   本示例将重写 Starlight 页面导航栏中的 SocialIcons 组件。

2. 创建一个 Astro 组件来替换 Starlight 组件。 本示例渲染了一个联系方式链接。

   src/components/EmailLink.astro

   ---
   const email = 'houston@example.com';
   ---
   
   <a href=`mailto:${email}`>E-mail Me</a>

3. 在 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 组件：

src/components/EmailLink.astro

---
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 命名插槽：

src/components/CustomContent.astro

---
import Default from '@astrojs/starlight/components/TwoColumnContent.astro';
---

<Default>
  <slot />
  <slot name="right-sidebar" slot="right-sidebar" />
</Default>

使用页面数据

当重写 Starlight 组件时，你可以访问包含当前页面所有数据的全局 starlightRoute 对象。 这使得你可以使用这些值来控制你的组件模板的渲染方式。

在下面的示例中，一个 PageTitle 组件显示当前页面的标题，该标题在内容的前端元数据中设置：

src/components/Title.astro

---
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 🌟”，在其他页面上显示默认的页脚：

src/components/ConditionalFooter.astro

---
import Default from '@astrojs/starlight/components/Footer.astro';

const isHomepage = Astro.locals.starlightRoute.id === '';
---

{
  isHomepage ? (
    <footer>Built with Starlight 🌟</footer>
  ) : (
    <Default>
      <slot />
    </Default>
  )
}

了解更多关于条件渲染的内容，请参阅 Astro 模板语法指南。