查找和替换扩展
查找和替换扩展会搜索文档、突出显示匹配项,并提供用于导航和替换的命令。它是无界面的,因此你可以构建控件,并将其放置在应用程序中的任意位置。
安装
npm install @tiptap/extension-find-and-replace用法
import { Editor } from '@tiptap/core'
import FindAndReplace from '@tiptap/extension-find-and-replace'
import StarterKit from '@tiptap/starter-kit'
new Editor({
extensions: [StarterKit, FindAndReplace],
})请参阅自定义 UI 指南,了解完整的 React 和 Vue 示例。
设置
这些选项用于设置初始状态。编辑器运行时,使用以下命令更新搜索内容。
searchTerm
要搜索的初始文本。在正则表达式模式下,这是正则表达式的源代码。
默认值:''
FindAndReplace.configure({
searchTerm: 'Tiptap',
})replaceTerm
替换命令使用的初始文本。启用正则表达式模式时,替换内容可以重用完整匹配项或捕获组。
默认值:''
FindAndReplace.configure({
useRegex: true,
searchTerm: '(color|colour)',
replaceTerm: '[$1]',
})caseSensitive
搜索是否严格区分大小写。
默认值:false
FindAndReplace.configure({
caseSensitive: true,
})useRegex
是否将 searchTerm 作为正则表达式处理。
默认值:false
FindAndReplace.configure({
useRegex: true,
searchTerm: 'colou?r',
})正则表达式模式可以与 caseSensitive 和 wholeWord 一起使用。模式无效或被判定为不安全时,不会返回结果。正则表达式模式使用兼容 RE2 的语法,因此搜索模式不支持环视和反向引用。
wholeWord
是否要求匹配项两侧都具有 Unicode 单词边界。字面搜索和正则表达式搜索均支持此选项。Unicode 单词字符包括字母、组合标记、数字和 _ 等连接标点。
默认值:false
FindAndReplace.configure({
caseSensitive: true,
useRegex: true,
wholeWord: true,
searchTerm: 'cat|catalog',
})例如,此配置会匹配 cat 和 catalog,但不会匹配 cats 或 Catalog。较早的结果不符合全词边界时,正则表达式引擎可以尝试后续备选项或更长的匹配。
searchDebounceMs
setSearchTerm() 更新搜索结果前的延迟时间,单位为毫秒。将其设置为 0 可立即更新结果。
默认值:250
FindAndReplace.configure({
searchDebounceMs: 0,
})injectCSS
是否注入默认的结果高亮样式。禁用此选项后可提供自定义样式。
默认值:true
FindAndReplace.configure({
injectCSS: false,
})injectNonce
应用于注入样式元素的 nonce。当内容安全策略要求 nonce 时,请设置此项。
默认值:undefined
FindAndReplace.configure({
injectNonce: 'your-nonce-here',
})命令
setSearchTerm()
设置搜索词并高亮每个匹配项。
editor.commands.setSearchTerm('Tiptap')setReplaceTerm()
设置 replace() 和 replaceAll() 使用的文本。正则表达式模式下,替换文本可以包含捕获组替换。
editor.commands.setReplaceTerm('[$1]')正则表达式替换标记
启用正则表达式模式时,替换文本支持以下 JavaScript 风格的标记:
| 标记 | 替换内容 |
|---|---|
$$ | 字面量 $ |
$& | 完整匹配项 |
$1–$99 | 对应编号的捕获组 |
$<name> | 对应名称的捕获组 |
未匹配的捕获组会替换为空字符串。超出模式捕获组数量的一位数字引用会保持不变。对于两位数字引用,遵循 JavaScript 风格的回退规则:如果完整数字没有对应捕获组,但首位数字对应某个捕获组,则插入该捕获组,再接上第二位数字。例如,只有一个捕获组时,$12 会插入第 1 组的内容,后接 2。带前导零的引用(如 $01)也遵循 JavaScript 语义,指向第 1 组。当模式中包含命名组时,未知命名引用会替换为空字符串;否则保持不变。
其他 $ 序列保持不变。JavaScript 的匹配前内容标记($ 后接反引号)和匹配后内容标记($')不会展开。禁用正则表达式模式时,所有替换文本都会按字面内容插入。
在正则表达式模式下,使用 $$ 转义开头的美元符号,即可按字面保留受支持的标记。例如,$$1 会插入 $1。
editor.commands.setUseRegex(true)
editor.commands.setSearchTerm('(color|colour)')
editor.commands.setReplaceTerm('[$1]')
editor.commands.replaceAll()
// "color and colour" becomes "[color] and [colour]"setCaseSensitive()
启用或禁用区分大小写匹配。字面模式和正则表达式模式均支持此选项。
editor.commands.setCaseSensitive(true)setUseRegex()
启用或禁用正则表达式匹配。正则表达式模式可以与“区分大小写”和“全词匹配”同时启用。
editor.commands.setUseRegex(true)setWholeWord()
启用或禁用支持 Unicode 的全词匹配,可用于字面搜索或正则表达式搜索。
editor.commands.setWholeWord(true)goToNextResult()
选择下一个结果。导航到最后一个结果后会循环回第一个结果。
editor.commands.goToNextResult()goToPreviousResult()
选择上一个结果。导航到第一个结果后会循环回最后一个结果。
editor.commands.goToPreviousResult()replace()
替换选中的结果,并选择下一个可用结果。
editor.commands.replace()replaceAll()
替换当前结果集中的每个结果。
editor.commands.replaceAll()clearSearch()
清除搜索词并移除每个结果的高亮。
editor.commands.clearSearch()存储
该扩展将其当前状态保存在 editor.storage.findAndReplace 中。
searchTerm
当前搜索词。
editor.storage.findAndReplace.searchTermreplaceTerm
当前替换文本。
editor.storage.findAndReplace.replaceTermcaseSensitive、useRegex 和 wholeWord
当前匹配选项。
editor.storage.findAndReplace.caseSensitive
editor.storage.findAndReplace.useRegex
editor.storage.findAndReplace.wholeWordresults
按文档顺序排列的匹配项。每个结果都有 from 和 to 两个 ProseMirror 位置。
editor.storage.findAndReplace.resultscurrentIndex
所选结果的索引;未选择任何结果时为 null。
editor.storage.findAndReplace.currentIndex搜索行为
当文档或搜索选项发生变化时,匹配项会更新。一个匹配项可以跨越带有不同标记的文本节点,但绝不会跨越文本块或非文本内联节点,例如硬换行或提及。
“区分大小写”、“正则”和“全词匹配”是相互独立的选项,可以同时启用。在正则表达式全词模式下,边界会围绕最终的正则匹配结果进行检查。这允许备选项和量词继续尝试,直到匹配完整单词。连续匹配可以共享标点边界,因此针对 cat 的全词正则表达式会在 cat-cat.cat 中找到全部三个匹配项。
replaceAll() 会替换命令运行时存在的匹配项。如果替换文本也符合搜索条件,那么这些新匹配项会在事务完成后保留在存储中。
设置样式
默认情况下,结果会以黄色高亮显示,选中的结果会以橙色高亮显示。禁用 injectCSS 以替换这些样式。
.find-and-replace-result {
background-color: rgb(255 225 0 / 0.4);
}
.find-and-replace-result-current {
background-color: rgb(255 165 0 / 0.55);
}