Переопределение компонентов

Пользовательский интерфейс и параметры конфигурации Starlight по умолчанию разработаны таким образом, чтобы быть гибкими и работать с разнообразным контентом. Большую часть внешнего вида Starlight по умолчанию можно настроить с помощью CSS и параметров конфигурации.

Если вам нужно больше, чем возможно из коробки, Starlight поддерживает создание собственных пользовательских компонентов для расширения или переопределения (полной замены) компонентов по умолчанию.

Когда переопределять

Переопределение стандартных компонентов Starlight может быть полезно, когда:

Вы хотите изменить внешний вид интерфейса Starlight, если это невозможно сделать с использованием пользовательских CSS.
Вы хотите изменить поведение интерфейса Starlight.
Вы хотите добавить какой-то дополнительный интерфейс наряду с существующим интерфейсом Starlight.

Как выполнить переопределение

Выберите компонент Starlight, который вы хотите переопределить. Вы можете найти полный список компонентов в Справочнике по переопределениям.

Не уверены, какой компонент нужно переопределить? Используйте интерактивную карту переопределений Starlight, чтобы узнать названия UI-компонентов Starlight.

В этом примере будет переопределён компонент SocialIcons в навигационной панели страницы.
Создайте компонент Astro для замены компонента Starlight. В этом примере отображается ссылка для связи.
src/components/EmailLink.astro
```
---
import type { Props } from '@astrojs/starlight/props';
---

<a href="mailto:houston@example.com">
  Связаться с нами по электронной почте
</a>
```

Сообщите Starlight, что нужно использовать ваш компонент, указав его в параметре конфигурации components в astro.config.mjs:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Моя документация, с переопределением компонентов',
      components: {
        // Переопределение компонента `SocialIcons`.
        SocialIcons: './src/components/EmailLink.astro',
      },
    }),
  ],
});

Переиспользование встроенного компонента

Вы можете работать со стандартными UI-компонентами Starlight так же, как и со своими собственными: импортировать их и использовать в своих компонентах. Это позволяет вам сохранить весь интерфейс Starlight в рамках вашего дизайна, добавляя свой интерфейс рядом с ними.

Пример ниже показывает компонент, который отображает ссылку на электронную почту наряду со стандартным компонентом SocialIcons:

---
import type { Props } from '@astrojs/starlight/props';
import Default from '@astrojs/starlight/components/SocialIcons.astro';
---

<a href="mailto:houston@example.com"> Связаться с нами по электронной почте </a>
<Default {...Astro.props}><slot /></Default>

При использовании встроенного компонента внутри вашего компонента:

Передайте в него Astro.props. Это гарантирует, что он получит все данные, необходимые для отображения.
Добавьте <slot /> внутрь компонента по умолчанию. Это гарантирует, что если компоненту передаются какие-либо дочерние элементы, Astro знает, где их отображать.

Если вы повторно используете компоненты PageFrame или TwoColumnContent, содержащие именованные слоты, вам также необходимо перенести эти слоты.

Ниже показан пользовательский компонент, который повторно использует компонент TwoColumnContent, содержащий дополнительный именованный слот right-sidebar, нуждающийся в переносе:

---
import type { Props } from '@astrojs/starlight/props';
import Default from '@astrojs/starlight/components/TwoColumnContent.astro';
---

<Default {...Astro.props}>
  <slot />
  <slot name="right-sidebar" slot="right-sidebar" />
</Default>

Использование данных страницы

При переопределении компонента Starlight ваша реализация получает стандартный объект Astro.props, содержащий все данные для текущей страницы. Это позволяет вам использовать эти значения для управления тем, как ваш компонент будет отображаться.

Например, вы можете прочитать метаданные страницы как Astro.props.entry.data. В следующем примере компонент PageTitle использует этот объект для отображения текущего заголовка страницы:

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

const { title } = Astro.props.entry.data;
---

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

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

Узнайте больше обо всех доступных свойствах в Справочнике по переопределениям.

Переопределение только на определённых страницах

Переопределение компонентов применяется ко всем страницам. Тем не менее, вы можете осуществлять условную отрисовку, используя значения из Astro.props, чтобы определить, когда показывать ваш интерфейс, когда показывать интерфейс Starlight, или даже когда показывать что-то совершенно другое.

В следующем примере компонент, переопределяющий Footer от Starlight, отображает надпись «Создано с помощью Starlight 🌟» только на главной странице, а на всех остальных страницах показывает футер по умолчанию:

---
import type { Props } from '@astrojs/starlight/props';
import Default from '@astrojs/starlight/components/Footer.astro';

const isHomepage = Astro.props.slug === '';
---

{
  isHomepage ? (
    <footer>Создано с помощью Starlight 🌟</footer>
  ) : (
    <Default {...Astro.props}>
      <slot />
    </Default>
  )
}

Узнайте больше об условной отрисовке в руководстве Синтаксис Astro.