portable-text-serialization

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Portable Text Serialization

Portable Text 序列化

Render Portable Text content across frameworks using the

@portabletext/*

library family. Each library follows the same component-mapping pattern: you provide a

components

object that maps PT node types to framework-specific renderers.

使用

@portabletext/*

系列库在各框架中渲染Portable Text内容。每个库都遵循相同的组件映射模式：你需要提供一个

components

对象，将PT节点类型映射到框架特定的渲染器。

Portable Text Structure (Quick Reference)

Portable Text 结构（快速参考）

PT is an array of blocks. Each block has

_type

, optional

style

children

(spans),

markDefs

listItem

, and

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 come in two forms:

Decorators: string values in
```
marks[]
```
like
```
"strong"
```
,
```
"em"
```
,
```
"underline"
```
,
```
"code"
```
Annotations: keys in
```
marks[]
```
referencing entries in
```
markDefs[]
```
(e.g., links, internal references)

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[]
```
中的条目（例如链接、内部引用）

Component Mapping Pattern (All Frameworks)

组件映射模式（全框架通用）

Every

@portabletext/*

library accepts a

components

object with these keys:

Key	Renders	Props/Data
`types`	Custom block/inline types (image, code, CTA)	`value` (the block data)
`marks`	Decorators + annotations	`children` + `value` (mark data)
`block`	Block styles (h1, normal, blockquote)	`children`
`list`	List wrappers (ul, ol)	`children`
`listItem`	List items	`children`
`hardBreak`	Line breaks within a block	—

所有

@portabletext/*

库都接受一个带有以下键的

components

对象：

键	渲染内容	属性/数据
`types`	自定义块/内联类型（图片、代码、CTA）	`value` （块数据）
`marks`	装饰器 + 注解	`children` + `value` （标记数据）
`block`	块样式（h1、普通文本、块引用）	`children`
`list`	列表容器（ul、ol）	`children`
`listItem`	列表项	`children`
`hardBreak`	块内换行符	—

Framework-Specific Rules

框架特定规则

Read the rule file matching your framework:

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 (server-side):
```
rules/html.md
```
—
```
@portabletext/to-html
```
Markdown:
```
rules/markdown.md
```
—
```
@portabletext/markdown
```

Plain text extraction:

rules/plain-text.md

—

@portabletext/toolkit

请阅读与你使用的框架匹配的规则文件：

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

Additional Community Serializers

其他社区序列化器

These are listed on portabletext.org but don't have dedicated rule files:

Target	Package
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 class)
Python	`portabletext-html`
C# / .NET	`dotnet-portable-text`
Dart / Flutter	`flutter_sanity_portable_text`

这些序列化器在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`

Common Patterns (All Frameworks)

通用模式（全框架通用）

Custom Types Need Explicit Components

自定义类型需要显式组件映射

PT renderers only handle standard blocks by default. Custom types (

image

code

callToAction

, etc.) require explicit component mappings — they won't render otherwise.

PT渲染器默认仅处理标准块。自定义类型（

image

、

code

、

callToAction

等）需要显式的组件映射，否则无法渲染。

Keep Components Object Stable

保持components对象稳定

In React/Vue, define

components

outside the render function or memoize it. Recreating on every render causes unnecessary re-renders.

在React/Vue中，将

components

定义在渲染函数外部或进行memoize处理。每次渲染时重新创建该对象会导致不必要的重渲染。

Handle Missing Components Gracefully

优雅处理缺失的组件

All libraries accept

onMissingComponent

to control behavior when encountering unknown types:

```
false
```
— suppress warnings
Custom function — log or report

所有库都支持

onMissingComponent

选项，用于控制遇到未知类型时的行为：

```
false
```
— 抑制警告
自定义函数 — 记录或上报问题

Querying PT with GROQ

使用GROQ查询PT内容

Always expand references inside custom blocks:

groq

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

请始终展开自定义块内的引用：

groq

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