Riferimento Sostituzioni
Puoi sovrascrivere i componenti integrati di Starlight fornendo percorsi ai componenti sostitutivi nell’opzione di configurazione components di Starlight.
Questa pagina elenca tutti i componenti disponibili per l’override e si collega alle loro implementazioni predefinite su GitHub.
Scopri di più nella Guida alla sostituzione dei componenti.
Proprietà dei componenti
Tutti i componenti possono accedere a un oggetto standard Astro.props che contiene informazioni sulla pagina corrente.
Per aggiungere i tipi di dato ai tuoi componenti personalizzati, importa il tipo Props da Starlight:
---
import type { Props } from '@astrojs/starlight/props';
const { hasSidebar } = Astro.props;
// ^ tipo: boolean
---Questo ti darà il completamento automatico e i tipi di dato quando accedi a Astro.props.
Proprietà
Starlight trasmetterà le seguenti proprietà ai tuoi componenti personalizzati.
dir
Tipo: 'ltr' | 'rtl'
Direzione di scrittura della pagina.
lang
Tipo: string
Tag di lingua BCP-47 per le impostazioni internazionali di questa pagina, ad es. en, zh-CN o pt-BR.
locale
Tipo: string | undefined
Il percorso di base in cui viene servita una lingua. undefined per gli slug della lingua di base.
slug
Tipo: string
Lo slug per questa pagina generato dal nome del file di contenuto.
id
Tipo: string
L’ID univoco per questa pagina in base al nome del file di contenuto.
isFallback
Tipo: true | undefined
true se questa pagina non è tradotta nella lingua corrente e utilizza contenuti di riserva dalle impostazioni di lingua predefinite.
Utilizzato solo in siti multilingue.
entryMeta
Tipo: { dir: 'ltr' | 'rtl'; lang: string }
Metadati di lingua per il contenuto della pagina. Può essere diverso dai valori di lingua di livello superiore quando una pagina utilizza contenuti di fallback.
entry
La voce della raccolta dei contenuti Astro per la pagina corrente.
Include i valori frontmatter per la pagina corrente in entry.data.
entry: {
data: {
title: string;
description: string | undefined;
// ecc.
}
}Scopri di più sulla forma di questo oggetto nel riferimento Tipo di voce della raccolta di Astro.
sidebar
Tipo: SidebarEntry[]
Voci della barra laterale di navigazione del sito per questa pagina.
hasSidebar
Tipo: boolean
Se la barra laterale deve essere visualizzata o meno in questa pagina.
pagination
Tipo: { prev?: Link; next?: Link }
Collegamenti alla pagina precedente e successiva nella barra laterale, se abilitata.
toc
Tipo: { minHeadingLevel: number; maxHeadingLevel: number; items: TocItem[] } | undefined
Sommario per questa pagina se abilitato.
headings
Tipo: { depth: number; slug: string; text: string }[]
Matrice di tutte le intestazioni Markdown estratte dalla pagina corrente.
Utilizza invece toc se vuoi creare un sommario che rispetti le opzioni di configurazione di Starlight.
lastUpdated
Tipo: Date | undefined
Oggetto JavaScript Date che rappresenta l’ultimo aggiornamento di questa pagina, se abilitato.
editUrl
Tipo: URL | undefined
Oggetto URL per l’indirizzo in cui questa pagina può essere modificata se abilitata.
Componenti
Head
Questi componenti vengono renderizzati all’interno dell’elemento <head> di ciascuna pagina.
Dovrebbero includere solo elementi consentiti all’interno di <head>.
Head
Componente standard: Head.astro
Componente renderizzato all’interno di <head> di ogni pagina.
Include tag importanti tra cui <title> e <meta charset="utf-8">.
Sostituisci questo componente come ultima risorsa.
Se possibile, preferisci l’opzione di configurazione head di Starlight.
ThemeProvider
Componente standard: ThemeProvider.astro
Componente renderizzato all’interno di <head> che imposta il supporto del tema scuro/chiaro.
L’implementazione predefinita include uno script in linea e un <template> utilizzato dallo script in <ThemeSelect />.
Accessibilità
SkipLink
Componente standard: SkipLink.astro
Componente renderizzato come primo elemento all’interno di <body> che si collega al contenuto della pagina principale per l’accessibilità.
L’implementazione predefinita è nascosta finché un utente non la focalizza premendo il tasto tab con la tastiera.
Layout
Questi componenti sono responsabili del layout dei componenti di Starlight e della gestione delle visualizzazioni attraverso diversi punti di interruzione. L’override di questi comporta una complessità significativa. Quando possibile, prediligi sovrascrivere un componente di livello inferiore.
PageFrame
Componente standard: PageFrame.astro
Componente di layout avvolto attorno alla maggior parte del contenuto della pagina.
L’implementazione predefinita imposta il layout header-sidebar-main e include slot denominati header e sidebar insieme a uno slot predefinito per il contenuto principale.
Renderizza inoltre <MobileMenuToggle /> per supportare l’attivazione/disattivazione della navigazione della barra laterale su piccole finestre (mobili).
MobileMenuToggle
Componente standard: MobileMenuToggle.astro
Componente reso all’interno di <PageFrame> responsabile dell’attivazione/disattivazione della navigazione della barra laterale su piccoli viewport (mobili).
TwoColumnContent
Componente standard: TwoColumnContent.astro
Componente di layout avvolto attorno alla colonna del contenuto principale e alla barra laterale destra (sommario). L’implementazione predefinita gestisce il passaggio da un layout a colonna singola con viewport piccolo a un layout a due colonne con viewport più grande.
Intestazione
Questi componenti eseguono il rendering della barra di navigazione superiore di Starlight.
Header
Componente standard: Header.astro
Componente dell’intestazione renderizzato nella parte superiore di ogni pagina.
L’implementazione predefinita renderizza <SiteTitle />, <Search />, <SocialIcons />, <ThemeSelect /> e <LanguageSelect />.
SiteTitle
Componente standard: SiteTitle.astro
Componente renderizzato all’inizio dell’intestazione del sito per visualizzare il titolo del sito. L’implementazione predefinita include la logica per il rendering dei loghi definita nella configurazione di Starlight.
Search
Componente standard: Search.astro
Componente utilizzato per eseguire il rendering dell’interfaccia utente di ricerca di Starlight. L’implementazione predefinita include il pulsante nell’intestazione e il codice per visualizzare una schermata di ricerca quando viene cliccata e caricare l’interfaccia utente di Pagefind.
SocialIcons
Componente standard: SocialIcons.astro
Componente renderizzato nell’intestazione del sito, inclusi i collegamenti alle icone social.
L’implementazione predefinita utilizza l’opzione social nella configurazione di Starlight per eseguire il rendering di icone e collegamenti.
ThemeSelect
Componente standard: ThemeSelect.astro
Componente renderizzato nell’intestazione del sito che consente agli utenti di selezionare la combinazione di colori preferita.
LanguageSelect
Componente standard: LanguageSelect.astro
Componente renderizzato nell’intestazione del sito che consente agli utenti di passare a una lingua diversa.
Barra Laterale Globale
La barra laterale globale di Starlight include la navigazione principale del sito. Nelle finestre strette questa è nascosta dietro un menu a discesa.
Sidebar
Componente standard: Sidebar.astro
Componente visualizzato prima del contenuto della pagina che contiene la navigazione globale.
L’implementazione predefinita viene visualizzata come barra laterale su viewport sufficientemente ampi e all’interno di un menu a discesa su viewport piccoli (mobili).
Visualizza inoltre <MobileMenuFooter /> per mostrare elementi aggiuntivi all’interno del menu mobile.
MobileMenuFooter
Componente standard: MobileMenuFooter.astro
Componente visualizzato nella parte inferiore del menu a discesa mobile.
L’implementazione predefinita visualizza <ThemeSelect /> e <LanguageSelect />.
Barra Laterale della Pagina
La barra laterale della pagina di Starlight è responsabile della visualizzazione di un sommario che delinea i sottotitoli della pagina corrente. Nelle finestre strette questo si comprime in un menu a discesa fisso.
PageSidebar
Componente standard: PageSidebar.astro
Componente renderizzato prima del contenuto della pagina principale per visualizzare un sommario.
L’implementazione predefinita rende <TableOfContents /> e <MobileTableOfContents />.
TableOfContents
Componente standard: TableOfContents.astro
Componente che renderizza il sommario della pagina corrente su finestre più ampie.
MobileTableOfContents
Componente standard: MobileTableOfContents.astro
Componente che renderizza il sommario della pagina corrente su piccoli viewport (mobili).
Contenuto
Questi componenti vengono visualizzati nella colonna principale del contenuto della pagina.
Banner
Componente standard: Banner.astro
Componente banner renderizzato nella parte superiore di ogni pagina.
L’implementazione predefinita utilizza il valore frontmatter banner della pagina per decidere se renderizzare o meno.
ContentPanel
Componente standard: ContentPanel.astro
Componente di layout utilizzato per racchiudere le sezioni della colonna del contenuto principale.
PageTitle
Componente standard: PageTitle.astro
Componente contenente l’elemento <h1> per la pagina corrente.
Le implementazioni dovrebbero garantire di impostare id="_top" sull’elemento <h1> come nell’implementazione predefinita.
FallbackContentNotice
Componente standard: FallbackContentNotice.astro
Avviso visualizzato agli utenti nelle pagine in cui non è disponibile una traduzione per la lingua corrente. Utilizzato solo su siti multilingue.
Hero
Componente standard: Hero.astro
Componente renderizzato nella parte superiore della pagina quando hero è impostato in frontmatter.
L’implementazione predefinita mostra un titolo di grandi dimensioni, uno slogan e collegamenti di invito all’azione insieme a un’immagine facoltativa.
MarkdownContent
Componente standard: MarkdownContent.astro
Componente renderizzato attorno al contenuto principale di ogni pagina. L’implementazione predefinita imposta gli stili di base da applicare al contenuto Markdown.
Piè di pagina
Questi componenti vengono visualizzati nella parte inferiore della colonna principale del contenuto della pagina.
Footer
Componente standard: Footer.astro
Componente piè di pagina renderizzato nella parte inferiore di ogni pagina.
L’implementazione predefinita visualizza <LastUpdated />, <Pagetion /> e <EditLink />.
LastUpdated
Componente standard: LastUpdated.astro
Componente renderizzato nel piè di pagina per visualizzare la data dell’ultimo aggiornamento.
EditLink
Componente standard: EditLink.astro
Componente renderizzato nel piè di pagina per visualizzare un collegamento al punto in cui è possibile modificare la pagina.
Pagination
Componente standard: Pagination.astro
Componente renderizzato nel piè di pagina per visualizzare le frecce di navigazione tra le pagine precedenti/successive.