覆盖组件

Starlight 的默认用户界面（UI）和配置选项在设计上十分灵活，能够适用于各种内容。Starlight 的大部分默认外观可以通过 CSS 和配置选项进行自定义。

当你需要的功能超出了开箱即用的范围时，Starlight 支持构建你自己的自定义组件来扩展或覆盖（完全替换）其默认组件。

何时覆盖

在以下情况下，覆盖 Starlight 的默认组件会很有用：

你想改变 Starlight UI 某一部分的外观，而这种改变无法通过自定义 CSS 实现。
你想改变 Starlight UI 某一部分的行为。
你想在 Starlight 现有 UI 的基础上添加一些额外的 UI。

如何覆盖

选择你想要覆盖的 Starlight 组件。你可以在覆盖参考中找到完整的组件列表。

不确定需要覆盖哪个组件？使用交互式 Starlight 覆盖地图来查找 Starlight UI 组件的名称。

本示例将覆盖页面导航栏中的 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 使用你的自定义组件。

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs with Overrides',
      components: {
        // Override the default `SocialIcons` component.
        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 组件会显示在内容的 frontmatter 中设置的当前页面标题：

---
const { title } = Astro.locals.starlightRoute.entry.data;
---

<h1 id="_top">{title}</h1>

<style>
  h1 {
    font-family: 'Comic Sans';
  }
</style>

在路由数据参考中了解所有可用属性的更多信息。

仅在特定页面上覆盖

组件覆盖会应用于所有页面。但是，你可以使用 starlightRoute 中的值进行条件渲染，以决定何时显示你的自定义 UI、何时显示 Starlight 的默认 UI，或者甚至显示完全不同的内容。

在下面的示例中，一个覆盖 Starlight Footer 的组件仅在主页上显示“由 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 的模板语法指南中了解有关条件渲染的更多信息。