Widget-Bereiche

Ein Widget-Bereich ist eine benannte Position in einem Site-Template. Redakteure legen fest, was dort erscheint, während das Template bestimmt, wo der Bereich liegt und wie seine Ausgabe gestaltet wird.

Verwenden Sie einen Widget-Bereich für Inhalte, die überall, wo der Bereich erscheint, synchron bleiben sollen, etwa eine Seitenleiste, eine Footer-Spalte oder eine Werbebotschaft. Verwenden Sie stattdessen eine Section, wenn ein Redakteur eine unabhängige Kopie in einen Eintrag einfügen und anschließend anpassen soll.

Einen Widget-Bereich hinzufügen

Erstellen und befüllen Sie Widget-Bereiche unter Widgets im EmDash-Admin.

Die verfügbaren Widget-Typen sind:

• Content rendert von einem Redakteur eingegebenen Portable Text.
• Menu rendert ein nach Namen ausgewähltes Menü.
• Component rendert eine der integrierten Komponenten: aktuelle Beiträge, Kategorien, Tags, Suche oder Archive.

Die Komponenten-Einstellungen im Admin steuern Details wie Anzahlbegrenzungen, Datumsangaben, Zählwerte und den Platzhaltertext der Suche.

Die folgenden integrierten Komponenten-Widgets sind verfügbar:

Die Link-Vorlage von core:recent-posts akzeptiert dieselben Token wie die routeMap von LiveSearch: :collection, :id (die Content-ULID), :slug (der reine Slug) und :path (Slug oder ID). Ohne Vorlage behalten Links ihre bisherige Form, einschließlich eines etwaigen Astro-i18n-Locale-Präfixes.

Den Bereich in einem Template platzieren

Importieren Sie WidgetArea aus emdash/ui. Die Komponente ruft den benannten Bereich ab, behält die konfigurierte Reihenfolge bei und rendert nichts, wenn der Bereich fehlt oder leer ist.

Das folgende Layout platziert einen Seitenleisten-Bereich neben dem Seiteninhalt:

---
import { WidgetArea } from "emdash/ui";
---

<div class="page-with-sidebar">
  <main>
    <slot />
  </main>

  <aside aria-label="Sidebar">
    <WidgetArea name="sidebar" class="sidebar-widgets" />
  </aside>
</div>

WidgetArea fügt seinem Wrapper widget-area und die übergebene class hinzu. Jedes Element verwendet die Klassen widget, widget__title und widget__content. Content-, Menü- und integrierte Komponenten-Widgets fügen darunter spezifischere Klassen hinzu.

Astro-Komponentenstile sind standardmäßig gescoped. Verwenden Sie einen globalen Style-Block, wenn Sie das innerhalb von WidgetArea gerenderte Markup gestalten:

<style is:global>
  .page-with-sidebar {
    display: grid;
    grid-template-columns: minmax(0, 1fr) 18rem;
    gap: 2rem;
  }

  .sidebar-widgets {
    display: grid;
    gap: 1.5rem;
  }

  .sidebar-widgets .widget__title {
    margin-block-end: 0.75rem;
  }

  @media (max-width: 48rem) {
    .page-with-sidebar {
      grid-template-columns: 1fr;
    }
  }
</style>

Menüs und Taxonomien in Widgets

Menü-, Kategorie- und Tag-Widgets fragen Daten in der Locale der aktuellen Anfrage ab. Menüverweise werden außerdem auf den übersetzten Inhalt oder Term aufgelöst, sofern einer existiert.

Der integrierte Widget-Renderer verwendet die Root-relative URL, die der Menü- oder Taxonomie-Helper zurückgibt. Er fügt kein Astro-Locale-Präfix hinzu. Rendern Sie auf einer mehrsprachigen Site Navigation und Taxonomielisten mit dem Muster zum Rendern eines Menüs oder dem Muster für Term-Listen, wenn diese Links Locale-Präfixe benötigen. Content-, Such-, Aktuelle-Beiträge- und Archiv-Widgets können weiterhin die Standardkomponente WidgetArea verwenden.

Einen Bereich selbst rendern

Rufen Sie getWidgetArea() auf, wenn die Site Markup benötigt, das der integrierte Renderer nicht liefert. Das folgende Beispiel rendert einen Bereich mit Content- und Menü-Widgets und fügt Menü-Links das Astro-Locale-Präfix hinzu.

Rufen Sie zunächst den Bereich ab und übergeben Sie jedes konfigurierte Widget an einen Renderer:

---
import { getWidgetArea } from "emdash";
import LocalizedWidget from "./LocalizedWidget.astro";

interface Props {
  name: string;
}

const area = await getWidgetArea(Astro.props.name);
---

{area && area.widgets.length > 0 && (
  <div class="widget-area" data-widget-area={area.name}>
    {area.widgets.map((widget) => (
      <LocalizedWidget widget={widget} />
    ))}
  </div>
)}

Behandeln Sie anschließend Content- und Menü-Widgets explizit:

---
import { getMenu } from "emdash";
import type { Widget } from "emdash";
import { PortableText } from "emdash/ui";
import { getRelativeLocaleUrl } from "astro:i18n";

interface Props {
  widget: Widget;
}

const { widget } = Astro.props;
const locale = Astro.currentLocale;
const menu = widget.type === "menu" && widget.menuName
  ? await getMenu(widget.menuName, { locale })
  : null;

function menuHref(url: string) {
  return locale && url.startsWith("/")
    ? getRelativeLocaleUrl(locale, url)
    : url;
}
---

{widget.type !== "component" && (
  <section class="widget" data-widget-id={widget.id}>
    {widget.title && <h3>{widget.title}</h3>}

    {widget.type === "content" && widget.content && (
      <PortableText value={widget.content} />
    )}

    {widget.type === "menu" && menu && (
      <nav aria-label={widget.title}>
        <ul>
          {menu.items.map((item) => (
            <li>
              <a
                href={menuHref(item.url)}
                target={item.target}
                rel={item.target === "_blank" ? "noopener noreferrer" : undefined}
              >
                {item.label}
              </a>
            </li>
          ))}
        </ul>
      </nav>
    )}
  </section>
)}

Dieser spezialisierte Renderer erzeugt für Komponenten-Widgets keine Ausgabe. Belassen Sie Komponenten-Widgets im Standard-WidgetArea oder fügen Sie explizite Fälle mit Komponenten-IDs für die Site-Komponenten hinzu, die Sie unterstützen.

Die Laufzeit-API-Referenz dokumentiert getWidgetArea() und getWidgetAreas(). Für programmatische Änderungen authentifizieren Sie sich mit einem Bearer-Token und fügen jeder zustandsändernden Anfrage X-EmDash-Request: 1 hinzu. Anfragekörper und Antworten finden Sie unter Widget-Bereich-Endpunkte.