JSON RTE 序列器
内容tack是一种无头的CMS,采用API-First方法. 这是一个CMS,开发者可以用来用他们最喜爱的语言来构建强大的跨平台应用程序. 构建您的应用程序前端, 而Contack 将照顾其余的 . 更多信息。 。 。 .
JSON RTE 序列器软件包协助在 JSON 格式和 HTML 格式之间转换您 JSON 丰富的文本编辑器字段内的内容。 这意味着您可以轻松地将您的数据从JSON格式更改为HTML格式,用于显示目的,反之亦然,用于数据存储或处理. 如果你需要将JSON转换为Markdown格式,我们提供Markdown序列器功能. 这个功能专门设计将您的JSON数据转换为Markdown,使得使用Markdown的平台更容易处理文本格式化.
安装
要使用基于Node.js的应用程序的 JSON RTE 序列器,您需要下列先决条件:
- 节点.js 10或以后
安装 json-rte-serializer 使用下列命令通过 npm 软件包 :
npm install @contentstack/json-rte-serializer
JSON RTE 序列器使用大小写
让我们看看几个代码样本,显示我们如何将JSON格式中的数据转换为HTML,反之亦然.
标准转换
对于标准转换方案,JSON RTE 序列器只支持JSON Rich Text编辑器领域中可用的标准标记. 要使用自定义标签,您可以遵循 自定义转换 实例如下.
JSON 到 HTML 转换代码
您可以使用以下 JSON RTE 序列器代码来将您的 JSON RTE 字段数据转换为 HTML 格式.
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数据如下:
<p>This is HTML-formatted content.</p>
HTML 到 JSON 转换码
您可以使用以下 JSON RTE 序列器代码来将 HTML 字段数据转换为 JSON 格式.
import { htmlToJson } from "@contentstack/json-rte-serializer";
const htmlDomBody = new DOMParser().parseFromString(
"<p>This is HTML-formatted content.</p>",
"text/html"
).body;
const jsonValue = htmlToJson(htmlDomBody);
console.log(jsonValue);
说明: 上面的代码片段只为JavaScript驱动的前端网站工作.
对于基于Node.js的应用程序,您可以使用以下代码:
const { htmlToJson } = require("@contentstack/json-rte-serializer")
const {JSDOM} = require('jsdom')
const dom = new JSDOM("<p>This is HTML-formatted content.</p>")
let htmlDoc = dom.window.document.querySelector('body')
const jsonValue = htmlToJson(htmlDoc)
console.log(jsonValue);
转换结果
由此产生的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 格式.
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数据如下:
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 格式.
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 `<social-embed${attrs}>${child}</social-embed>`;
},
},
customTextWrapper: {
"color": (child, value) => {
return `<color data-color="${value}">${child}</color>`;
},
},
allowedEmptyAttributes : {
"p": ["dir"],
"img" : ["width"]
},
addNbspForEmptyBlocks : true
}
);
console.log(htmlValue);
说明:指定的自定义解析器的密钥必须完全匹配元素类型. 这包括文本的外壳.
转换结果
由此产生的HTML数据如下:
<p><social-embed url="https://twitter.com/Contentstack/status/1508911909038436365?cxt=HHwWmsC9-d_Y3fApAAAA"></social-embed></p><p>This <color data-color="red">is</color> text.</p>
将 HTML 转换为 JSON
您可以通过一个自定义解析器方法来转换上面提到的 HTML 元素类型的数据(例如, <social-embed>)到JSON格式. 在解析的选项中 customElementTags 对象解析块级和内含元素(例如信息面板),而 customTextTags 对象解析文本格式元素(如粗体、斜体、字体颜色等)。 这些选项将选择一个对象,其密钥是元素类型,而值是该类型将执行的解析函数.
解析器函数提供 el 引用 HTML 节点元素的参数.
您可以使用以下定制的 JSON RTE 序列器代码来将您的 HTML RTE 字段数据转换为 JSON 格式 .
import { htmlToJson } from "@contentstack/json-rte-serializer";
const htmlDomBody = new DOMParser().parseFromString(
`<p><social-embed url="https://twitter.com/Contentstack/status/1508911909038436365?cxt=HHwWmsC9-d_Y3fApAAAA"></social-embed></p><p>This <color data-color="red">is</color> text.</p>`,
"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的应用程序,您可以使用以下代码:
const { htmlToJson } = require("@contentstack/json-rte-serializer")
const {JSDOM} = require('jsdom')
const dom = new JSDOM(`<p><social-embed url="https://twitter.com/Contentstack/status/1508911909038436365?cxt=HHwWmsC9-d_Y3fApAAAA"></social-embed></p><p>This <color data-color="red">is</color> text.</p>`)
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格式数据如下:
{
"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."
}
]
}
]
}
自动转换
说明数字 :
srcurl为社会嵌入物和嵌入物提供 默认是 uri 编码。 。 。 .
默认情况下,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 规格这些准则具体规定了下列规则:
- 可打印的 ASCII 字符 : 属性名称必须只由可打印的 ASCII 字符组成.
- 不区分大小写 : 属性名称对大小写不敏感,但小写优先用于一致性.
- 无特殊字符 : 属性名称不能包含空格或特殊字符, 如
=, (中文(简体) ),>, (中文(简体) ),<, (中文(简体) ),"等 (中文(简体) ). - 允许属性 : 属性, 例如
xmlns, (中文(简体) ),aria-*, (中文(简体) ),data-*,以及HTML5标准所定义的其他标准.
重要说明:
如果属性名称不符合这些规则,则属性将是 丢弃 从元素.
属性值准则
HTML属性的值被消化,以确保正确渲染并减轻安全风险,例如交叉相地脚本(XSS). 此消毒过程涉及替换 HTML 实体( 如 : <, (中文(简体) ), >, (中文(简体) ), &等)与相应的字符并去除任何无效或不安全字符.
以下是一些常见的HTML实体及其替换:
<→<>→>&→&
您可以在“ jsonToHtml” 方法中通过“ allow NonStandard Tags: true” 参数,允许 JSON RTE 序列器工具识别标准的 HTML 标记或元素类型,并将其转换为 JSON 格式.
您可以使用以下定制的 JSON RTE 序列器代码来将您的 JSON RTE 字段数据转换为 HTML 格式.
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数据如下:
<hangout-module><hangout-chat from="Paul, Addy"><hangout-discussion><hangout-message from="Paul" profile="profile.png" datetime="2013-07-17T12:02"><p>Feelin' this Web Components thing.</p><p>Heard of it?</p></hangout-message></hangout-discussion></hangout-chat><hangout-chat>Hi There!</hangout-chat></hangout-module>
将 HTML 转换为 JSON
你可以通过 allowNonStandardTags: true 参数 htmlToJson 方法允许 JSON RTE 序列器工具识别标准的 HTML 标记或元素类型,同时将 JSON 数据转换为 HTML 格式.
您可以使用以下定制的 JSON RTE 序列器代码来将您的 HTML RTE 字段数据转换为 JSON 格式 .
import { htmlToJson } from "@contentstack/json-rte-serializer";
const htmlDomBody = new DOMParser().parseFromString(
`<hangout-module><hangout-chat from="Paul, Addy"><hangout-discussion><hangout-message from="Paul" profile="profile.png" datetime="2013-07-17T12:02"><p>Feelin' this Web Components thing.</p><p>Heard of it?</p></hangout-message></hangout-discussion></hangout-chat><hangout-chat>Hi There!</hangout-chat></hangout-module>`,
"text/html"
).body;
const jsonValue = htmlToJson(htmlDomBody, {
allowNonStandardTags: true,
});
console.log(jsonValue);
转换结果
由此产生的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 丰富的文本编辑器 需要更多信息的文档.
许可证
这个项目使用了麻省理工学院的许可证. 参见 自由主义 文档以获取更多信息.