建议工具

此工具帮助处理编辑器中的各种建议。查看 Mention 或 Emoji 节点以查看其实际效果。

设置

char

触发自动补全弹出窗口的字符。

默认：'@'

pluginKey

一个 ProseMirror PluginKey。

默认：SuggestionPluginKey

allow

一个返回布尔值的函数，指示建议是否应处于活动状态。

默认：(props: { editor: Editor; state: EditorState; range: Range, isActive?: boolean }) => true

shouldShow

一个返回布尔值的函数，用于指示建议是否应处于激活状态。这对于防止在协作环境中远程用户触发建议弹窗非常有用。

shouldShow: ({ editor, range, query, text, transaction }) => {
  return !isChangeOrigin(transaction)
}

默认：null

shouldResetDismissed

控制用户通过 Escape 或 exitSuggestion() 关闭后，何时让已关闭的建议再次变为活动状态。

默认情况下，只要用户停留在同一个触发上下文中，该工具会保持已关闭的建议处于关闭状态。使用 allowSpaces: true 时，该已关闭上下文可以跨越空格，直到光标离开它为止。

如果你需要自行决定何时清除该已关闭上下文，请使用 shouldResetDismissed。

该回调不会在每次事务中都被调用。它只会在以下事务上进行评估：建议插件找到有效匹配、匹配通过 allow 和 shouldShow，并且存在可能需要清除的已关闭建议状态。

Suggestion({
  // ...
  shouldResetDismissed: ({ transaction, allowSpaces, range, match }) => {
    if (!allowSpaces) {
      return false
    }

    return transaction.doc.textBetween(range.from, match.range.to, '\n').includes('.')
  },
})

返回 true 以清除当前事务的已关闭状态，并允许建议再次打开。

默认：null

allowSpaces

允许或不允许建议项目中出现空格。

默认：false

allowedPrefixes

允许触发建议的前缀字符。设置为 null 以允许任何前缀字符。

默认：[' ']

startOfLine

仅在行首触发自动补全弹出窗口。

默认：false

decorationTag

应为建议呈现的 HTML 标签。

默认：'span'

decorationClass

应添加到建议的 CSS 类。

默认: 'suggestion'

decorationContent

应在建议装饰中呈现的内容。

默认: ''

decorationEmptyClass

当建议为空时应添加的 CSS 类。

默认: 'is-empty'

command

选择建议时执行的操作。

默认：() => {}

items

传递一个过滤后的建议数组，可以是异步的。

默认：({ editor, query }) => []

render

自动补全弹出窗口的渲染函数。

默认：() => ({})

findSuggestionMatch

可选参数，用于替换触发建议的编辑器内容内置正则匹配。
有关更多详细信息，请参见源代码。

默认：findSuggestionMatch(config: Trigger): SuggestionMatch

关闭打开的建议

有时你希望用户能够在不选择项目的情况下退出打开的建议。
为实现这一点，用户可以按下 Escape 键，这将关闭打开的建议。
如果你想手动触发关闭建议，可以使用 exitSuggestion 工具函数来关闭视图中现有的建议。

import { exitSuggestion } from '@tiptap/suggestion'
import { PluginKey } from 'prosemirror-state' // 可选，如果你需要创建自定义的 key

const MySuggestionPluginKey = new PluginKey('my-suggestions') // 或使用默认的 'suggestion'

exitSuggestion(editor.view, MySuggestionPluginKey)

// 或者，使用默认的插件 key：
// exitSuggestion(editor.view, 'suggestion')

Collaboration

当在协作环境中使用 Tiptap 时，你可能会注意到当某个用户触发建议（如提及）时，建议会对所有用户弹出。这是因为文档更改被同步到所有客户端，每个客户端的建议插件都会对该更改作出反应。

为防止这种情况，可以使用 shouldShow 选项结合来自 @tiptap/extension-collaboration 的 isChangeOrigin 辅助函数。

import { isChangeOrigin } from '@tiptap/extension-collaboration'

Suggestion({
  // …
  shouldShow: ({ transaction }) => {
    return !isChangeOrigin(transaction)
  },
})

通过返回 !isChangeOrigin(props.transaction)，只有当前用户发起更改时，建议才会被激活。

源代码

packages/suggestion/

Previously静态渲染器

Next upPHP 集成工具