格式互操作性

BlockNote 兼容几种不同的存储格式，每种格式都有其优缺点。本指南将向您展示如何使用它们。

概述

对于编辑器来说，格式可能比较棘手。编辑器需要能够读取和写入每种格式。

如果元素在此转换过程中未被保留，我们称转换为有损。虽然我们理想上支持每种格式，但 其他格式可能不支持所有 BlockNote 内容。

请参阅下表以查看我们支持的格式及其有损性的总结：

格式	导入	导出	仅限专业版
BlockNote JSON (`editor.document`)	✅	✅	❌
BlockNote HTML (`blocksToFullHTML`)	✅	✅	❌
标准 HTML (`blocksToHTMLLossy`)	✅（有损）	✅（有损）	❌
Markdown (`blocksToMarkdownLossy`)	✅（有损）	✅（有损）	❌
PDF (`@blocknote/xl-pdf-exporter`)	❌	✅	✅
DOCX (`@blocknote/xl-docx-exporter`)	❌	✅	✅
ODT (`@blocknote/xl-odt-exporter`)	❌	✅	✅
Email (`@blocknote/xl-email-exporter`)	❌	✅	✅

提示： 推荐使用 BlockNote JSON (editor.document) 来存储文档，因为它是最持久的格式且保证无损。

使用区块（JSON）

BlockNote 使用 JSON 结构（一个 Block 对象数组）作为其原生格式。这是推荐的存储文档方式，因为它是无损的，能够完整保留内容的精确结构和所有属性。

保存区块

获取最新内容的最佳方法是在使用原生 JS 时使用 editor.onChange 回调，或在 React 中使用 useEditorChange 钩子。每当编辑器内容发生变化时，该函数都会被调用。

import React from "react";
import { ,  } from "@blocknote/react";
import {  } from "@blocknote/mantine";


export default function () {
  const  = ();

  (() => {
    // 当前文档内容的字符串形式
    const  = .(.);

    ();
  }, );

  return < ={} />;
}

加载区块

加载内容时，可以在创建编辑器时使用 initialContent 属性。您可以传入之前保存的 Block 对象数组。

import { useCreateBlockNote } from "@blocknote/react";
import type { Block } from "@blocknote/core";
import { BlockNoteView } from "@blocknote/mantine";

export default function App({
  initialContent,
}: {
  initialContent?: Block<any, any, any>[];
}) {
  const editor = useCreateBlockNote({
    initialContent,
  });

  return <BlockNoteView editor={editor} />;
}

使用 HTML

BlockNote 提供了将内容在 Block 对象和 HTML 之间转换的工具。请注意，转换为标准 HTML 可能是有损的。

保存为 HTML

要将文档转换为 HTML 字符串，可以使用 editor.blocksToFullHTML(blocks: Block[])：

import React from "react";
import { ,  } from "@blocknote/react";
import {  } from "@blocknote/mantine";


export default function () {
  const  = ();

  (async () => {
    const  = await .(.);
    // 你现在可以保存这个 HTML 字符串
    ();
  }, );

  return < ={} />;
}

editor.blocksToFullHTML 方法会输出 BlockNote 内部格式的 HTML。如果想导出为标准 HTML，可以改用 editor.blocksToHTMLLossy。

从 HTML 加载

加载 HTML 内容时，首先需要使用 editor.tryParseHTMLToBlocks() 将 HTML 转换为 Block 对象数组，然后再插入编辑器。

import React from "react";
import {  } from "react";
import {  } from "@blocknote/react";
import {  } from "@blocknote/mantine";

const  = "<p>这是一个段落。</p>";

export default function () {
  const  = ();

  (() => {
    // 初始化时替换区块内容
    // 你也可以在渲染编辑器之前调用此方法
    async function () {
      const  = await .();
      .(., );
    }
    ();
  }, []);

  return < ={} />;
}

使用 Markdown

BlockNote 也支持 Markdown 的相互转换。但转换为 Markdown 及从 Markdown 转换都是有损的。

保存为 Markdown

要将文档转换为 Markdown 字符串，可以使用 editor.blocksToMarkdownLossy()：

import React from "react";
import { ,  } from "@blocknote/react";
import {  } from "@blocknote/mantine";


export default function () {
  const  = ();

  (async () => {
    const  = await .(.);
    // 你现在可以保存这个 Markdown 字符串
    ();
  }, );

  return < ={} />;
}

从 Markdown 加载

加载 Markdown 内容时，首先需要使用 editor.tryParseMarkdownToBlocks() 将 Markdown 转换为 Block 对象数组，然后插入编辑器。

import React from "react";
import {  } from "react";
import {  } from "@blocknote/react";
import {  } from "@blocknote/mantine";

const  = "这是一个带有 **加粗** 文字的段落。";

export default function () {
  const  = ();

  (() => {
    async function () {
      const  = await .();
      .(., );
    }
    ();
  }, []);

  return < ={} />;
}

仅导出格式

BlockNote 还支持导出到以下额外格式：

DOCX
- 通过 @blocknote/xl-docx-exporter 包
PDF
- 通过 @blocknote/xl-pdf-exporter 包
ODT
- 通过 @blocknote/xl-odt-exporter 包
电子邮件
- 通过 @blocknote/xl-email-exporter 包