Przejdź do głównej zawartości

Komponenty

Komponenty Astro stanowią podstawę każdego projektu Astro. Są to komponenty szablonów oparte wyłącznie na HTML, bez wykonywania kodu po stronie klienta, i używają rozszerzenia .astro.

Komponenty Astro są bardzo elastyczne. Komponent Astro może być tak mały jak fragment HTML, na przykład zestaw powszechnych tagów <meta>, które ułatwiają optymalizację pod kątem wyszukiwarek. Komponenty mogą być elementami interfejsu wielokrotnego użytku, takimi jak nagłówek czy karta profilowa. Mogą nawet zawierać cały layout strony albo, gdy znajdują się w specjalnym katalogu src/pages/, być całą stroną.

Najważniejszą rzeczą do zapamiętania o komponentach Astro jest to, że nie renderują się po stronie klienta. Renderują się do HTML w czasie budowania albo przy renderowaniu na żądanie. Kod JavaScript umieszczony we frontmatterze komponentu zostanie usunięty z ostatecznej strony wysyłanej do przeglądarek użytkowników. Dzięki temu strona jest szybsza i domyślnie nie dokłada własnego JavaScriptu.

Jeśli komponent Astro potrzebuje interakcji po stronie klienta, możesz dodać standardowe tagi HTML <script> (EN) albo komponenty frameworków UI (EN) jako „wyspy klienckie”.

W komponentach, które mają renderować spersonalizowaną lub dynamiczną treść, możesz odłożyć renderowanie po stronie serwera, dodając dyrektywę serwerową (EN). Takie „wyspy serwerowe” wyrenderują treść, gdy będzie dostępna, bez opóźniania wczytania całej strony.

Komponent 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ć.

src/components/EmptyComponent.astro
---
// Skrypt komponentu (JavaScript)
---
<!-- Szablon komponentu (HTML + wyrażenia JS) -->

Astro 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
src/components/MyComponent.astro
---
import SomeAstroComponent from '../components/SomeAstroComponent.astro';
import SomeReactComponent from '../components/SomeReactComponent.jsx';
import someData from '../data/pokemon.json';
// Dostęp do przekazanych propów komponentu, np. `<X title="Witaj, Świecie" />`
const { title } = Astro.props;
// Pobieranie zewnętrznych danych, nawet z prywatnego API lub bazy danych
const data = await fetch('SOME_SECRET_API_URL/users').then(r => r.json());
---
<!-- Tutaj Twój szablon komponentu! -->

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.

Szablon 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> (EN) i <script> (EN) wspierane przez Astro, importowane komponenty, oraz specjalne dyrektywy Astro (EN). Dane i wartości zdefiniowane w skrypcie komponentu mogą być używane w szablonie komponentu do dynamicznego generowania HTMLa.

src/components/MyFavoritePokemon.astro
---
// Tutaj Twój skrypt komponentu!
import Banner from '../components/Banner.astro';
import Avatar from '../components/Avatar.astro';
import ReactPokemonComponent from '../components/ReactPokemonComponent.jsx';
const myFavoritePokemon = [/* ... */];
const { title } = Astro.props;
---
<!-- Komentarze HTML są wspierane! -->
{/* Składnia komentarza JavaScript również jest wspierana! */}
<Banner />
<h1>Witaj świecie!</h1>
<!-- Użyj propów i innych zmiennych z skryptu komponentu: -->
<p>{title}</p>
<!-- Opóźnij renderowanie komponentu i pokaż zastępczą treść ładowania: -->
<Avatar server:defer>
<svg slot="fallback" class="generic-avatar" transition:name="avatar">...</svg>
</Avatar>
<!-- Dołącz komponenty frameworków UI za pomocą dyrektywy `client:` w celu przeprowadzenia hydracji: -->
<ReactPokemonComponent client:visible />
<!-- Mieszaj HTML z wyrażeniami JavaScript, podobnie jak w JSX: -->
<ul>
{myFavoritePokemon.map((data) => <li>{data.name}</li>)}
</ul>
<!-- Użyj dyrektywy szablonu do budowania nazw klas z wielu ciągów znaków lub nawet obiektów! -->
<p class:list={["add", "dynamic", { classNames: true }]} />

Komponenty 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:

src/components/ButtonGroup.astro
---
import Button from './Button.astro';
---
<div>
<Button title="Przycisk 1" />
<Button title="Przycisk 2" />
<Button title="Przycisk 3" />
</div>

Komponent 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.

src/components/GreetingHeadline.astro
---
// Użycie: <GreetingHeadline greeting="Cześć" name="przyjacielu" />
const { greeting, name } = Astro.props;
---
<h2>{greeting}, {name}!</h2>

Ten komponent, gdy jest importowany i renderowany w innych komponentach Astro, układach lub stronach, może otrzymać te propy jako atrybuty:

src/components/GreetingCard.astro
---
import GreetingHeadline from './GreetingHeadline.astro';
const name = 'Astro';
---
<h1>Karta pozdrowień</h1>
<GreetingHeadline greeting="Cześć" name={name} />
<p>Mam nadzieję, że masz wspaniały dzień!</p>

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.

src/components/GreetingHeadline.astro
---
interface Props {
name: string;
greeting?: string;
}
const { greeting = "Cześć", name } = Astro.props;
---
<h2>{greeting}, {name}!</h2>

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.

src/components/GreetingHeadline.astro
---
const { greeting = "Cześć", name = "astronauto" } = Astro.props;
---
<h2>{greeting}, {name}!</h2>

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 />.

src/components/Wrapper.astro
---
import Header from './Header.astro';
import Logo from './Logo.astro';
import Footer from './Footer.astro';
const { title } = Astro.props;
---
<div id="content-wrapper">
<Header />
<Logo />
<h1>{title}</h1>
<slot /> <!-- elementy potomne będą tutaj -->
<Footer />
</div>
src/pages/fred.astro
---
import Wrapper from '../components/Wrapper.astro';
---
<Wrapper title="Strona Freda">
<h2>Wszystko o Fredzie</h2>
<p>Oto kilka rzeczy o Fredzie.</p>
</Wrapper>

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.

Zobacz funkcje pomocnicze Astro.slots, aby poznać więcej sposobów odczytu i renderowania zawartości slotów.

Komponent 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:

src/components/Wrapper.astro
---
import Header from './Header.astro';
import Logo from './Logo.astro';
import Footer from './Footer.astro';
const { title } = Astro.props;
---
<div id="content-wrapper">
<Header />
<!-- dzieci z `slot="after-header"` zostaną pokazane tutaj -->
<slot name="after-header" />
<Logo />
<h1>{title}</h1>
<!-- dzieci bez `slot`, albo z `slot="default"` zostaną pokazane tutaj -->
<slot />
<Footer />
<!-- dzieci z `slot="after-footer"` zostaną pokazane tutaj -->
<slot name="after-footer" />
</div>

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.

src/pages/fred.astro
---
import Wrapper from '../components/Wrapper.astro';
---
<Wrapper title="Strona Freda">
<img src="https://my.photo/fred.jpg" slot="after-header" />
<h2>Wszystko o Fredzie</h2>
<p>Oto kilka rzeczy o Fredzie.</p>
<p slot="after-footer">Copyright 2022</p>
</Wrapper>

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 />:

src/components/CustomTable.astro
---
// Stwórz własną tabelę z nazwanymi slotami na treść nagłówka i treści głównej
---
<table class="bg-white">
<thead class="sticky top-0 bg-white"><slot name="header" /></thead>
<tbody class="[&_tr:nth-child(odd)]:bg-gray-100"><slot name="body" /></tbody>
</table>

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:

src/components/StockTable.astro
---
import CustomTable from './CustomTable.astro';
---
<CustomTable>
<Fragment slot="header"> <!-- przekaż nagłówek tabeli -->
<tr><th>Nazwa produktu</th><th>Ilość</th></tr>
</Fragment>
<Fragment slot="body"> <!-- przekaż zawartość tabeli -->
<tr><td>Klapki</td><td>64</td></tr>
<tr><td>Buty turystyczne</td><td>32</td></tr>
<tr><td>Trampki</td><td class="text-red-500">0</td></tr>
</Fragment>
</CustomTable>

Zauważ, że nazwane sloty muszą być bezpośrednimi dziećmi komponentu. Nie możesz przkazywać nazwanych slotów przez zagnieżdżone elementy.

Sloty 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.

src/components/Wrapper.astro
---
import Header from './Header.astro';
import Logo from './Logo.astro';
import Footer from './Footer.astro';
const { title } = Astro.props;
---
<div id="content-wrapper">
<Header />
<Logo />
<h1>{title}</h1>
<slot>
<p>To moja zawartość zastępcza, która zostanie użyta, gdy nie będzie pasującego dziecka.</p>
</slot>
<Footer />
</div>

Zastępcza zawartość pojawi się tylko wtedy, gdy do nazwanego slotu nie przekazano żadnego elementu z atrybutem slot="name".

Astro przekaże pusty slot, gdy element slotu istnieje, ale nie ma treści do przekazania. Zastępczej zawartości nie można użyć jako wartości domyślnej, gdy przekazano pusty slot. Jest ona wyświetlana tylko wtedy, gdy nie znaleziono elementu slotu.

Sloty mogą zostać przeniesione do innych komponentów. Na przykład, gdy tworzysz zagnieżdżone układy:

src/layouts/BaseLayout.astro
---
---
<html lang="en">
<head>
<meta charset="utf-8" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<meta name="viewport" content="width=device-width" />
<meta name="generator" content={Astro.generator} />
<slot name="head" />
</head>
<body>
<slot />
</body>
</html>
">
src/layouts/HomeLayout.astro
---
import BaseLayout from './BaseLayout.astro';
---
<BaseLayout>
<slot name="head" slot="head" />
<slot />
</BaseLayout>

W ten sposób domyślny slot oraz ten nazwany head przekazane do HomeLayout zostaną przeniesione do BaseLayout.

src/pages/index.astro
---
import HomeLayout from '../layouts/HomeLayout.astro';
---
<HomeLayout>
<title slot="head">Astro</title>
<h1>Astro</h1>
</HomeLayout>

Astro 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:

Dowiedz się jak możesz używać komponentów frameworków UI (EN) w Twoim projekcie Astro.
Pomóż nam Społeczność Zostań sponsorem