Portable Text Rendering-Komponenten

Plugins können benutzerdefinierte Blocktypen zum Portable Text Editor hinzufügen — YouTube-Einbettungen, Code-Snippets, Bildergalerien, alles, was nicht vom Standard-Blockset abgedeckt wird. Sandboxed Plugins können die Bearbeitungsoberfläche für diese Blöcke deklarieren (unter Verwendung von Block Kit-Feldern), aber die Astro-Komponenten, die sie auf der öffentlichen Website rendern, müssen zur Build-Zeit von npm geladen werden. Das ist der Teil, der ein Native Plugin erfordert.

Wenn Ihr Plugin nur Felder auf der Bearbeitungsseite benötigt und jemand anderes die Rendering-Komponenten bereitstellt (oder die Website sie lokal bereitstellt), können Sie sandboxed bleiben. Wenn das Plugin auch die Rendering-Komponenten ausliefern soll, müssen Sie native sein.

Deklarieren von Blocktypen

Sowohl Sandboxed als auch Native Plugins können Blocktypen deklarieren. Native Plugins tun dies innerhalb von definePlugin() unter admin.portableTextBlocks:

admin: {
	portableTextBlocks: [
		{
			type: "youtube",
			label: "YouTube Video",
			icon: "video",                       // video, code, link, link-external
			placeholder: "Paste YouTube URL...",
			fields: [                            // Block Kit fields for the editing UI
				{ type: "text_input", action_id: "id", label: "YouTube URL" },
				{ type: "text_input", action_id: "title", label: "Title" },
				{ type: "text_input", action_id: "poster", label: "Poster Image URL" },
			],
		},
	],
},

Jeder Blocktyp definiert:

• type — Blocktyp-Name (verwendet in Portable Text _type).
• label — Anzeigename im Slash-Command-Menü des Editors.
• icon — video, code, link oder link-external. Fällt auf einen generischen Würfel zurück.
• placeholder — Eingabe-Platzhaltertext.
• fields — Block Kit-Formularfelder zur Bearbeitung. Wenn weggelassen, wird eine einfache URL-Eingabe angezeigt.

Rendering auf der öffentlichen Website

Um Blocktypen auf der öffentlichen Website zu rendern, exportieren Sie Astro-Komponenten aus einem componentsEntry. Der Export-Name muss blockComponents sein:

import YouTube from "./YouTube.astro";
import CodePen from "./CodePen.astro";

export const blockComponents = {
	youtube: YouTube,
	codepen: CodePen,
};

Setzen Sie componentsEntry auf dem Descriptor:

export function myPlugin(): PluginDescriptor {
	return {
		id: "embeds",
		version: "1.0.0",
		format: "native",
		entrypoint: "@my-org/embeds",
		componentsEntry: "@my-org/embeds/astro",
	};
}

EmDash fügt Plugin-Block-Komponenten automatisch in <PortableText> ein — Website-Autoren müssen nichts importieren. Vom Benutzer bereitgestellte Komponenten (deklariert in der components-Prop der Website auf <PortableText>) haben Vorrang vor Plugin-Defaults.

Package-Exporte

Fügen Sie den ./astro-Export zu package.json hinzu:

{
	"exports": {
		".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
		"./admin": { "types": "./dist/admin.d.ts", "import": "./dist/admin.js" },
		"./astro": { "types": "./dist/astro/index.d.ts", "import": "./dist/astro/index.js" }
	}
}

Der ./astro-Export ist serverseitig (Astro SSR), der ./admin-Export ist browserseitig (React), und der "."-Export ist der Descriptor + createPlugin. Halten Sie sie in separaten Dateien, da sie für verschiedene Umgebungen gebündelt werden.

Sandbox-freundliche Varianten

Wenn Sie möchten, dass ein Plugin sandboxed ist, aber dennoch eine Standard-Rendering-Erfahrung bereitstellt, ist das übliche Muster:

1. Liefern Sie das Sandboxed Plugin (nur Bearbeitungsfelder) auf dem Marketplace aus.
2. Liefern Sie ein separates Begleit-Native-Package auf npm aus, das die Astro-Rendering-Komponenten bereitstellt.
3. Dokumentieren Sie beides: Endbenutzer installieren das Sandboxed Plugin vom Marketplace und führen npm install für das Begleit-Package zum Rendern aus.

Dies tauscht eine Ein-Schritt-Installation gegen das Beibehalten der Editor-Seite als sandboxed. Vollständig native zu werden ist einfacher, wenn Block-Rendering involviert ist, aber diese Aufteilung bleibt eine Option.