🚀 BlockNote AI is here! Access the early preview.
BlockNote Docs/Features/自定义模式

自定义模式

默认情况下,BlockNote 文档支持不同类型的块、内联内容和文本样式(参见默认模式)。 不过,您可以扩展 BlockNote,创建自定义模式以支持您自己的块、内联内容和文本样式。

自定义块

块是文档的主要元素,例如段落、标题、列表等。

自定义内联内容

内联内容是可以插入到文本块中的元素,例如链接、提及、标签等。

自定义样式

文本样式是可以应用于一段文本的属性,例如加粗、斜体、下划线等。

创建您自己的模式

一旦您定义了自定义块(参见上面的链接)、内联内容或样式,就可以创建一个模式并将其传递给编辑器的初始化。有两种方法可以创建新模式。

扩展现有模式

您可以调用 BlockNoteSchema.extend 向现有模式添加自定义块、内联内容或样式。虽然这适用于任何现有模式,但最常用的是用来扩展默认模式。

// 当什么都不传入 `BlockNoteSchema.create` 时,会创建默认模式的实例。
const schema = BlockNoteSchema.create()
  // 向默认模式添加自定义块、内联内容或样式。
  .extend({
    blockSpecs: {
      // 添加您自己的自定义块:
      customBlock: CustomBlock,
      ...
    },
    inlineContentSpecs: {
      // 添加您自己的自定义内联内容:
      customInlineContent: CustomInlineContent,
      ...
    },
    styleSpecs: {
      // 添加您自己的自定义样式:
      customStyle: CustomStyle,
      ...
    },
  });

从头创建模式

将自定义块、内联内容或样式直接传递给 BlockNoteSchema.create 会创建一个只包含您传入内容的新模式。如果您只需要默认模式中的少数基本内容,且打算自行实现其余部分,这非常有用。

const schema = BlockNoteSchema.create({
  blockSpecs: {
    // 只添加默认的段落块:
    paragraph: defaultBlockSpecs.paragraph,

    // 添加您自己的自定义块:
    customBlock: CustomBlock,
    ...
  },
  inlineContentSpecs: {
    // 只添加默认的文本内联内容:
    text: defaultInlineContentSpecs.text,

    // 添加您自己的自定义内联内容:
    customInlineContent: CustomInlineContent,
    ...
  },
  styleSpecs: {
    // 只添加默认的加粗样式:
    bold: defaultStyleSpecs.bold,

    // 添加您自己的自定义样式:
    customStyle: CustomStyle,
    ...
  },
});

使用您自己的模式

一旦您使用 BlockNoteSchema.createBlockNoteSchema.extend 创建了模式实例,就可以将其传递给 BlockNoteEditor 的 schema 选项(无论是 BlockNoteEditor.create 还是 useCreateBlockNote):

const editor = useCreateBlockNote({
  schema,
});

在 TypeScript 中的使用

与大多数其他编辑器不同,BlockNote 设计为完全兼容 TypeScript。这意味着即使使用自定义模式,您也可以获得完整的类型安全和自动补全。

默认情况下,API 暴露的方法、hooks 和类型假设您正在使用默认的内置模式。如果您使用自定义模式,有三种方式可以获得完整的类型安全:

接受可选 schema 参数的方法

一些方法,如 useBlockNoteEditor hook,接受一个可选的 schema?: BlockNoteSchema 参数。如果您使用自定义模式,应在这里传入它,以确保返回类型正确。

手动定义类型

如果您直接使用像 BlockNoteEditorBlockPartialBlock 这样的类型,可以这样获得正确类型的变体:

type MyBlock = Block<
  typeof schema.blockSchema,
  typeof schema.inlineContentSchema,
  typeof schema.styleSchema
>;

或者更简单地,使用模式暴露的简写:

type MyBlockNoteEditor = typeof schema.BlockNoteEditor;
type MyBlock = typeof schema.Block;
type MyPartialBlock = typeof schema.PartialBlock;

自动覆盖所有默认类型(实验性)

另外,获取完整类型安全而无需额外工作最简单的方式是通过自定义类型定义文件,用您的自定义模式覆盖所有默认类型。请参见这个 示例 blocknote.d.ts。这是一个实验性功能——我们非常希望听到您对这一方法的反馈。