Áreas de widgets

Un área de widgets es una posición con nombre en una plantilla del sitio. Los editores eligen qué aparece allí, mientras que la plantilla controla dónde se sitúa el área y cómo se estiliza su salida.

Usa un área de widgets para contenido que deba mantenerse sincronizado dondequiera que aparezca el área, como una barra lateral, una columna del pie de página o un mensaje promocional. Usa una sección cuando un editor deba insertar y luego personalizar una copia independiente dentro de una entrada.

Añadir un área de widgets

Crea y rellena las áreas de widgets en Widgets en el administrador de EmDash.

Los tipos de widget disponibles son:

• Content renderiza Portable Text introducido por un editor.
• Menu renderiza un menú seleccionado por nombre.
• Component renderiza uno de los componentes integrados: entradas recientes, categorías, etiquetas, búsqueda o archivos.

Los ajustes del componente en el administrador controlan detalles como los límites de elementos, las fechas, los recuentos y el texto de marcador de posición de la búsqueda.

Están disponibles los siguientes widgets de componente integrados:

La plantilla de enlace de core:recent-posts acepta los mismos tokens que el routeMap de LiveSearch: :collection, :id (el ULID del contenido), :slug (el slug simple) y :path (slug o ID). Sin plantilla, los enlaces conservan su forma actual, incluido cualquier prefijo de idioma de i18n de Astro.

Colocar el área en una plantilla

Importa WidgetArea desde emdash/ui. El componente obtiene el área con nombre, conserva el orden configurado y no renderiza nada cuando el área no existe o está vacía.

El siguiente layout coloca un área de barra lateral junto al contenido de la página:

---
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 añade widget-area y la class proporcionada a su contenedor. Cada elemento usa las clases widget, widget__title y widget__content. Los widgets de contenido, de menú y de componente integrado añaden clases más específicas por debajo de ellas.

Los estilos de los componentes Astro tienen alcance local por defecto. Usa un bloque de estilos global al aplicar estilos al marcado renderizado dentro de WidgetArea:

<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 y taxonomías en widgets

Los widgets de menú, categoría y etiqueta consultan datos en el idioma de la solicitud actual. Las referencias de los menús también se resuelven al contenido o término traducido cuando existe.

El renderizador de widgets integrado usa la URL relativa a la raíz que devuelve el helper de menú o taxonomía. No añade el prefijo de idioma de Astro. En un sitio multilingüe, renderiza la navegación y las listas de taxonomías con el patrón de renderizado de menús o el patrón de lista de términos cuando esos enlaces necesiten prefijos de idioma. Los widgets de contenido, búsqueda, entradas recientes y archivos pueden seguir usando el componente estándar WidgetArea.

Renderizar un área por tu cuenta

Llama a getWidgetArea() cuando el sitio necesite un marcado que el renderizador integrado no ofrece. El siguiente ejemplo renderiza un área que contiene widgets de contenido y de menú, y añade el prefijo de idioma de Astro a los enlaces del menú.

Primero, obtén el área y pasa cada widget configurado a un renderizador:

---
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>
)}

Después, gestiona explícitamente los widgets de contenido y de menú:

---
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>
)}

Este renderizador específico no produce salida para los widgets de componente. Mantén los widgets de componente en el WidgetArea estándar, o añade casos explícitos por ID de componente para los componentes del sitio que admitas.

La referencia de la API de tiempo de ejecución documenta getWidgetArea() y getWidgetAreas(). Para hacer cambios mediante programación, autentícate con un token Bearer y añade X-EmDash-Request: 1 a cada solicitud que cambie el estado. Consulta los endpoints de áreas de widgets para ver los cuerpos de las solicitudes y las respuestas.