查找和替换扩展

版本下载量

查找和替换扩展会搜索文档、突出显示匹配项,并提供用于导航和替换的命令。它是无界面的,因此你可以构建控件,并将其放置在应用程序中的任意位置。

安装

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.searchTerm

replaceTerm

当前替换文本。

editor.storage.findAndReplace.replaceTerm

caseSensitive、useRegex 和 wholeWord

当前匹配选项。

editor.storage.findAndReplace.caseSensitive
editor.storage.findAndReplace.useRegex
editor.storage.findAndReplace.wholeWord

results

按文档顺序排列的匹配项。每个结果都有 from 和 to 两个 ProseMirror 位置。

editor.storage.findAndReplace.results

currentIndex

所选结果的索引;未选择任何结果时为 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);
}

源代码

packages/extension-find-and-replace/