tiptap内容序列化：HTML、JSON、Markdown转换详解

2026-02-05 04:23:27作者：余洋婵Anita

在现代富文本编辑应用中，内容的序列化与反序列化是连接编辑器与数据存储、展示的核心环节。tiptap作为面向Web开发者的无头编辑器框架（headless editor framework），提供了灵活的内容转换机制，支持HTML、JSON和Markdown等多种格式的相互转换。本文将详细解析tiptap的内容序列化原理及实操方法，帮助开发者高效处理富文本数据流转。

HTML与JSON的双向转换

tiptap的内容转换核心能力由@tiptap/html包提供，该模块实现了ProseMirror文档模型与HTML/JSON格式的相互映射。其核心转换逻辑定义在packages/html/src/index.ts中，通过generateHTML和generateJSON两个主要函数暴露转换接口。

HTML生成：从JSON到可视化标记

generateHTML函数接收ProseMirror JSON格式内容和扩展配置，输出对应的HTML字符串。其实现逻辑位于packages/html/src/generateHTML.ts，关键步骤包括：

** schema构建 **：基于传入的extensions创建文档模型 schema
**节点转换 **：使用Node.fromJSON()将JSON内容转换为ProseMirror节点
HTML片段生成：通过getHTMLFromFragment将节点树转换为HTML标记

以下是基础使用示例：

import { generateHTML } from '@tiptap/html'
import StarterKit from '@tiptap/starter-kit'

const jsonContent = {
  type: 'doc',
  content: [
    {
      type: 'paragraph',
      content: [
        { type: 'text', text: 'Hello tiptap!' }
      ]
    }
  ]
}

// 生成HTML字符串
const html = generateHTML(jsonContent, [StarterKit])
// 输出: <p>Hello tiptap!</p>

JSON解析：从HTML到结构化数据

generateJSON函数则实现反向转换，将HTML字符串解析为ProseMirror JSON格式。其核心逻辑包括：

DOM解析：使用浏览器原生DOMParser解析HTML字符串
内容提取：从解析后的DOM树中提取内容节点
JSON序列化：通过ProseMirror的DOMParser将DOM节点转换为JSON结构

使用示例：

import { generateJSON } from '@tiptap/html'
import StarterKit from '@tiptap/starter-kit'

const html = '<p><strong>tiptap</strong> is awesome!</p>'

// 解析HTML为JSON
const json = generateJSON(html, [StarterKit])
// 输出JSON结构包含paragraph和text节点

Markdown格式支持

tiptap通过@tiptap/pm/markdown模块提供Markdown格式的转换能力。虽然具体实现文件路径需要进一步确认，但该模块通常包含markdownit等解析器的集成代码，实现ProseMirror文档与Markdown格式的双向转换。

Markdown转换核心流程

Markdown转换通常涉及以下步骤：

语法解析：使用markdown解析器将文本转换为AST
节点映射：将Markdown AST节点映射为ProseMirror节点
文档构建：基于映射结果构建ProseMirror文档模型

基础使用示例

import { Markdown } from '@tiptap/pm/markdown'
import StarterKit from '@tiptap/starter-kit'

// Markdown转JSON
const json = Markdown.parse('# Hello tiptap', [StarterKit])

// JSON转Markdown
const markdown = Markdown.serialize(json, [StarterKit])

实战应用与注意事项

环境适配处理

@tiptap/html模块默认依赖浏览器环境的DOM API，在Node.js环境使用时需导入服务端专用模块：

// 服务端环境使用
import { generateHTML } from '@tiptap/html/server'

这一环境检测逻辑在packages/html/src/generateHTML.ts中实现，通过检查window对象是否存在来区分运行环境。

扩展与自定义转换规则

当使用自定义节点或标记时，需要在转换过程中提供相应的schema定义。例如添加表格扩展后，HTML转换会自动支持<table>相关标签的生成与解析：

import { generateHTML } from '@tiptap/html'
import StarterKit from '@tiptap/starter-kit'
import Table from '@tiptap/extension-table'
import TableRow from '@tiptap/extension-table-row'
import TableCell from '@tiptap/extension-table-cell'

// 支持表格转换
const html = generateHTML(jsonContent, [
  StarterKit,
  Table,
  TableRow,
  TableCell
])