portable-text-serialization

Portable Text のシリアライズ

@portabletext/* ライブラリファミリーを使用して、さまざまなフレームワークで Portable Text コンテンツをレンダリングします。各ライブラリは同じコンポーネントマッピングパターンに従います。components オブジェクトを指定し、PT ノードの種類をフレームワーク固有のレンダラーにマッピングします。

Portable Text の構造（クイックリファレンス）

PT はブロックの配列です。各ブロックは _type、省略可能な style、children（スパン）、markDefs、listItem、level を持ちます。

Root array
├── block (_type: "block")
│   ├── style: "normal" | "h1" | "h2" | "blockquote" | ...
│   ├── children: [span, span, ...]
│   │   └── span: { _type: "span", text: "...", marks: ["strong", "<markDefKey>"] }
│   ├── markDefs: [{ _key, _type: "link", href: "..." }, ...]
│   ├── listItem: "bullet" | "number" (optional)
│   └── level: 1, 2, 3... (optional, for nested lists)
├── custom block (_type: "image" | "code" | any custom type)
└── ...more blocks

マークには 2 つの形式があります。

• デコレーター："strong"、"em"、"underline"、"code" など、marks[] 内の文字列値
• アノテーション：markDefs[] 内のエントリーを参照する marks[] のキー（リンクや内部参照など）

コンポーネントマッピングパターン（すべてのフレームワーク）

すべての @portabletext/* ライブラリは、次のキーを持つ components オブジェクトを受け取ります。

キー	レンダリング対象	Props／データ
types	カスタムブロック／インライン型（画像、コード、CTA）	value（ブロックデータ）
marks	デコレーター＋アノテーション	children ＋ value（マークデータ）
block	ブロックスタイル（h1、normal、blockquote）	children
list	リストのラッパー（ul、ol）	children
listItem	リスト項目	children
hardBreak	ブロック内の改行	—

フレームワーク固有のルール

お使いのフレームワークに対応するルールファイルを参照してください。

• React／Next.js：rules/react.md — @portabletext/react または next-sanity
• Svelte／SvelteKit：rules/svelte.md — @portabletext/svelte
• Vue／Nuxt：rules/vue.md — @portabletext/vue
• Astro：rules/astro.md — astro-portabletext
• HTML（サーバーサイド）：rules/html.md — @portabletext/to-html
• Markdown：rules/markdown.md — @portabletext/markdown
• プレーンテキストの抽出：rules/plain-text.md — @portabletext/toolkit

コミュニティ製シリアライザー

これらは portabletext.org に掲載されていますが、専用のルールファイルはありません。

対象	パッケージ
React Native	@portabletext/react-native-portabletext
React PDF	@portabletext/react-pdf-portabletext
Solid	solid-portabletext
Qwik	portabletext-qwik
Shopify Liquid	portable-text-to-liquid
PHP	sanity-php（SanityBlockContent クラス）
Python	portabletext-html
C#／.NET	dotnet-portable-text
Dart／Flutter	flutter_sanity_portable_text

共通パターン（すべてのフレームワーク）

カスタム型には明示的なコンポーネントが必要です

PT レンダラーは、デフォルトでは標準ブロックのみを処理します。カスタム型（image、code、callToAction など）をレンダリングするには、コンポーネントのマッピングを明示的に指定する必要があります。指定しない場合はレンダリングされません。

コンポーネントオブジェクトを安定させる

React／Vue では、components をレンダリング関数の外で定義するか、メモ化してください。レンダリングのたびに再作成すると、不要な再レンダリングが発生します。

コンポーネントが見つからない場合に適切に処理する

すべてのライブラリは、未知の型に遭遇したときの動作を制御する onMissingComponent を受け取ります。

• false — 警告を抑制します
• カスタム関数 — ログを記録するか、報告します

GROQ で PT をクエリする

カスタムブロック内の参照は、必ず展開してください。

body[]{
  ...,
  _type == "image" => {
    ...,
    asset->
  },
  markDefs[]{
    ...,
    _type == "internalLink" => {
      ...,
      "slug": @.reference->slug.current
    }
  }
}