コンポーネントのオーバーライド
StarlightのデフォルトのUIと設定オプションは、柔軟に設計されており、さまざまなコンテンツで機能します。Starlightのデフォルトの見た目の大部分は、CSSと設定オプションによりカスタマイズできます。
デフォルトの内容に満足できない場合には、デフォルトのコンポーネントを拡張したり、オーバーライドしたり(完全に置き換えたり)するためのカスタムコンポーネントを作成することも可能です。
いつオーバーライドするか
以下の場合、Starlightのデフォルトコンポーネントをオーバーライドすると便利です。
- カスタムCSSでは不可能な方法で、StarlightのUIの見た目を部分的に変更したい場合。
- StarlightのUIの動作を部分的に変更したい場合。
- Starlightの既存のUIに別のUIを追加したい場合。
オーバーライドの方法
-
オーバーライドしたいStarlightコンポーネントを選択します。コンポーネントの完全なリストは、オーバーライドリファレンスにあります。
この例では、ページのナビゲーションバーに表示される、Starlightの
SocialIcons
コンポーネントをオーバーライドします。 -
Starlightのコンポーネントを置き換えるAstroコンポーネントを作成します。この例では、連絡先のリンクをレンダリングします。
-
astro.config.mjs
のcomponents
設定オプションで、カスタムコンポーネントを使用するようStarlightに指示します。
組み込みコンポーネントを再利用する
StarlightのデフォルトのUIコンポーネントを、自分で作ったものと同じように使うことができます。これにより、Starlightの基本的なUIをデザインとしてすべて保持しながら、そこに別のUIを追加することができます。
以下の例は、デフォルトのSocialIcons
コンポーネントと一緒に、メールリンクをレンダリングするカスタムコンポーネントです。
組み込みコンポーネントをカスタムコンポーネント内でレンダリングする場合、
Astro.props
を展開します。これにより、レンダリングに必要なすべてのデータを受け取ることができます。- デフォルトのコンポーネント内に
<slot />
を追加します。これにより、コンポーネントに子要素が渡された場合、Astroがそれらをどこにレンダリングするかを知ることができます。
ページデータを使用する
Starlightコンポーネントをオーバーライドすると、カスタム実装側には、現在のページのすべてのデータを含む、標準のAstro.props
オブジェクトが渡されます。これらの値を使用して、コンポーネントテンプレートのレンダリング方法を制御することができます。
たとえば、ページのフロントマターの値をAstro.props.entry.data
として取得できます。以下の例では、PageTitle
を置き換えるコンポーネントが、現在のページのタイトルを表示するためにこれを使用しています。
利用可能なすべてのpropsについて、詳しくはオーバーライドリファレンスを参照してください。
特定ページのみでのオーバーライド
コンポーネントのオーバーライドはすべてのページに適用されます。ただし、Astro.props
の値を使用して条件に応じてレンダリングすることで、カスタムUIを表示するタイミング、StarlightのデフォルトUIを表示するタイミング、あるいはまったく別のものを表示するタイミングを決定することができます。
以下は、StarlightのFooter
をオーバーライドするコンポーネントの例です。ホームページでのみ「Starlightで作成 🌟」と表示し、それ以外のすべてのページではデフォルトのフッターを表示します。
条件付きレンダリングについて、詳しくはAstroのテンプレート構文ガイドを参照してください。