Portable Textレンダリングコンポーネント

このページで分かること

プラグインが定義するPortable Textのブロックは、編集画面用の定義と公開サイト用のAstroコンポーネントの2つからなること
admin.portableTextBlocks でのブロックの定義と、各項目の働き
Astroコンポーネントの作成と登録（blockComponents、componentsEntry）、描画コンポーネントの優先順位とサイト側での上書き

難易度: 上級
読む時間: 3分
前提知識: はじめてのネイティブ型プラグイン／Astroとは

このページの目次

プラグインが定義するPortable Textのブロックは、2つの部分からなります。

宣言的なブロックの定義は、ブロックを挿入・編集する方法をEmDashのエディターに伝えます。
Astroコンポーネントは、保存されたブロックを公開サイトで描画します。

ブロックの定義は共通のプラグインのランタイムを使い、サンドボックス型プラグインでも使えます。パッケージからAstroコンポーネントを読み込むには、ネイティブ型のディスクリプターが必要です。Astroがホストのサイトをビルドするときに、そのコンポーネントをインポートする必要があるためです。

本サイトの補足

やさしい解説

公式の対応表では、WordPressの the_content() は、EmDashの <PortableText /> にあたります。プラグインで独自のブロックを作る場合、エディターでの入力項目は admin.portableTextBlocks に宣言し、公開サイトでの見た目はAstroコンポーネントで作ります。入力項目の宣言はただのデータなのでサンドボックス型でも書けますが、Astroコンポーネントはサイトのビルド時に読み込む必要があるため、ネイティブ型でしか提供できません。

エディター用のブロックの定義

definePlugin() の中の admin.portableTextBlocks で、ブロックを宣言します。次の定義は、見出し、本文、トーンを持つコールアウトを追加します。

src/index.ts

return definePlugin({
	id: "plugin-callout",
	version: "0.1.0",
	admin: {
		portableTextBlocks: [
			{
				type: "callout",
				label: "Callout",
				icon: "info",
				description: "Highlight supporting information",
				category: "Sections",
				fields: [
					{
						type: "text_input",
						action_id: "heading",
						label: "Heading",
					},
					{
						type: "text_input",
						action_id: "body",
						label: "Body",
						multiline: true,
					},
					{
						type: "select",
						action_id: "tone",
						label: "Tone",
						options: [
							{ value: "note", label: "Note" },
							{ value: "warning", label: "Warning" },
						],
						initial_value: "note",
					},
				],
			},
		],
	},
});

ブロックのフィールドは、スラッシュメニューと編集ダイアログでのブロックの表示を制御します。

フィールド	必須	動作
`type`	はい	保存されるPortable Textのブロックの `_type` と、描画コンポーネントの対応表のキーになる。有効なプラグイン全体で一意にする。
`label`	はい	エディターでのブロックの名前。
`icon`	いいえ	一致するものがあれば、エディターが対応しているアイコンのキーを使う。ない場合、エディターは汎用のブロックのアイコンを表示する。
`description`	いいえ	スラッシュメニューに補足のテキストを追加する。
`category`	いいえ	スラッシュメニューでブロックをグループにまとめる。デフォルトのカテゴリーは `Embeds`。
`placeholder`	いいえ	`fields` を省略したときの、シンプルなURL入力欄のプレースホルダーを設定する。
`fields`	いいえ	シンプルなURL入力欄を、Block Kitのフォーム要素に置き換える。それぞれの `action_id` が、保存されるブロックのプロパティになる。

fields には、Block Kitで説明しているBlock Kitの要素の形を使います。この例では、次の値のような形のブロックが保存されます。

{
	"_type": "callout",
	"_key": "01JEXAMPLEKEY",
	"heading": "Before you publish",
	"body": "Check the preview on a small screen.",
	"tone": "warning"
}

Astroコンポーネントの追加

保存されたブロックを node として受け取るAstroコンポーネントを作成します。
src/astro/Callout.astro
```
---
interface CalloutNode {
 _type: "callout";
 _key: string;
 heading?: string;
 body?: string;
 tone?: "note" | "warning";
}

interface Props {
 node: CalloutNode;
}

const { node } = Astro.props;
---

<aside class:list={["callout", `callout--${node.tone ?? "note"}`]}>
 {node.heading && {node.heading}}
 {node.body && {node.body}}
</aside>
```
astro-portabletext は、独自のタイプのコンポーネントに node プロパティを渡します。ブロックを value として渡すことはありません。この描画コンポーネントでは、省略可能な見出しに、スタイルを付けたテキストを使っています。ブロックはドキュメントのどの深さにも現れる可能性があるため、見出しの要素を固定すると、見出しのレベルが飛んだり重複したりする場合があるためです。
blockComponents という名前の対応表で、コンポーネントをエクスポートします。
src/astro/index.ts
```
import Callout from "./Callout.astro";

export const blockComponents = {
    callout: Callout,
};
```
各キーは、ブロックの定義の type と一致している必要があります。

ディスクリプターのファクトリーに componentsEntry を追加します。

src/index.ts

export function calloutPlugin(): PluginDescriptor {
    return {
        id: "plugin-callout",
        version: "0.1.0",
        format: "native",
        entrypoint: "@example/plugin-callout",
        componentsEntry: "@example/plugin-callout/astro",
    };
}

npmパッケージから ./astro のエントリーをエクスポートします。このエントリーは、blockComponents をエクスポートするモジュールを指している必要があります。パッケージの完全な定義は、ネイティブ型プラグインの配布にあります。

描画の優先順位と上書き

EmDashは、プラグインのコンポーネントを自動的に <PortableText> コンポーネントに追加します。コンポーネントは、次の順に統合されます。

EmDashの組み込みのコンポーネント
プラグインの blockComponents
サイトが <PortableText> に渡したコンポーネント

同じタイプのキーを持つものは、後のものが前のものを上書きします。そのため、サイトは、プラグインのエディター用の定義を有効にしたまま、コールアウトの描画コンポーネントだけを置き換えられます。

src/pages/article.astro

---
import { PortableText } from "emdash/ui";
import SiteCallout from "../components/SiteCallout.astro";
---

<PortableText
	value={entry.body}
	components={{
		type: {
			callout: SiteCallout,
		},
	}}
/>

本サイトの補足 · AIへの依頼文

AIに聞いてみよう

目的：ネイティブ型プラグインで、独自のPortable Textのブロックと、公開サイトで描画するAstroコンポーネントを作る

EmDashの公式ドキュメント「Portable Text rendering components」
（https://docs.emdashcms.com/plugins/creating-native-plugins/portable-text-components/）をもとに、
自分のネイティブ型プラグインに独自のブロックを追加したいです。

作りたいブロック：
・（例：見出しと本文を持つ注意書きのブロック）
・現在の src/index.ts：（内容を貼る）

条件：
・admin.portableTextBlocks でのブロックの定義、Astroコンポーネント、blockComponents の対応表、ディスクリプターの componentsEntry、package.json の ./astro のエクスポートをそろえて示す
・fields にはページで案内されているBlock Kitの要素だけを使う
・Astroコンポーネントは、ブロックを value ではなく node として受け取る

回答する前に、必ず公式ドキュメントの現在の内容を確認してください。
EmDash Docs MCP（https://docs.emdashcms.com/mcp）が使える場合は、それで確認してください。

自分で確認すること

ブロックの定義の type と、blockComponents のキーが同じになっている
エディターのスラッシュメニューに、追加したブロックが表示される
ブロックを入れて公開したページで、Astroコンポーネントによる表示になっている

訳の誤りを報告する