Zum Inhalt springen

Canvas

Canvas bietet eine herausgezoomte, Figma-ähnliche Übersicht aller von Blockstudio verwalteten Seiten. Jede Seite erscheint als Live-Iframe-Artboard in einer einzigen horizontalen Reihe. Verschiebe die Ansicht mit dem Trackpad und zoome mit einer Pinch-Geste oder Strg+Scrollen.

Aktivierung

Canvas ist als verborgene Admin-Seite verfügbar. Navigiere zu:

Code
/wp-admin/admin.php?page=blockstudio-canvas

Die Seite ist nur zugänglich, wenn dev.canvas.enabled true ist und der aktuelle Benutzer über die Berechtigung edit_posts verfügt.

Einstellungen

Aktiviere Canvas und konfiguriere sein Verhalten in der blockstudio.json deines Themes:

JSON
{
  "dev": {
    "canvas": {
      "enabled": true,
      "adminBar": false
    }
  }
}
Eigenschaft Typ Standard Beschreibung
enabled boolean false Aktiviert die Canvas-Funktion.
adminBar boolean true Zeigt die Admin-Leiste von WordPress in Artboard-Iframes an. Setze den Wert auf false, um eine aufgeräumtere Vorschau zu erhalten.

Beide Einstellungen sind auch als Filter verfügbar:

PHP
add_filter('blockstudio/settings/dev/canvas/enabled', '__return_true');
add_filter('blockstudio/settings/dev/canvas/admin_bar', '__return_false');

Ansichten

Wechsle über das Dropdown-Menü oben rechts zwischen den Ansichten.

  • Seiten: Alle von Blockstudio verwalteten Seiten als vollbreite Artboards in einer einzigen Reihe.
  • Blöcke: Alle registrierten Blockstudio-Blöcke in einem Raster, jeweils mit den Standardwerten ihrer Attribute gerendert.

Öffentliches Inhaltsverzeichnis und DokumentAPI

Canvas stellt einen versionierten, verbraucherneutralen PHP-Vertrag für Tools bereit, die dieselben registrierten Inhalte benötigen, ohne die Erkennungs- oder Rendering-Logik von Blockstudio neu aufzubauen:

PHP
use Blockstudio\Canvas;

$all = Canvas::inventory();

$changed = Canvas::inventory([
  'blocks' => ['theme/hero'],
  'pages' => ['about'],
]);

$documents = Canvas::documents([
  'patterns' => ['theme/featured'],
  'templates' => ['front-page'],
]);

Die aktuelle Version ist unter Canvas::SCHEMA_VERSION verfügbar. Ergebnisse des Inhaltsverzeichnisses enthalten:

  • inventory: normalisierte pages, blocks, patterns, templates, parts und Beispiele öffentlicher ui-Familien
  • order: die stabile, typübergreifende Anzeigereihenfolge
  • sources: genaue ausgewählte Quellpfade mit Herkunftsinformationen für jeden Eintrag; die source eines Seiteneintrags ist seine stabile Quellidentität, während path der physische Rendering-Vorlagenpfad ist
  • warnings und errors: strukturierte Probleme statt ausgegebener Inhalte
  • deleted: angeforderte Kennungen, die nicht mehr existieren
  • selection: die normalisierte Auswahl und die Angabe, ob sie gezielt war

Canvas::documents() fügt für jeden ausgewählten Eintrag ein vollständiges Render-Dokument hinzu. Jedes Dokument enthält seinen Inhalt, zusammengesetztes HTML, Namen der abhängigen Blöcke und die exakten CSS, JavaScript, Module, Interaktivitäts-Bootstrap, gebündelten UI-Globals und die Tailwind-Ausgabe. Seitendokumente verwenden einen semantischen <main>-Inhaltscontainer. Aufrufende können ihn über die gemeinsamen Optionen für Render-Dokumente überschreiben oder deaktivieren. Jede ausgewählte Seite wird in ihrem eigenen wiederhergestellten Frontend-WordPress-Kontext gerendert. Dadurch beziehen sich Abfragebedingungen, Body-Class-Filter, Shortcodes, Layouts, Weiterleitungen und wp_enqueue_scripts-Callbacks auf diese Seite und nicht auf den Admin- oder REST-Request, der das Canvas-Ergebnis angefordert hat. Vom Aufrufer bereitgestellte Body-Klassen werden mit den kontextbezogenen Klassen der Seite zusammengeführt. Die Enqueue-Registries des Frontends sind zwischen Dokumenten isoliert. Canvas löst diese Lifecycle-Callbacks über ihre öffentlichen WordPress-Funktionsnamen auf. Derselbe Kontext bleibt somit erhalten, wenn Blockstudio über Composer oder einen verlagerten Anwendungs-Namespace geladen wird.

Semantik der exakten Auswahl

Die Auswahl ist strikt:

  • Ohne erkannte Typschlüssel werden alle Typen geladen.
  • Mit true, null oder "*" werden alle Einträge dieses Typs geladen.
  • Ein String oder eine Liste lädt nur exakte IDs, Namen, Slugs, Pfade oder Quellpfade.
  • Ein leerer String, eine leere Liste oder false lädt keine Einträge dieses Typs.
  • Sobald ein Typschlüssel vorhanden ist, werden ausgelassene Typen weder erkannt noch synchronisiert, gerendert oder kompiliert.

So sind Anfragen nur für geänderte Inhalte auch bei großen Projekten sicher. Vorhandene Blöcke und Seiten werden über ihre kanonischen Registries aufgelöst. Wenn bei einer Frontend-Anfrage nur die gespeicherte Seitenprojektion geladen wurde, führt Canvas eine schreibgeschützte Quellerkennung durch und führt passende Beitrags-IDs und Permalinks zusammen, ohne Inhalte zu synchronisieren. Dieselbe Zusammenführung der Identitäten findet statt, wenn eine logische Erkennungsquelle zuerst die quellengestützte Registry befüllt. Das kontextbezogene Rendern der Seite verwendet dann weiterhin den passenden verwalteten Beitrag vom Typ WordPress. Neue Live-Session-Topologien werden nur im Umfeld des geänderten Verzeichnisses erkannt. Ausgewählte Pattern- und Site-Editor-Vorlagenquellen werden erst nach der Auswahl kompiliert.

Der Aktualisierungsendpunkt REST folgt derselben Regel für seine vorhandenen Abfrageparameter blocks und pages. Zum Beispiel gibt ?blocks=theme/hero diesen Block und keine Seiten zurück. Verwende beide Parameter für eine gemischte Antwort. Wird der Endpunkt ohne einen der Parameter aufgerufen, bleibt die vollständige Legacy-Antwort erhalten.

Live-Modus

Der Live-Modus verwendet Server-Sent Events (SSE), um Dateiänderungen zu erkennen und die Canvas-Ansicht in Echtzeit zu aktualisieren. Wenn du eine Blockvorlage, Seitenvorlage oder ein Stylesheet bearbeitest, werden die betroffenen Artboards automatisch innerhalb von etwa einer Sekunde aktualisiert.

Aktiviere den Live-Modus über das Dropdown-Menü. Bei aktivem Modus erscheint eine grüne, pulsierende Anzeige. Die Einstellung bleibt sitzungsübergreifend in localStorage erhalten.

Der Live-Modus verfolgt Änderungen an Dateien vom Typ .php, .json, .css, .scss, .js, .twig und .html in Block- und Seitenverzeichnissen. Bekannte Änderungen aktualisieren nur den zugehörigen registrierten Block oder die Seite. Für einen tatsächlich neuen Block oder eine neue Seite wird ein einzelner Verzeichnisdurchlauf zur Erkennung der Topologie ausgeführt. So lassen sich während einer geöffneten Live-Sitzung weiterhin Inhalte erstellen, ohne andere Quellen erneut zu durchsuchen.

Fokusmodus

Klicke auf eine beliebige Artboard-Beschriftung, um den Fokusmodus zu öffnen. Das ausgewählte Artboard füllt das Ansichtsfenster über die gesamte Breite und lässt sich vertikal scrollen. Drücke Escape oder klicke auf die Schließen-Schaltfläche, um zur Übersicht zurückzukehren.

Steuerelemente

Aktion Eingabe
Verschieben Scrollen / Zwei-Finger-Ziehen auf dem Trackpad
Zoomen Strg+Scrollen oder Pinch-Geste
An Ansicht anpassen Dropdown-Menü
Auf 100 % zoomen Dropdown-Menü
Artboard fokussieren Artboard-Beschriftung anklicken
Fokusmodus beenden Escape / Schließen-Schaltfläche

Sicherheit

Das Canvas-Skript und die Seitendaten werden nur geladen, wenn alle Bedingungen erfüllt sind:

  • Die Einstellung dev.canvas.enabled ist true.
  • Der aktuelle Benutzer verfügt über die Berechtigung edit_posts.

Öffentliche Besucher sehen weder das Canvas-Skript noch Seitenmetadaten.