Portable Text シリアライゼーション

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

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 つの形式があります：

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

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

すべての @portabletext/* ライブラリは、以下のキーを持つ components オブジェクトを受け入れます：

キー	レンダリング対象	プロップ/データ
types	カスタムブロック/インラインタイプ（image、code、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
    }
  }
}