# @contentstack/json-rte-serializer 中文文档
规范地址：https://npmcn.com/package/%40contentstack/json-rte-serializer/
版本：3\.1\.0
npm 元数据更新时间：2026-05-18T11:26:47.625Z
中文译文更新时间：2026-11-10T16:45:39.770Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40contentstack/json-rte-serializer
原文对照：https://npmcn.com/package/%40contentstack/json-rte-serializer/?lang=original
项目主页：https://github.com/contentstack/json-rte-serializer#readme
源码仓库：https://github.com/contentstack/json-rte-serializer
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：538 kB，13 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：12 个
- 首次发布：2021-07-07T07:11:48.586Z
- 最新版本发布：2026-05-18T11:26:47.479Z
- 近 30 天下载量：77514（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 2 个）
## 中文简介
此套件将 Html 文档转换为 Json 并反之 .
## 安装
```sh
npm install @contentstack/json-rte-serializer
```
也可以使用：`pnpm add @contentstack/json-rte-serializer`、`yarn add @contentstack/json-rte-serializer`、`bun add @contentstack/json-rte-serializer`
## README
# JSON RTE 序列器
内容tack是一种无头的CMS,采用API-First方法. 这是一个CMS,开发者可以用来用他们最喜爱的语言来构建强大的跨平台应用程序. 构建您的应用程序前端, 而Contack 将照顾其余的 . [更多信息](https://www.contentstack.com/docs/)。 。 。 .
JSON RTE 序列器软件包协助在 JSON 格式和 HTML 格式之间转换您 JSON 丰富的文本编辑器字段内的内容。 这意味着您可以轻松地将您的数据从JSON格式更改为HTML格式,用于显示目的,反之亦然,用于数据存储或处理. 如果你需要将JSON转换为Markdown格式,我们提供Markdown序列器功能. 这个功能专门设计将您的JSON数据转换为Markdown,使得使用Markdown的平台更容易处理文本格式化.
# 安装
要使用基于Node.js的应用程序的 JSON RTE 序列器,您需要下列先决条件:
- 节点.js 10或以后
安装 `json-rte-serializer` 使用下列命令通过 npm 软件包 :
```bash
npm install @contentstack/json-rte-serializer
```
# JSON RTE 序列器使用大小写
让我们看看几个代码样本,显示我们如何将JSON格式中的数据转换为HTML,反之亦然.
## 标准转换
对于标准转换方案,JSON RTE 序列器只支持JSON Rich Text编辑器领域中可用的标准标记. 要使用自定义标签,您可以遵循 [自定义转换](https://npmcn.com/package/%40contentstack/json-rte-serializer/#readme-custom-conversion) 实例如下.
### JSON 到 HTML 转换代码
您可以使用以下 JSON RTE 序列器代码来将您的 JSON RTE 字段数据转换为 HTML 格式.
```javascript
import { jsonToHtml } from "@contentstack/json-rte-serializer";
const htmlValue = jsonToHtml({
type: "doc",
attrs: {},
uid: "547a479c68824767ce1d9725852f042b",
children: [
{
uid: "767a479c6882471d9725852f042b67ce",
type: "p",
attrs: {},
children: [{ text: "This is HTML-formatted content." }],
},
],
});
console.log(htmlValue);
```
### 转换结果
由此产生的HTML数据如下:
```HTML
This is HTML-formatted content.
```
### HTML 到 JSON 转换码
您可以使用以下 JSON RTE 序列器代码来将 HTML 字段数据转换为 JSON 格式.
```javascript
import { htmlToJson } from "@contentstack/json-rte-serializer";
const htmlDomBody = new DOMParser().parseFromString(
"This is HTML-formatted content.
",
"text/html"
).body;
const jsonValue = htmlToJson(htmlDomBody);
console.log(jsonValue);
```
> **_说明:_** 上面的代码片段只为JavaScript驱动的前端网站工作.
对于基于Node.js的应用程序,您可以使用以下代码:
```javascript
const { htmlToJson } = require("@contentstack/json-rte-serializer")
const {JSDOM} = require('jsdom')
const dom = new JSDOM("This is HTML-formatted content.
")
let htmlDoc = dom.window.document.querySelector('body')
const jsonValue = htmlToJson(htmlDoc)
console.log(jsonValue);
```
### 转换结果
由此产生的JSON格式数据如下:
```JSON
{
"type":"doc",
"attrs":{},
"uid":"547a479c68824767ce1d9725852f042b",
"children":[{
"uid":"767a479c6882471d9725852f042b67ce",
"type": "p",
"attrs":{},
"children" : [{"text": "This is HTML-formatted content."}]
}]
}
```
### JSON 到 Markdown 转换码
您可以使用以下 JSON RTE 序列器代码来将您的 JSON RTE 字段数据转换为 Markdown 格式.
```javascript
import { jsonToMarkdown } from "@contentstack/json-rte-serializer";
const markdownValue = jsonToHtml({
type: "doc",
attrs: {},
uid: "547a479c68824767ce1d9725852f042b",
children: [
{
uid: "767a479c6882471d9725852f042b67ce",
type: "p",
attrs: {},
children: [
{ text: "This is Markdown-formatted content which has some " },
{ text: "BOLD", bold: true },
{ text: " text and some "},
{ text: "Italic", italic: true },
{ text: " text."}
]
},
],
});
console.log(markdownValue);
```
### 转换结果
由此产生的Markdown数据如下:
```MARKDOWN
This is Markdown-formatted content which has some **BOLD** text and some *Italic* text.
```
## 自定义转换
对于定制的转换方案,您可以自定义您的 JSON RTE 序列器代码,允许在 JSON 富文本编辑器域中支持额外的标记或元素类型. 通过一个 `options` 字段(可选) `jsonToHtml` 或者说 `htmlToJson` 方法来按照您的要求操纵 JSON RTE 序列器包的工作.
### 将 JSON 转换为 HTML
您可以通过一个自定义解析器方法,将上面提到的 JSON 元素类型(例如:社会嵌入)的数据转换为 HTML 格式. 在解析的选项中 `customElementTypes` 对象解析块级和内含元素(例如信息面板),而 `customTextWrapper` 对象解析文本格式元素(如粗体、斜体、字体颜色等)。 这些选项将选择一个对象,其密钥是元素类型,而值是该类型将执行的解析函数.
这个 `customElementTypes` parser 函数提供以下参数:
- `attrs`: 向节点传递的属性
- `child`: 当前节点的嵌入元素
- `jsonBlock`: 目前正在解析的全部 JSON 对象
另一方面 `customTextWrapper` parser 函数提供以下参数:
- `child`: 指定子元素的 HTML 字符串
- `value`: 与儿童因素相对的数值
* * *
`allowedEmptyAttributes`
- 类型 : `object`
- 默认 : `{ img: ['alt'], reference: ['alt'] }`
指定在 jsonToHtml 转换时要为特定的 HTML 元素保留哪些空属性. 默认情况下,转换器会为 和引用(资产)元素,即使其值为空. 这对确保语义正确性和无障碍性特别有用.
在转换过程中想要保留带有空值的特定属性时使用此选项.
* * *
`addNbspForEmptyBlocks`
- 类型 : `boolean`
- 默认 :`false`
设置为正则时, 此选项会在 jsonToHtml 转换过程中为空块添加一个非破解空间( nbsp;) 。 这有助于维持HTML输出的视觉结构——特别是有助于在可编辑的内容或内容编辑器中保持间隔.
您可以使用以下定制的 JSON RTE 序列器代码来将您的 JSON RTE 字段数据转换为 HTML 格式.
```javascript
import { jsonToHtml } from "@contentstack/json-rte-serializer";
const jsonValue = {
type: "doc",
uid: "cfe8176d1ca04cc0b42f60b3047f611d",
attrs: {},
children: [
{
type: "p",
attrs: {},
uid: "6eae3c5bd7624bf39966c855543d954b",
children: [
{
type: "social-embed",
attrs: {
url: "https://twitter.com/Contentstack/status/1508911909038436365?cxt=HHwWmsC9-d_Y3fApAAAA",
style: {},
"redactor-attributes": {
url: "https://twitter.com/Contentstack/status/1508911909038436365?cxt=HHwWmsC9-d_Y3fApAAAA",
},
},
uid: "8d8482d852b84822a9b66e55ffd0e57c",
children: [{ text: "" }],
},
],
},
{
"type": "p",
"uid": "28c837c127504d3c85b9cb6d7099cb0b",
"attrs": {},
"children": [
{
"text": ""
}
]
},
{
type: "p",
attrs: {},
uid: "54a7340da87846dda28aaf622069559a",
children: [
{ text: "This " },
{ text: "is", attrs: { style: {} }, color: "red" },
{ text: " text." },
],
},
],
};
const htmlValue = jsonToHtml(
jsonValue,
// parser options
{
customElementTypes: {
"social-embed": (attrs, child, jsonBlock) => {
return `${child}`;
},
},
customTextWrapper: {
"color": (child, value) => {
return `${child}`;
},
},
allowedEmptyAttributes : {
"p": ["dir"],
"img" : ["width"]
},
addNbspForEmptyBlocks : true
}
);
console.log(htmlValue);
```
> **_说明_**:指定的自定义解析器的密钥必须完全匹配元素类型. 这包括文本的外壳.
### 转换结果
由此产生的HTML数据如下:
```HTML
This is text.
```
### 将 HTML 转换为 JSON
您可以通过一个自定义解析器方法来转换上面提到的 HTML 元素类型的数据(例如, ``)到JSON格式. 在解析的选项中 `customElementTags` 对象解析块级和内含元素(例如信息面板),而 `customTextTags` 对象解析文本格式元素(如粗体、斜体、字体颜色等)。 这些选项将选择一个对象,其密钥是元素类型,而值是该类型将执行的解析函数.
解析器函数提供 `el` 引用 HTML 节点元素的参数.
您可以使用以下定制的 JSON RTE 序列器代码来将您的 HTML RTE 字段数据转换为 JSON 格式 .
```javascript
import { htmlToJson } from "@contentstack/json-rte-serializer";
const htmlDomBody = new DOMParser().parseFromString(
`
This is text.
`,
"text/html"
).body;
const jsonValue = htmlToJson(htmlDomBody, {
customElementTags: {
"SOCIAL-EMBED": (el) => ({
type: "social-embed",
attrs: {
url: el.getAttribute("url") || null,
},
}),
},
customTextTags: {
"COLOR": (el) => {
return {
color: el.getAttribute("data-color"),
};
},
},
});
console.log(jsonValue);
```
> **_说明:_** 上面的代码片段只为JavaScript驱动的前端网站工作.
对于基于Node.js的应用程序,您可以使用以下代码:
```javascript
const { htmlToJson } = require("@contentstack/json-rte-serializer")
const {JSDOM} = require('jsdom')
const dom = new JSDOM(`
This is text.
`)
let htmlDoc = dom.window.document.querySelector('body')
const jsonValue = htmlToJson(htmlDoc, {
customElementTags: {
"SOCIAL-EMBED": (el) => ({
type: "social-embed",
attrs: {
url: el.getAttribute("url") || null,
},
}),
},
customTextTags: {
"COLOR": (el) => {
return {
color: el.getAttribute("data-color"),
};
},
},
});
console.log(jsonValue);
```
> **_说明_**:自定义解析器的密钥必须始终被资本化并完全匹配自定义的HTML标记.
### 转换结果
由此产生的JSON格式数据如下:
```JSON
{
"type": "doc",
"uid": "cfe8176d1ca04cc0b42f60b3047f611d",
"attrs": {},
"children": [
{
"type": "p",
"attrs": {},
"uid": "6eae3c5bd7624bf39966c855543d954b",
"children": [
{
"type": "social-embed",
"attrs": {
"url": "https://twitter.com/Contentstack/status/1508911909038436365?cxt=HHwWmsC9-d_Y3fApAAAA",
"style": {},
"redactor-attributes": {
"url": "https://twitter.com/Contentstack/status/1508911909038436365?cxt=HHwWmsC9-d_Y3fApAAAA"
}
},
"uid": "8d8482d852b84822a9b66e55ffd0e57c",
"children": [
{
"text": ""
}
]
}
]
},
{
"type": "p",
"attrs": {},
"uid": "54a7340da87846dda28aaf622069559a",
"children": [
{
"text": "This "
},
{
"text": "is",
"attrs": {
"style": {}
},
"color": "red"
},
{
"text": " text."
}
]
}
]
}
```
## 自动转换
> **_说明_**数字 : `src` url为社会嵌入物和嵌入物提供 默认是 [uri 编码](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI)。 。 。 .
默认情况下,JSON富文本编辑器字段支持编辑器内部有限的HTML标记. 由于这个原因,JSON RTE序列器工具无法识别出每一个标准的HTML标记.
为了帮助JSON RTE序列器识别和处理跨HTML常用的额外标记,您可以使用自动转换选项. 当使用此选项时, 您需要通过 `allowNonStandardTags: true` 参数 `jsonToHtml` 或者说 `htmlToJson` 方法来按照您的要求操纵 JSON RTE 序列器包的工作。 当您通过此参数时, 它会自定义您的 JSON RTE 序列器代码, 允许在 JSON rich Text 编辑器字段中支持所有标准的 HTML 识别标记或元素类型 .
### 将 JSON 转换为 HTML
#### HTML 属性名称和值
这个工程确保了HTML属性按照W3C HTML的规格进行适当的验证和消毒. 它根据HTML标准验证属性名称,并消毒属性值,以确保正确的渲染和安全,特别是针对跨站点脚本(XSS)的弱点.
#### 属性名称准则
所有 HTML 属性名称必须符合 [W3C HTML 规格](https://www.w3.org/TR/2012/WD-html-markup-20120329/syntax.html#attribute-name)这些准则具体规定了下列规则:
- **可打印的 ASCII 字符 :** 属性名称必须只由可打印的 ASCII 字符组成.
- **不区分大小写 :** 属性名称对大小写不敏感,但小写优先用于一致性.
- **无特殊字符 :** 属性名称不能包含空格或特殊字符, 如 `=`, (中文(简体) ), `>`, (中文(简体) ), `<`, (中文(简体) ), `"`等 (中文(简体) ).
- **允许属性 :** 属性, 例如 `xmlns`, (中文(简体) ), `aria-*`, (中文(简体) ), `data-*`,以及HTML5标准所定义的其他标准.
##### 重要说明:
如果属性名称不符合这些规则,则属性将是 **丢弃** 从元素.
#### 属性值准则
HTML属性的值被消化,以确保正确渲染并减轻安全风险,例如交叉相地脚本(XSS). 此消毒过程涉及替换 HTML 实体( 如 : `<`, (中文(简体) ), `>`, (中文(简体) ), `&`等)与相应的字符并去除任何无效或不安全字符.
以下是一些常见的HTML实体及其替换:
- `<` → `<`
- `>` → `>`
- `&` → `&`
* * *
您可以在“ jsonToHtml” 方法中通过“ allow NonStandard Tags: true” 参数,允许 JSON RTE 序列器工具识别标准的 HTML 标记或元素类型,并将其转换为 JSON 格式.
您可以使用以下定制的 JSON RTE 序列器代码来将您的 JSON RTE 字段数据转换为 HTML 格式.
```js
import { jsonToHtml } from "@contentstack/json-rte-serializer";
const jsonValue = {
"type": "doc",
"uid": "cfe8176d1ca04cc0b42f60b3047f611d",
"attrs": {},
"children": [
{
"type": "hangout-module",
"attrs": {},
"children": [
{
"type": "hangout-chat",
"attrs": {
"from": "Paul, Addy"
},
"children": [
{
"type": "hangout-discussion",
"attrs": {},
"children": [
{
"type": "hangout-message",
"attrs": {
"from": "Paul",
"profile": "profile.png",
"datetime": "2013-07-17T12:02"
},
"children": [
{
"type": "p",
"attrs": {},
"children": [
{
"text": "Feelin' this Web Components thing."
}
]
},
{
"type": "p",
"attrs": {},
"children": [
{
"text": "Heard of it?"
}
]
}
]
}
]
}
]
},
{
"type": "hangout-chat",
"attrs": {},
"children": [
{
"text": "Hi There!"
}
]
}
]
}
]
};
const htmlValue = jsonToHtml(
jsonValue,
// parser options
{
allowNonStandardTypes: true
}
);
console.log(htmlValue);
```
### 转换结果
由此产生的HTML数据如下:
```html
Feelin' this Web Components thing.
Heard of it?
Hi There!
```
### 将 HTML 转换为 JSON
你可以通过 `allowNonStandardTags: true` 参数 `htmlToJson` 方法允许 JSON RTE 序列器工具识别标准的 HTML 标记或元素类型,同时将 JSON 数据转换为 HTML 格式.
您可以使用以下定制的 JSON RTE 序列器代码来将您的 HTML RTE 字段数据转换为 JSON 格式 .
```js
import { htmlToJson } from "@contentstack/json-rte-serializer";
const htmlDomBody = new DOMParser().parseFromString(
`Feelin' this Web Components thing.
Heard of it?
Hi There!`,
"text/html"
).body;
const jsonValue = htmlToJson(htmlDomBody, {
allowNonStandardTags: true,
});
console.log(jsonValue);
```
### 转换结果
由此产生的JSON格式数据如下:
```json
{
"type": "doc",
"uid": "cfe8176d1ca04cc0b42f60b3047f611d",
"attrs": {},
"children": [
{
"type": "hangout-module",
"attrs": {},
"children": [
{
"type": "hangout-chat",
"attrs": {
"from": "Paul, Addy"
},
"children": [
{
"type": "hangout-discussion",
"attrs": {},
"children": [
{
"type": "hangout-message",
"attrs": {
"from": "Paul",
"profile": "profile.png",
"datetime": "2013-07-17T12:02"
},
"children": [
{
"type": "p",
"attrs": {},
"children": [
{
"text": "Feelin' this Web Components thing."
}
]
},
{
"type": "p",
"attrs": {},
"children": [
{
"text": "Heard of it?"
}
]
}
]
}
]
}
]
},
{
"type": "hangout-chat",
"attrs": {},
"children": [
{
"text": "Hi There!"
}
]
}
]
}
]
}
```
# 文档
参考我们 [JSON 丰富的文本编辑器](https://www.contentstack.com/docs/developers/json-rich-text-editor/) 需要更多信息的文档.
# 许可证
这个项目使用了麻省理工学院的许可证. 参见 [自由主义](https://npmcn.com/package/%40contentstack/json-rte-serializer/LICENSE) 文档以获取更多信息.
## 常见问题
### @contentstack/json-rte-serializer 是什么？
此套件将 Html 文档转换为 Json 并反之 \.
### 如何安装 @contentstack/json-rte-serializer？
在项目目录运行 npm install @contentstack/json-rte-serializer，或使用 pnpm add / yarn add / bun add。
### @contentstack/json-rte-serializer 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @contentstack/json-rte-serializer 支持 ESM 还是 CommonJS？
同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。
### @contentstack/json-rte-serializer 可以商用吗？
@contentstack/json-rte-serializer 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @contentstack/json-rte-serializer 的下载量有多少？
根据 npm 官方下载统计，@contentstack/json-rte-serializer 在 2026/10/11 – 2026/11/09 这 30 天内被下载 77,514 次，日均约 2,584 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @contentstack/json-rte-serializer 还在维护吗？
最新版本 3\.1\.0 发布于 2026/05/18（5 个月前）；至今共发布 24 个版本，其中过去 12 个月发布了 2 个；首次发布于 2021/07/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。