Taxonomien

Eine Taxonomie ist eine benannte Klassifikation, die auf eine oder mehrere Collections angewendet wird. EmDash startet mit der hierarchischen Taxonomie category und der flachen Taxonomie tag für Posts. Eine Site kann auch Taxonomien wie genre, topic oder difficulty definieren.

Terms gehören zu einer Taxonomie. Eine Kategorie wie „Guides“ kann Kindkategorien haben, während Tags und andere flache Taxonomien eine Ebene haben.

Terms verwalten

Öffnen Sie eine Taxonomie über Taxonomies in der EmDash-Administration.

Redakteure weisen Terms aus den Taxonomie-Panels in einem Inhaltseintrag zu. Die Taxonomie-Definition steuert, welche Collections jedes Panel zeigen.

Das Löschen eines Terms entfernt seine Zuweisungen vom Inhalt. Es löscht die Inhaltseinträge nicht.

Einen Tag zu mehreren Posts hinzufügen

Redakteure können Posts in einer Collection-Liste auswählen und Add tag klicken oder Tags öffnen und Add to posts klicken, um öffentliche Post-URLs einzufügen (eine pro Zeile, bis zu 50). Wählen Sie einen bestehenden Tag oder erstellen Sie einen im Dialog, dann klicken Sie auf Review posts. Prüfen Sie jeden gefundenen Titel und jede Sprache, dann klicken Sie auf den Button, der anzeigt, wie viele Posts getaggt werden. Links, die nicht exakt zu einem veröffentlichten Post auf dieser Site passen, werden markiert statt geraten.

Das Hinzufügen des Tags wirkt sofort, auch wenn ein Post andere unveröffentlichte Draft-Änderungen hat; es veröffentlicht diese Änderungen nicht. Bestehende Tags bleiben, und Posts, die den Tag bereits haben, werden übersprungen. Die Ergebnisliste zeigt, welche Posts getaggt, übersprungen oder nicht getaggt werden konnten; nutzen Sie Retry failures bei Schreibfehlern. URL-Matching nutzt den konfigurierten öffentlichen Origin der Site und die URL-Muster der Collections, einschließlich Datums- und Sprachpfaden.

Eine benutzerdefinierte Taxonomie hinzufügen

Erstellen Sie eine Taxonomie, wenn eine bestehende Collection eine separate Klassifikation braucht.

Templates fragen den stabilen Namen ab. Das Ändern eines Anzeige-Labels erfordert keine Template-Änderung.

Benutzerdefinierte Taxonomien nutzen dieselben Abfrage- und Filterhelfer wie Kategorien und Tags. Das folgende Beispiel liest die genre-Terms und filtert Bücher nach einem ihrer Slugs:

import { getEmDashCollection, getTaxonomyTerms } from "emdash";

const genres = await getTaxonomyTerms("genre", { includeCounts: false });
const { entries: scienceFictionBooks } = await getEmDashCollection("books", {
  where: { genre: "science-fiction" },
});

Eine Taxonomie löschen

Öffnen Sie die Taxonomie in der Administration, wählen Sie dann Delete taxonomy aus dem Aktionsmenü in der Seitenkopfzeile und bestätigen Sie. Die Aktion erfordert die Berechtigung taxonomies:manage, die Redakteure und Administratoren haben.

Das Löschen einer Taxonomie löscht ihre Terms in jeder Sprache und entfernt diese Terms aus dem darunter abgelegten Inhalt. Die Inhaltseinträge selbst bleiben erhalten.

Eine Term-Liste abfragen

Nutzen Sie getTaxonomyTerms(), um einen Taxonomie-Index, eine Navigationsliste oder Filtersätze zu rendern. Hierarchische Taxonomien liefern einen Baum über das children-Array jedes Terms.

Term-Zählungen sind standardmäßig enthalten und erfordern eine Aggregation über die zugewiesenen Collections der Taxonomie. Überspringen Sie diese Arbeit, wenn die Komponente keine Zählungen anzeigt.

Die folgende Komponente rendert Kategorie-Links ohne Zählungen:

---
import { getTaxonomyTerms } from "emdash";
import { getRelativeLocaleUrl } from "astro:i18n";

const locale = Astro.currentLocale;
const categories = await getTaxonomyTerms("category", {
  locale,
  includeCounts: false,
});

function categoryHref(slug: string) {
  const path = `/category/${slug}`;
  return locale ? getRelativeLocaleUrl(locale, path) : path;
}
---

<nav aria-label="Categories">
  <ul>
    {categories.map((category) => (
      <li>
        <a href={categoryHref(category.slug)}>{category.label}</a>
        {category.children.length > 0 && (
          <ul>
            {category.children.map((child) => (
              <li><a href={categoryHref(child.slug)}>{child.label}</a></li>
            ))}
          </ul>
        )}
      </li>
    ))}
  </ul>
</nav>

Wenn eine Komponente die Nutzung anzeigt, lassen Sie includeCounts: false weg und rendern Sie term.count. Die Zählung umfasst öffentlich sichtbare Einträge in der für die Abfrage genutzten Locale.

Ein Taxonomie-Archiv bauen

Dekodieren Sie einen dynamischen Routenparameter, bevor Sie einen Term nachschlagen. Fragen Sie Term und Inhalt mit derselben Locale ab und leiten Sie generierte Pfade durch Astros Locale-URL-Helfer.

Die folgende Route listet veröffentlichte Posts in einer Kategorie:

---
import { decodeSlug, getEmDashCollection, getTerm } from "emdash";
import { getRelativeLocaleUrl } from "astro:i18n";
import Base from "../../layouts/Base.astro";

const locale = Astro.currentLocale;
const slug = decodeSlug(Astro.params.slug);
const category = slug
  ? await getTerm("category", slug, { locale, includeCounts: false })
  : null;

if (!category) {
  return Astro.redirect("/404");
}

const { entries: posts } = await getEmDashCollection("posts", {
  status: "published",
  locale,
  where: { category: category.slug },
  orderBy: { published_at: "desc" },
});

function postHref(postSlug: string) {
  const path = `/posts/${postSlug}`;
  return locale ? getRelativeLocaleUrl(locale, path) : path;
}
---

<Base title={`${category.label} posts`}>
  <h1>{category.label}</h1>
  {category.description && <p>{category.description}</p>}

  {posts.length > 0 ? (
    <ul>
      {posts.map((post) => (
        post.data.slug && (
          <li>
            <a href={postHref(post.data.slug)}>{post.data.title}</a>
          </li>
        )
      ))}
    </ul>
  ) : (
    <p>No posts in this category.</p>
  )}
</Base>

where nutzt den Taxonomie-Namen als Schlüssel und einen Term-Slug als Wert. Abfrage-Sortierkennungen nutzen Datenbankfeldnamen wie published_at; Eintragsdaten stellen den entsprechenden Wert als publishedAt bereit.

Nutzen Sie die tatsächliche öffentliche Route der Collection in postHref(). Wenn die Collection ein benutzerdefiniertes urlPattern nutzt, bauen Sie Links aus diesem Muster, statt /posts/{slug} anzunehmen.

Die Terms eines Eintrags anzeigen

getEmDashEntry() und getEmDashCollection() hydrieren zugewiesene Terms auf entry.data.terms. Lesen Sie diesen Wert, statt für jeden Eintrag in einer Liste eine getEntryTerms()-Abfrage auszuführen.

Die folgende Komponente rendert Kategorien und Tags, die bereits mit einem Post geladen wurden:

---
import type { ContentEntry, InferCollectionData } from "emdash";
import { getRelativeLocaleUrl } from "astro:i18n";

interface Props {
  post: ContentEntry<InferCollectionData<"posts">>;
}

const { post } = Astro.props;
const locale = Astro.currentLocale;
const categories = post.data.terms?.category ?? [];
const tags = post.data.terms?.tag ?? [];

function termHref(taxonomy: string, slug: string) {
  const path = `/${taxonomy}/${slug}`;
  return locale ? getRelativeLocaleUrl(locale, path) : path;
}
---

{categories.length > 0 && (
  <ul aria-label="Categories">
    {categories.map((category) => (
      <li>
        <a href={termHref("category", category.slug)}>{category.label}</a>
      </li>
    ))}
  </ul>
)}

{tags.length > 0 && (
  <ul aria-label="Tags">
    {tags.map((tag) => (
      <li>
        <a href={termHref("tag", tag.slug)}>{tag.label}</a>
      </li>
    ))}
  </ul>
)}

Nutzen Sie getEntryTerms(), wenn Sie nur einen Collection-Namen und eine Entry-ID haben. Nutzen Sie getTermsForEntries(), um Terms für mehrere Einträge zu bündeln, wenn sie nicht durch die Inhaltsabfrage hydriert wurden.

Taxonomien und Terms übersetzen

Taxonomie-Definitionen und Terms haben eine Zeile pro Locale. EmDash zeichnet auf, welche Zeilen Übersetzungen derselben Taxonomie oder desselben Terms sind. Inhaltszuweisungen nutzen diese gemeinsame Identität, sodass eine Zuweisung in einer Locale zum übersetzten Term in einer anderen Locale auflöst, wenn einer existiert.

Eine Taxonomie-Definition teilt ihre Felder zwischen der Taxonomie und jeder Locale:

Eine Definition, die für einen Namen erstellt wird, der bereits in einer anderen Locale existiert, tritt dieser Taxonomie bei, mit oder ohne translationOf, und übernimmt ihre hierarchical und collections. Das Erstellen mit anderen Werten scheitert; ändern Sie sie mit einem Update. Eine Locale ohne eigene Definition listet weiterhin die Terms der Taxonomie und zeigt das Label der ersten Locale in ihrer Fallback-Kette, die eines hat, sonst das Label der Standard-Locale, sonst das Label der Locale mit dem niedrigsten Locale-Code.

Nutzen Sie den Locale-Umschalter auf einer Taxonomie-Seite, um Terms in jeder konfigurierten Locale zu verwalten. Öffnen Sie den Bearbeitungsdialog eines Terms und nutzen Sie sein Translations-Panel, um eine weitere Locale hinzuzufügen oder zu öffnen. Ein übersetzter Term kann einen anderen Slug und ein anderes Label nutzen.

Parent und Position eines Terms werden von jeder Locale geteilt. Eine Übersetzung, die ohne Parent erstellt wird, übernimmt Parent und Position ihres Terms. Das Erstellen einer Übersetzung unter einem anderen Parent oder das Ändern des Parents über eine Locale verschiebt den Term in jeder Locale.

Die Abfragehelfer nutzen eine explizite Locale, wenn sie geliefert wird. Andernfalls nutzen sie die aktuelle Request-Locale, dann die konfigurierte Standard-Locale. Einzelterm-Lookups folgen der konfigurierten Fallback-Kette, wenn die angeforderte Übersetzung fehlt.

Siehe Internationalization für Locale-Routing und Fallback-Konfiguration und Working with Content für das Bearbeiten von Einträgen. Die Runtime-API-Referenz dokumentiert Taxonomie-Abfragehelfer. Für programmatische Änderungen authentifizieren Sie sich mit einem Bearer-Token und fügen Sie X-EmDash-Request: 1 zu jeder zustandsändernden Anfrage hinzu. Siehe die Taxonomie-Endpoints für Request-Bodies und Antworten.