抠丁客 抠丁客
项目
编辑 (2024/6/19)

tiptap 创建菜单

引言

Tiptap 从基础开始提供，但这其实是一件好事。你对界面的外观有完全的控制。

当我们说“完全控制”时，我们是认真的。你可以（也必须）自己构建菜单，但 Tiptap 会帮你连接一切。

菜单

编辑器提供了流畅的 API 来触发命令和添加活动状态。你可以使用任何你喜欢的标记。为了使菜单定位更简单，Tiptap 提供了一些工具和组件。让我们逐个了解最典型的用例。

固定菜单

固定菜单会永久位于某个位置，比如通常会在编辑器上方放置一个固定的菜单。虽然 Tiptap 并没有预先打包好的固定菜单，但你可以通过简单地创建一个 <div> 元素，并填充一些 <button> 元素来自定义它。下面 将介绍如何使用这些按钮在编辑器中触发 命令，例如加粗或斜体文本。

泡泡菜单

泡泡菜单 会在选中文本时出现。这里的标记和样式完全取决于你自己。

浮动菜单

浮动菜单会在你将光标放在空行上时在编辑器中出现。同样，这里的标记和样式完全取决于你自己。

斜线命令（工作进行中）

虽然还没有官方扩展，但有一个 实验 允许你使用 “斜线命令” 。使用斜线命令，当你在新行开头输入 / 时，会显示一个弹出菜单。

按钮

好的，你已经有了菜单。但是如何连接它们呢？

命令

你已经在运行编辑器，并想要添加第一个按钮。你需要一个带有点击处理程序的 <button> HTML 标签。根据你的设置，这可能看起来像下面的例子：

<button onclick="editor.chain().focus().toggleBold().run()">加粗</button>

哦，那是个很长的命令，对吧？实际上，它是一个 命令链 。让我们逐个分析：

editor.chain().focus().toggleBold().run();
  1. editor应该是 Tiptap 实例，
  2. chain()告诉编辑器你想执行多个命令，
  3. focus()将焦点重新设置到编辑器，
  4. toggleBold()标记选中的文本为粗体，如果已应用，则会移除粗体标记，
  5. run()将执行链。

换句话说：这将是你文本编辑器中的典型加粗按钮。

可用的命令取决于你注册给编辑器的哪些扩展。大多数扩展都带有 set…()、unset…() 和 toggle…() 命令。查看扩展文档以查看实际可用的内容，或者直接浏览你的代码编辑器的自动完成功能。

保持焦点

在上述示例中，你已经看到了 focus() 命令。点击按钮时，浏览器会聚焦那个 DOM 元素，而编辑器会失去焦点。很可能你想要在所有菜单按钮上添加 focus() ，这样用户的写作流程就不会被打断。

活动状态

编辑器提供了一个 isActive() 方法来检查选中文本上是否已应用了什么东西。在 Vue.js 中，你可以借助这个函数切换 CSS 类：

<button
  :class="{ 'is-active': editor.isActive('bold') }"
  @click="editor.chain().focus().toggleBold().run()"
>
  加粗
</button>

这会相应地切换 .is-active 类，并适用于节点和标记。你甚至可以检查特定属性。这里有一个使用 Highlight 标记的例子，该标记忽略了不同的属性：

editor.isActive("highlight");

还有一个例子，比较给出的属性：

editor.isActive("highlight", { color: "#ffa8a8" });

甚至支持正则表达式：

editor.isActive("textStyle", { color: /.*/ });

你甚至可以检查节点和标记，但只检查属性。这里是使用 TextAlign 扩展的一个例子：

editor.isActive({ textAlign: "right" });

如果选区跨越多个节点或标记，或者选区部分有标记，isActive() 将返回 false，表示什么都没有激活。这是应该如此的，因为这样可以让用户立即在选区上应用新的节点或标记。

用户体验

在设计出色的用户体验时，你应该考虑一些事情。

可访问性

  • 确保用户可以用键盘导航菜单
  • 使用正确的 标题属性
  • 使用适当的 ARIA 属性
  • 列出可用的键盘快捷键

警告 不完整
这部分需要改进。当你构建编辑器菜单时，还需要考虑哪些其他因素？请在 GitHub 上告诉我们，或者发送电子邮件至 humans@tiptap.dev ！

图标

大多数编辑器菜单使用图标作为按钮。在我们的一些演示中，我们使用了开源图标集 Remix Icon ，它是免费使用的。但选择什么图标完全取决于你。这里有一些你可以考虑的图标集：

在本文档中