Karty, ikony, obrazy i badge

Karta z ikoną i obrazem

Karta jest kontenerem z treścią, kolorem, obramowaniem i zaokrągleniem. Nie musi zawierać wszystkich elementów naraz. Przykład blocks/media-card.html ma opcjonalny obraz, wybór ikony, rozmiar ikony, tytuł i opis. Dodaj plik do paczki i dopuść media-card w schema rodzica.

1. Powierzchnia karty

<article data-canvas-card="[[ block.field_path ]].card" style="background:[[ block.settings.background ]];border:[[ block.settings.border_width ]]px solid [[ block.settings.border_color ]];border-radius:[[ block.settings.radius ]]px">
  <h2 data-text-field="[[ block.settings_path ]].title" gs-text="block.settings.title"></h2>
</article>

data-canvas-card podłącza edytor powierzchni karty. Schema daje dodatkowo jawne kontrolki koloru, grubości i promienia z wartościami początkowymi. Nie przypisuj jednego identyfikatora wszystkim kartom. block.field_path zapewnia osobną ścieżkę dla każdej instancji.

Nadpisania wyglądu z edycji na podglądzie są zapisywane w content.canvas.elements. Jeśli zmiana wartości schema nie daje spodziewanego efektu, sprawdź nadpisanie danego elementu i przywróć domyślny styl w edytorze. To dwie warstwy konfiguracji, nie dwa niezależne elementy.

2. Ikona

<span class="launch-card-icon" style="--icon-size:[[ block.settings.icon_size ]]px">
  <gs-icon name="[[ block.settings.icon ]]" field="[[ block.field_path ]].icon"></gs-icon>
</span>

W schema użyj select z faktycznymi nazwami ikon. Dostępny katalog: spark, star, check, arrow, heart, plus, globe, shield, users, bolt, wallet, cards, insights. Wartość none oznacza brak ikony.

Rozmiar deklaruj jako range, np. 16–96 px, domyślnie 32. CSS odczytuje zmienną: .launch-card-icon svg { width:var(--icon-size,32px); height:var(--icon-size,32px); }. Bez użycia wartości w CSS sam suwak niczego nie zmienia. Powiązanie field umożliwia też zmianę ikony i wymiarów przez wspólny edytor elementu.

W przykładzie ikona none nie jest renderowana. Aby ją przywrócić, użyj kontrolki schema. Nie pokazuj fikcyjnej ikony w miejscu, gdzie jej nie ma.

3. Obraz i tekst alternatywny

<template gs-if="block.settings.image_url != blank">
<img src="[[ safe_url(block.settings.image_url) ]]" alt="[[ block.settings.image_alt ]]" loading="lazy" width="640" height="400">
</template>

image_picker obecnie jest polem adresu obrazu. Użyj HTTPS lub adresu z biblioteki mediów. image_alt jest osobnym ustawieniem tekstowym: opisuje znaczenie obrazu; dla dekoracji może być pusty. Nie wpisuj nazwy pliku zamiast opisu.

Ustaw szerokość i wysokość odpowiadające zamierzonemu obszarowi, aby ograniczyć przeskoki układu. CSS przykładu używa aspect-ratio i object-fit:cover. To kadrowanie CSS, nie zapis interaktywnego kadru. Wspólne gs-image obsługuje inne pola treści (image_url, sąsiednie image_alt i image_frame); nie zamieniaj tych modeli bez jawnego mapowania danych.

4. Badge

Badge to krótka etykieta, nie automatycznie link. Dodaj do schema tekst o ID badge, kolor oraz promień, a w HTML:

<span class="theme-badge" data-text-field="[[ block.settings_path ]].badge" gs-text="block.settings.badge"></span>

Styl przykładowy: display:inline-flex; padding:6px 12px; border:1px solid currentColor; border-radius:999px. Jeśli badge ma mieć ikonę, użyj gs-icon z własną ścieżką i realnym stanem „brak”. Jeżeli ma nawigować, użyj dostępnego linku, jak w przyciskach.

5. Lista kart i responsywność

Rodzic renderuje dzieci przez gs-slot="blocks"; CSS określa siatkę. Każda karta zachowuje własne ustawienia podczas zmiany kolejności. Nie zapisuj szerokości ekranu w schema jako stałej szerokości każdej karty. Użyj minmax i sprawdź długie teksty oraz puste obrazy na telefonie.

Test końcowy

Dodaj dwie karty o różnych kolorach, zmień kolejność i sprawdź zapis. Wyłącz ikonę, przywróć ją, zmień rozmiar, ustaw promień i obramowanie na 0. Sprawdź pusty URL obrazu, poprawny obraz, alt, edytor karty oraz publiczny renderer. Nadpisania wyglądu nie powinny przenosić się między instancjami.

Kompletny plik bloku

blocks/media-card.html

<article class="launch-card" data-canvas-card="[[ block.field_path ]].card" style="background:[[ block.settings.background ]];border:[[ block.settings.border_width ]]px solid [[ block.settings.border_color ]];border-radius:[[ block.settings.radius ]]px">
  <template gs-if="block.settings.icon != &#x27;none&#x27;"><span class="launch-card-icon" style="color:[[ block.settings.icon_color ]];--icon-size:[[ block.settings.icon_size ]]px"><gs-icon name="[[ block.settings.icon ]]" field="[[ block.field_path ]].icon"></gs-icon></span></template>
  <template gs-if="block.settings.image_url != blank"><img class="launch-card-image" src="[[ safe_url(block.settings.image_url) ]]" alt="[[ block.settings.image_alt ]]" loading="lazy" width="640" height="400"></template>
  <h2 data-text-field="[[ block.settings_path ]].title" gs-text="block.settings.title"></h2>
  <p data-text-field="[[ block.settings_path ]].text" gs-text="block.settings.text"></p>
</article>