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-Block-Set abgedeckt wird. Sandboxed Plugins können die Bearbeitungs-UI für diese Blöcke deklarieren (mit 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 natives Plugin erfordert.

Wenn Ihr Plugin nur Editor-seitige Felder 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 bereitstellen soll, müssen Sie nativ sein.

Blocktypen deklarieren

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 — Blocktypname (verwendet in Portable Text _type).
• label — Anzeigename im Slash-Befehlsmenü 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 Exportname 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 fusioniert Plugin-Block-Komponenten automatisch in <PortableText> — Website-Autoren müssen nichts importieren. Benutzerdefinierte Komponenten (deklariert in der components-Prop von <PortableText> der Website) haben Vorrang vor Plugin-Standardwerten.

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 bietet, ist das übliche Muster:

1. Versenden Sie das sandboxed Plugin (nur Bearbeitungsfelder) auf dem Marketplace.
2. Versenden Sie ein separates natives Begleitpaket auf npm, das die Astro-Rendering-Komponenten bereitstellt.
3. Dokumentieren Sie beides: Endbenutzer installieren das sandboxed Plugin vom Marketplace und verwenden npm install für das Begleitpaket zum Rendern.

Dies tauscht eine Ein-Schritt-Installation gegen das Sandboxed-Halten der Editor-Seite. Die meisten Plugin-Autoren ziehen es vor, einfach nativ zu werden, wenn Block-Rendering involviert ist — aber die Option besteht.