数学公式扩展

版本下载量

此扩展可让你在编辑器中插入数学公式,并使用 KaTeX 渲染以 LaTeX 编写的公式。

安装

npm install @tiptap/extension-mathematics katex

用法

import { Mathematics } from '@tiptap/extension-mathematics'

const editor = new Editor({
  extensions: [
    Mathematics.configure({
      inlineOptions: {
        // optional options for the inline math node
      },
      blockOptions: {
        // optional options for the block math node
      },
      katexOptions: {
        // optional options for the KaTeX renderer
      },
    }),
  ],
})

其他设置

设置 KaTeX 渲染样式

你可以自行设置渲染元素和编辑器输入区域的样式。

必须导入 KaTeX 样式。

import 'katex/dist/katex.min.css'

你可以使用以下 class 选择数学公式节点并设置其样式。示例代码见本页末尾。

/* The rendered math node */
.tiptap-mathematics-render {
  // …
}

/* This selector only selects editable math nodes */
.tiptap-mathematics-render--editable {
  // …
}

/** This selector only selects block math nodes */
.tiptap-mathematics-render[data-type="block-math"] {
  // …
}

/** This selector only selects inline math nodes */
.tiptap-mathematics-render[data-type="inline-math"] {
  // …
}

配置扩展并更新数学公式节点

此扩展提供若干选项,用于配置数学公式节点的行为。

import Mathematics from '@tiptap/extension-mathematics'

// [...]

Mathematics.configure({
  // Options for the inline math node
  inlineOptions: {
    onClick: (node, pos) => {
      // you can do anything on click, e.g. open a dialog to edit the math node
      // or just a prompt to edit the LaTeX code for a quick prototype
      const katex = prompt('Enter new calculation:', node.attrs.latex)
      if (katex) {
        editor.chain().setNodeSelection(pos).updateInlineMath({ latex: katex }).focus().run()
      }
    },
  },

  // Options for the block math node
  blockOptions: {
    onClick: (node, pos) => {
      // you can do anything on click, e.g. open a dialog to edit the math node
      // or just a prompt to edit the LaTeX code for a quick prototype
      const katex = prompt('Enter new calculation:', node.attrs.latex)
      if (katex) {
        editor.chain().setNodeSelection(pos).updateBlockMath({ latex: katex }).focus().run()
      }
    },
  },

  // Options for the KaTeX renderer. See here: https://katex.org/docs/options.html
  katexOptions: {
    throwOnError: false, // don't throw an error if the LaTeX code is invalid
    macros: {
      '\\R': '\\mathbb{R}', // add a macro for the real numbers
      '\\N': '\\mathbb{N}', // add a macro for the natural numbers
    },
  },
}

将现有数学装饰迁移为数学公式节点

Math 扩展以前使用装饰来表示公式,因此你的编辑器中可能已有数学装饰。你可以使用扩展提供的 migrateMathStrings 工具函数,将它们迁移为新的数学公式节点。

import { migrateMathStrings } from '@tiptap/extension-mathematics'

// The best way to do this is to run it in the `onCreate` hook of your editor
// but you have to be cautious in collaborative environments to wait for the initial document to be loaded
const editor = new Editor({
  // [...]
  onCreate: ({ editor: currentEditor }) => {
    migrateMathStrings(currentEditor)
  },
})

// or if you are running a collaborative environment with a provider
const editor = new Editor({
  // [...]
  onCreate: ({ editor: currentEditor }) => {
    provider.on('synced', () => {
      migrateMathStrings(currentEditor)
    })
  },
})

只导入一种数学公式节点

如果只需要一种数学公式节点(行内或块级),可以直接导入对应扩展:

import { InlineMath } from '@tiptap/extension-mathematics/inline'

// [...]

InlineMath.configure({
  katexOptions: {
    // optional options for the KaTeX renderer
  },
  onClick: (node, pos) => {
    // you can do anything on click, e.g. open a dialog to edit the math node
    // or just a prompt to edit the LaTeX code for a quick prototype
    const katex = prompt('Enter new calculation:', node.attrs.latex)
    if (katex) {
      editor.chain().setNodeSelection(pos).updateInlineMath({ latex: katex }).focus().run()
    }
  },
})

设置

inlineOptions

此选项用于配置行内数学公式节点。你可以传入该节点支持的任意选项,例如使用 onClick 处理节点的点击事件。

默认值:undefined

import Mathematics from '@tiptap/extension-mathematics'

// [...]

Mathematics.configure({
  inlineOptions: {
    onClick: (node, pos) => {
      // you can do anything on click, e.g. open a dialog to edit the math node
      // or just a prompt to edit the LaTeX code for a quick prototype
      const katex = prompt('Enter new calculation:', node.attrs.latex)
      if (katex) {
        editor.chain().setNodeSelection(pos).updateInlineMath({ latex: katex }).focus().run()
      }
    },
  },
})

blockOptions

此选项用于配置块级数学公式节点。你可以传入该节点支持的任意选项,例如使用 onClick 处理节点的点击事件。

默认值:undefined

import Mathematics from '@tiptap/extension-mathematics'

// [...]

Mathematics.configure({
  blockOptions: {
    onClick: (node) => {
      // you can do anything on click, e.g. open a dialog to edit the math node
      // or just a prompt to edit the LaTeX code for a quick prototype
      const katex = prompt('Enter new calculation:', node.attrs.latex)
      if (katex) {
        editor.chain().setNodeSelection(pos).updateBlockMath({ latex: katex }).focus().run()
      }
    },
  },
})

katexOptions

此选项用于配置 KaTeX 渲染器。所有选项请参阅此处。

默认值:undefined

import Mathematics from '@tiptap/extension-mathematics'

// [...]

Mathematics.configure({
  katexOptions: {
    throwOnError: false, // don't throw an error if the LaTeX code is invalid
    macros: {
      '\\R': '\\mathbb{R}', // add a macro for the real numbers
      '\\N': '\\mathbb{N}', // add a macro for the natural numbers
    },
  },
})

InlineMath 设置

onClick

此选项用于处理行内数学公式节点的点击事件。你可以借此打开对话框编辑节点,也可以使用 prompt 快速编辑 LaTeX 代码以进行原型验证。

默认值:undefined

import { InlineMath } from '@tiptap/extension-mathematics'

// [...]

InlineMath.configure({
  onClick: (node) => {
    // you can do anything on click, e.g. open a dialog to edit the math node
    // or just a prompt to edit the LaTeX code for a quick prototype
    const katex = prompt('Enter new calculation:', node.attrs.latex)
    if (katex) {
      editor.chain().setNodeSelection(pos).updateInlineMath({ latex: katex }).focus().run()
    }
  },
})

katexOptions

此选项用于配置行内数学公式节点的 KaTeX 渲染器。所有选项请参阅此处。

默认值:undefined

import { InlineMath } from '@tiptap/extension-mathematics'

// [...]

InlineMath.configure({
  katexOptions: {
    throwOnError: false, // don't throw an error if the LaTeX code is invalid
    macros: {
      '\\R': '\\mathbb{R}', // add a macro for the real numbers
      '\\N': '\\mathbb{N}', // add a macro for the natural numbers
    },
  },
})

BlockMath 设置

onClick

此选项用于处理块级数学公式节点的点击事件。你可以借此打开对话框编辑节点,也可以使用 prompt 快速编辑 LaTeX 代码以进行原型验证。

默认值:undefined

import { BlockMath } from '@tiptap/extension-mathematics'

// [...]

BlockMath.configure({
  onClick: (node) => {
    // you can do anything on click, e.g. open a dialog to edit the math node
    // or just a prompt to edit the LaTeX code for a quick prototype
    const katex = prompt('Enter new calculation:', node.attrs.latex)
    if (katex) {
      editor.chain().setNodeSelection(pos).updateBlockMath({ latex: katex }).focus().run()
    }
  },
})

katexOptions

此选项用于配置块级数学公式节点的 KaTeX 渲染器。所有选项请参阅此处。

默认值:undefined

import { BlockMath } from '@tiptap/extension-mathematics'

// [...]

BlockMath.configure({
  katexOptions: {
    throwOnError: false, // don't throw an error if the LaTeX code is invalid
    macros: {
      '\\R': '\\mathbb{R}', // add a macro for the real numbers
      '\\N': '\\mathbb{N}', // add a macro for the natural numbers
    },
  },
})

InlineMath 命令

insertInlineMath({ latex, pos })

在指定位置插入包含给定 LaTeX 代码的行内数学公式节点。如果未提供 pos,则在当前选区插入节点。

// with a specified position
editor.commands.insertInlineMath({
  latex: '\\frac{a}{b}',
  pos: 38,
})

// or without a position
editor.commands.insertInlineMath({
  latex: '\\frac{a}{b}',
})

deleteInlineMath({ pos })

删除指定位置的行内数学公式节点。如果未提供 pos,则删除当前选区中的节点。

// with a specified position
editor.commands.deleteInlineMath({
  pos: 38,
})

// or without a position
editor.commands.deleteInlineMath()

updateInlineMath({ latex, pos })

在指定位置使用给定的 LaTeX 代码更新行内数学公式节点。如果未提供 pos,则更新当前选区中的节点。

// with a specified position
editor.commands.updateInlineMath({
  latex: '\\frac{a}{b}',
  pos: 38,
})

// or without a position
editor.commands.updateInlineMath({
  latex: '\\frac{a}{b}',
})

BlockMath 命令

insertBlockMath({ latex, pos })

在指定位置插入包含给定 LaTeX 代码的块级数学公式节点。如果未提供 pos,则在当前选区插入节点。

// with a specified position
editor.commands.insertBlockMath({
  latex: '\\frac{a}{b}',
  pos: 38,
})

// or without a position
editor.commands.insertBlockMath({
  latex: '\\frac{a}{b}',
})

deleteBlockMath({ pos })

删除指定位置的块级数学公式节点。如果未提供 pos,则删除当前选区中的节点。

// with a specified position
editor.commands.deleteBlockMath({
  pos: 38,
})

// or without a position
editor.commands.deleteBlockMath()

updateBlockMath({ latex, pos })

在指定位置使用给定的 LaTeX 代码更新块级数学公式节点。如果未提供 pos,则更新当前选区中的节点。

// with a specified position
editor.commands.updateBlockMath({
  latex: '\\frac{a}{b}',
  pos: 38,
})

// or without a position
editor.commands.updateBlockMath({
  latex: '\\frac{a}{b}',
})

工具函数和常量

mathMigrationRegex

用于查找并迁移编辑器中数学表达式的默认正则表达式。它会匹配由 $ 符号包裹的 LaTeX 表达式。

import { mathMigrationRegex } from '@tiptap/extension-mathematics'

createMathMigrateTransaction(editor, transaction, regex)

创建一个 ProseMirror 事务,将编辑器文档中的数学表达式迁移为数学公式节点,并使用传入的正则表达式查找这些表达式。

参数

  • editor:ProseMirror 编辑器实例。
  • transaction:要修改的 ProseMirror 事务。
  • regex(可选):用于查找数学表达式的正则表达式。默认为 mathMigrationRegex。
import { createMathMigrateTransaction } from '@tiptap/extension-mathematics'

const tr = createMathMigrateTransaction(editor, editor.state.tr, mathMigrationRegex)
editor.view.dispatch(tr)

migrateMathStrings(editor, regex)

创建并运行迁移事务,将编辑器文档中的数学表达式转换为数学公式节点,并使用传入的正则表达式查找这些表达式。

参数

  • editor:ProseMirror 编辑器实例。
  • regex(可选):用于查找数学表达式的正则表达式。默认为 mathMigrationRegex。
import { migrateMathStrings } from '@tiptap/extension-mathematics'

migrateMathStrings(editor, mathMigrationRegex)