Komponenty
Komponenty Astro stanowią podstawę każdego projektu Astro. Są to komponenty szablonów oparte wyłacznie na HTML, bez wykonywania JavaScriptu po stronie klienta. Komponenty Astro można łatwo rozpoznać po rozszerzeniu pliku, w którym się znajdują: .astro
.
Charakteryzują się one dużą elastycznością. Często zawierają elementy interfejsu wielokrotnego użytku, takie jak nagłóweki czy karty profilowe. W innych przypadkach mogą zawierać mniejsze fragmenty HTML, jak zestaw powszechnych tagów <meta>
, które ułatwiają optymalizację pod kątem wyszukiwarek. Czasem mogą nawet definiować całą strukturę strony.
Najważniejszą rzeczą do zapamiętania o komponentach Astro jest to, że nie renderują się po stronie klienta. Renderują się one do HTMLa podczas budowy strony lub na żądanie za pomocą renderowania po stronie serwera (SSR). Kod JavaScript umieszczony w frontmatterze komponentu zostanie automatycznie usunięty z ostatecznej wersji strony wysyłanej do przeglądarek użytkowników. Dzięki temu uzyskujemy szybszą witrynę, z domyślnie zerową ilością JavaScriptu.
Jeśli jednak twój komponent Astro wymaga interakcji po stronie klienta, możesz dodać standardowe tagi HTML <script>
lub interaktywne komponenty korzystające z frameworka UI.
Struktura komponentu
Dział zatytułowany Struktura komponentuKomponent Astro składa się z dwóch głównych części: skryptu oraz szablonu. Obie te części pełnią różne funkcje, ale łącznie tworzą solidne podstawy, które są zarówno łatwe w użyciu, jak i wystarczająco elastyczne, aby poradzić sobie z dowolnym projektem, który chcesz zrealizować.
Skrypt komponentu
Dział zatytułowany Skrypt komponentuAstro wykorzystuje code fence (---
), aby zidentyfikować część skryptową w twoim komponencie Astro. Jeśli miałeś styczność z Markdown, być może już znasz podobne pojęcie, znane jako frontmatter. Pomysł na skrypt komponentu Astro był bezpośrednio inspirowany tym konceptem.
Możesz użyć skryptu komponentu do napisania dowolnego kodu JavaScript, który jest potrzebny do wyrenderowania Twojego szablonu. Może to obejmować:
- Importowanie innych komponentów Astro
- Importowanie komponentów z frameworków, takich jak React
- Importowanie danych, np. pliku JSON
- Pobieranie treści z API lub bazy danych
- Tworzenie zmiennych, do których będziesz odnosić się w swoim szablonie
Code fence został zaprojektowany, aby zagwarantować, że JavaScript, który w nim piszesz, jest “ogrodzony”. Nie przecieknie do Twojej aplikacji frontendowej i nie trafi do rąk Twoich użytkowników. Możesz bezpiecznie pisać tutaj kod, który jest kosztowny lub wrażliwy (jak komunikacja z Twoją prywatną bazą danych), nie martwiąc się o to, że kiedykolwiek znajdzie się w przeglądarce.
Możesz nawet używać TypeScriptu w swoim skrypcie komponentu!
Szablon komponentu
Dział zatytułowany Szablon komponentuSzablon komponentu znajduje się poniżej code fence i określa to, jaki HTML generuje Twój komponent.
Jeżeli używasz w tym miejscu tylko znaczników HTML, Twój komponent wyrenderuje go na dowolnej stronie Astro, gdzie zostanie zaimportowany i użyty.
Jednak składnia szablonu komponentu Astro obsługuje również wyrażenia JavaScript, tagi <style>
i <script>
wspierane przez Astro, importowane komponenty, oraz specjalne dyrektywy Astro. Dane i wartości zdefiniowane w skrypcie komponentu mogą być używane w szablonie komponentu do dynamicznego generowania HTMLa.
Projektowanie oparte na komponentach
Dział zatytułowany Projektowanie oparte na komponentachKomponenty zostały zaprojektowane w taki sposób, aby można ich było używać w wielu miejscach i łączyć je w bardziej skomplikowane jednostki. Możesz stosować komponenty wewnątrz innych komponentów, aby budować coraz bardziej zaawansowane elementy interfejsu użytkownika. Na przykład komponent Button
może być użyty do stworzenia komponentu ButtonGroup
:
Propy w komponentach
Dział zatytułowany Propy w komponentachKomponent Astro może definiować i akceptować propy, które później stają się dostępne w szablonie komponentu i mogą zostać użyte w czasie renderowania HTMLa. Propy dostępne są w globalnej zmiennej Astro.props
wewnątrz skryptu frontmattera.
Oto przykład komponentu, który otrzymuje propy greeting
i name
. Zauważ, że właściwości do otrzymania są destrukturyzowane z globalnego obiektu Astro.props
.
Ten komponent, gdy jest importowany i renderowany w innych komponentach Astro, układach lub stronach, może otrzymać te propy jako atrybuty:
Możesz również definiować swoje propy za pomocą TypeScriptu używając interfejsu nazwanego Props
. Astro automatycznie wykryje interfejs Props
w Twoim frontmatterze i wyświetli ostrzeżenia/błędy typów. Propy mogą również otrzymać domyślne wartości podczas destrukturyzacji z Astro.props
.
Każdemu propowi możemy przyporządkować domyślną wartość, która zostanie użyta, jeżeli nie przekażemy żadnej wartości w miejscu użycia komponentu.
Element <slot />
jest placeholderem dla zewnętrznej zawartości HTML, pozwalając na wstrzyknięcie (lub “za-slotowanie”) elementów potomnych z innych plików do Twojego komponentu.
Domyślnie, wszystkie dzieci przekazane do komponentu, zostaną pokazane w miejscu elementu <slot />
.
W przeciwieństwie do propów, które są atrybutami przekazywanymi do komponentu Astro dostępnymi do użycia w całym twoim komponencie za pomocą Astro.props
, sloty renderują elementy HTML tam, gdzie się znajdują.
Ten wzorzec stanowi podstawę komponentu układu Astro: cała zawartość strony HTML może być “owinięta” tagami <SomeLayoutComponent></SomeLayoutComponent>
i przekazana do komponentu do renderowania wewnątrz niego, wśród stałych elementów strony takich jak nagłówek czy stopka.
Nazwane sloty
Dział zatytułowany Nazwane slotyKomponent Astro może również zawierać nazwane sloty. Dzięki temu możesz przekazać elementy HTML do konkretnego slotu o danej nazwie.
Aby nazwać slot, użyj atrybutu name
:
Aby wstrzyknąć zawartość HTML do określonego slotu, użyj atrybutu slot
na dowolnym dziecku i wskaż za jego pomocą nazwę slotu. Wszystkie inne dzieci trafią do domyślnego (nienazwanego) slotu.
Użyj atrybutu slot="my-slot"
na dziecku, które chcesz przekazać do slotu <slot name="my-slot" />
w Twoim komponencie.
Aby przekazać wiele elementów HTML do slotu komponentu bez zawijania całości w element <div>
, użyj atrybutu slot=""
na wbudowanym komponencie <Fragment />
:
Możesz teraz wstrzyknąć wiele wierszy i kolumn treści HTML wskazując za pomocą atrybutu slot=""
zawartość nagłówka ("header"
) oraz treść ("body"
). Pojedyncze elementy HTML mogą być również stylowane:
Zauważ, że nazwane sloty muszą być bezpośrednimi dziećmi komponentu. Nie możesz przkazywać nazwanych slotów przez zagnieżdżone elementy.
Nazwane sloty mogą być również przeniesione do komponentów frameworków UI!
Nie jest możliwe generowanie nazwy slotu Astro dynamiczne, np. za pomocą funkcji map
. Jeżeli potrzebujesz tej funkcjonalności wewnątrz komponentu frameworka UI, najlepiej będzie generować dynamiczne sloty wewnątrz samego frameworka.
Zastępcza zawartość w slotach
Dział zatytułowany Zastępcza zawartość w slotachSloty mogą również renderować zawartość zastępczą. Gdy wśród dzieci danego komponentu nie ma żadnych pasujących do slotu, wtedy <slot />
wyrenderuje swoje dzieci zadeklarowane w tym komponencie.
Przenoszenie slotów
Dział zatytułowany Przenoszenie slotówSloty mogą zostać przeniesione do innych komponentów. Na przykład, gdy tworzysz zagnieżdżone układy:
Nazwane sloty mogą być przeniesione do innego komponentu używając obu atrybutów: name
i slot
na elemencie <slot />
W ten sposób domyślny slot oraz ten nazwany head
przekazane do HomeLayout
zostaną przeniesione do BaseLayout
.
Komponenty HTML
Dział zatytułowany Komponenty HTMLAstro wspiera importowanie i używnaie plików .html
jako komponentów. Możesz również umieszczać takie pliki wewnątrz src/pages
, aby definiować strony. Jest to przydatne, gdy masz już istniejącą stronę zbudowaną bez użycia frameworka albo gdy chcesz mieć pewność, że komponent zawsze będzie całkowicie statyczny.
Komponenty HTML mogą zawierać tylko poprawną składnię HTML, stąd nie wspierają one kluczowych funkcjonalności zapewnianych przez Astro:
- Nie wspierają frontmattera, importów, czy wyrażeń dynamicznych
- Wszystkie elementy
<script>
nie są przetwarzanie przez Astro i zachowują się tak samo jak w przypadku użyciais:inline
. - Mogą tylko korzystać z zasobów obecnych w katalogu
public/
.
Element <slot />
umieszczony wewnątrz komponentu HTML będzie działał normalnie, tak jak w przypadku komponentu Astro. Jeżeli chcesz zamiast tego użyć elementu HTML Web Component Slot, dodaj do niego is:inline
.