Drei Werkzeuge für drei Aufgaben. Link macht etwas anklickbar, entweder ins Web oder zu einer anderen Stelle im selben Dokument. Anchor markiert diese Stelle. Bookmark füllt den Outline-Baum, den Ihr PDF-Viewer in seiner Seitenleiste zeigt.

Links ins Web

Umschließen Sie ein beliebiges Element, und seine ganze Box wird zur Hit-Area - ein Bild, eine Box, eine Zeile.

Link({ href: "https://jasy.dev" }, Box({ bg: "#f3dc29", padding: 12 }, [Text("Read the docs")]));

Ein Link zeichnet selbst nichts, gestalten Sie also das Kind, wenn es wie ein Link aussehen soll.

Für einen Link auf einem Teil einer Zeile setzen Sie href stattdessen an einen span. Nur dieses Stück wird anklickbar, und der Text fließt drumherum weiter:

Paragraph([
  span("Built with "),
  span("jasy", { href: "https://jasy.dev", color: "#1450aa", bold: true }),
  span(", and the rest of this sentence is not a link."),
]);

Ein Span, der in eine zweite Zeile umbricht, bekommt pro Zeile ein klickbares Rechteck, das ganze Stück bleibt also anklickbar. Ein einfacher String funktioniert auch: Text("jasy.dev", { href: "https://jasy.dev" }) verlinkt den ganzen Text.

Sprünge im Dokument

Markieren Sie ein Ziel mit Anchor und zeigen Sie dann mit to statt href darauf. So bauen Sie ein Inhaltsverzeichnis, das wirklich funktioniert.

import { Document, Page, Column, Row, Text, Link, Anchor } from "@jasy/pdf";

const doc = Document([
  Page([
    Column([
      Text("Contents", { size: 22, bold: true }),
      Link({ to: "install" }, Row({ justify: "between" }, [Text("1. Installation"), Text("jump")])),
    ]),
  ]),
  Page([Anchor({ name: "install" }, Text("1. Installation", { size: 22, bold: true }))]),
]);

to funktioniert auch an einem span, für ein „zurück nach oben“ mitten im Satz. Ein Link nimmt genau eines von href oder to; beides oder keines wirft einen Fehler.

Der Anchor darf auf einer Seite liegen, die noch nicht gerendert wurde - jasy löst ihn am Ende über den Namen auf, um Verweise nach vorn müssen Sie sich also keine Gedanken machen.

Vorsicht mit dem Wort: Anchor ist hier ein Sprungziel. Das hat nichts mit dem Anchoring über h / v eines Positioned-Kindes zu tun, bei der es um die Platzierung geht.

Bookmarks

Bookmark fügt einen Eintrag in den Outline-Baum ein - die Leiste, die Ihr Viewer neben der Seite öffnet. level verschachtelt ihn, Kapitel und ihre Abschnitte bilden also einen aufklappbaren Baum.

Bookmark({ title: "2. Installation", level: 1 }, Text("2. Installation", { size: 22, bold: true }));
Bookmark(
  { title: "2.1 Requirements", level: 2 },
  Text("2.1 Requirements", { size: 16, bold: true }),
);

Ein Bookmark mit level: 2 hängt unter dem nächsten vorangehenden level: 1. Bookmarks sind für das Layout unsichtbar: Das Kind wird genau so gerendert wie ohne sie.

Eine Überschrift, beide Aufgaben

Eine Kapitelüberschrift soll meist ein Eintrag in der Seitenleiste und ein Sprungziel sein. Verschachteln Sie beides, und sie ist beides:

Bookmark(
  { title: "2. Installation", level: 1 },
  Anchor({ name: "install" }, Text("2. Installation", { size: 22, bold: true })),
);

Das Handbuch im Showroom zeigt alles in einem Dokument: ein klickbares Inhaltsverzeichnis, einen Bookmark-Baum und Links zurück nach oben.