在任意前端框架中渲染与序列化 Portable Text…

当你需要把 Portable Text（PT）内容渲染到前端框架、转成 HTML/Markdown 字符串或提取纯文本时使用。

适用场景

解决思路

1. 使用 @portabletext/* 系列库，每个库都遵循同一套组件映射模式：传入一个 components 对象，把 PT 节点类型映射到对应框架的渲染器。
2. 理解 PT 结构：PT 是一个 block 数组，每个 block 含 _type、可选的 style、children（span 数组）、markDefs、listItem 和 level；span 形如 { _type: "span", text: "...", marks: [...] }。
3. 区分两种 marks：Decorators 是 marks[] 中的字符串值（如 "strong"、"em"、"underline"、"code"）；Annotations 是 marks[] 中引用 markDefs[] 条目的 key（如链接、内部引用）。
4. 在 components 对象中按以下键提供渲染器：types（自定义块/内联类型，如 image、code、CTA，接收 value）、marks（装饰器与注解，接收 children 与 value）、block（块样式如 h1、normal、blockquote，接收 children）、list（列表包裹元素 ul/ol，接收 children）、listItem（列表项，接收 children）、hardBreak（块内换行）。
5. 按框架选择对应库：React/Next.js 用 @portabletext/react 或 next-sanity；Svelte/SvelteKit 用 @portabletext/svelte；Vue/Nuxt 用 @portabletext/vue；Astro 用 astro-portabletext；服务端 HTML 用 @portabletext/to-html；Markdown 用 @portabletext/markdown；纯文本提取用 @portabletext/toolkit。
6. 如需其他目标平台，可选用社区序列化器：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。
7. 为自定义类型显式提供组件：PT 渲染器默认只处理标准块，自定义类型（image、code、callToAction 等）必须显式映射，否则不会渲染。
8. 保持 components 对象稳定：在 React/Vue 中把 components 定义在渲染函数之外或进行 memoize，避免每次渲染都重建导致不必要的重渲染。
9. 优雅处理缺失组件：所有库都接受 onMissingComponent 来控制遇到未知类型时的行为——传 false 可抑制警告，或传自定义函数进行日志/上报。
10. 用 GROQ 查询 PT 时始终展开自定义块内的引用，例如：body[]{ ..., _type == "image" => { ..., asset-> }, markDefs[]{ ..., _type == "internalLink" => { ..., "slug": @.reference->slug.current } } }。