portable-text-serialization

可移植文本序列化

使用 @portabletext/* 库系列，在各种框架中渲染可移植文本内容。每个库都遵循相同的组件映射模式：提供一个 components 对象，将 PT 节点类型映射到对应框架的渲染器。

可移植文本结构（快速参考）

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

标记分为两种：

• 装饰符：marks[] 中的字符串值，如 "strong"、"em"、"underline"、"code"
• 注释：marks[] 中引用 markDefs[] 条目的键（例如，链接、内部引用）

组件映射模式（所有框架）

每个 @portabletext/* 库都接受一个包含以下键的 components 对象：

键	渲染内容	属性/数据
types	自定义块/行内类型（图像、代码、CTA）	value（块数据）
marks	装饰符 + 注释	children + value（标记数据）
block	块样式（h1、普通、引用块）	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
    }
  }
}