Mengganti Komponen

UI dan konfigurasi bawaan Starlight dirancang agar fleksibel dan dapat digunakan untuk berbagai macam jenis konten. Sebagian besar tampilan bawaan Starlight dapat disesuaikan dengan CSS dan opsi konfigurasi.

Ketika Anda membutuhkan lebih dari apa yang telah disediakan, Starlight mendukung pembuatan komponen custom Anda sendiri untuk memperluas atau mengganti (sepenuhnya) komponen bawaannya.

Kapan harus mengganti komponen

Mengganti komponen bawaan Starlight dapat berguna ketika:

• Anda ingin mengubah sebagian dari UI Starlight dengan cara yang tidak mungkin dilakukan dengan custom CSS.
• Anda ingin mengubah bagaimana sebagian UI Starlight bekerja.
• Anda ingin menambahkan UI tambahan disamping UI Starlight yang sudah ada.

Cara mengganti komponen

1. Pilih komponen Starlight yang ingin Anda ganti. Anda dapat menemukan daftar lengkap komponen di Referensi Penggantian.

   Contoh ini akan mengganti komponen SocialIcons Starlight pada bilah navigasi halaman.

2. Buat komponen Astro untuk menggantikan komponen Starlight tersebut. Contoh ini membuat tautan kontak.

   ---
   // src/components/EmailLink.astro
   import type { Props } from '@astrojs/starlight/props';
   ---
   
   <a href="mailto:houston@example.com">Kirim email ke Saya</a>

3. Beri tahu Starlight untuk menggunakan komponen custom Anda dalam opsi konfigurasi components di astro.config.mjs:

   // astro.config.mjs
   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';
   
   export default defineConfig({
     integrations: [
       starlight({
         title: 'Website Dokumentasi Saya dengan Penggantian Komponen',
         components: {
           // Mengganti komponen `SocialIcons` bawaan.
           SocialIcons: './src/components/EmailLink.astro',
         },
       }),
     ],
   });

Menggunakan ulang komponen bawaan

Anda dapat menggunakan komponen UI bawaan Starlight seperti yang Anda lakukan dengan komponen custom Anda sendiri: mengimpor dan merendernya dalam komponen custom Anda sendiri. Hal ini memungkinkan Anda mempertahankan semua elemen UI dasar Starlight dalam desain Anda, sambil menambahkan elemen UI tambahan bersama mereka.

Contoh di bawah ini menunjukkan sebuah komponen custom yang merender tautan e-mail bersama dengan komponen SocialIcons bawaan:

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

<a href="mailto:houston@example.com">Kirim email ke Saya</a>
<Default {...Astro.props}><slot /></Default>

Saat merender komponen bawaan dalam komponen custom:

• Spread Astro.props ke dalamnya. Hal ini memastikan bahwa komponen tersebut menerima semua data yang diperlukan untuk merendernya.
• Tambahkan <slot /> di dalam komponen bawaan tersebut. Hal ini memastikan bahwa jika komponen tersebut menerima child elements, Astro tahu di mana merendernya.

Menggunakan data halaman

Ketika mengganti komponen Starlight, implementasi custom Anda menerima objek standar Astro.props yang berisi semua data untuk halaman saat ini. Ini memungkinkan Anda menggunakan nilai-nilai ini untuk mengontrol bagaimana template komponen Anda merender.

Sebagai contoh, Anda dapat membaca nilai-nilai frontmatter halaman sebagai Astro.props.entry.data. Pada contoh berikut, komponen pengganti PageTitle menggunakannya untuk menampilkan judul halaman saat ini:

---
// src/components/Title.astro
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>

Pelajari lebih lanjut tentang semua prop yang tersedia di Referensi Penggantian.

Mengganti komponen hanya pada halaman tertentu

Penggantian komponen berlaku untuk semua halaman. Namun, Anda dapat merender secara kondisional menggunakan nilai dari Astro.props untuk menentukan kapan menampilkan UI custom Anda, kapan menampilkan UI bawaan Starlight, atau bahkan kapan menampilkan sesuatu yang benar-benar berbeda.

Pada contoh berikut, sebuah komponen yang menggantikan Footer Starlight menampilkan “Dibangun dengan Starlight 🌟” hanya di halaman beranda, dan menampilkan footer bawaan pada semua halaman lainnya:

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

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

{
  isHomepage ? (
    <footer>Dibangun dengan Starlight 🌟</footer>
  ) : (
    <Default {...Astro.props}>
      <slot />
    </Default>
  )
}

Pelajari lebih lanjut tentang merender secara kondisional di Panduan Template Syntax Astro.