数学公式扩展
此扩展可让你在编辑器中插入数学公式,并使用 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)