Tiptap React：Shift-Enter行为定制及列表换行异常问题

1. 移除/自定义Shift-Enter的默认行为 #

Tiptap默认按下Shift-Enter会插入<br>标签实现换行，要修改或禁用这个行为，有两种可靠方式：

方式一：通过扩展覆盖键盘快捷键 #

在Document扩展的addKeyboardShortcuts里直接定义Shift-Enter的行为，返回true可完全阻止默认操作：

Document.extend({
  addKeyboardShortcuts() {
    return {
      // 保留你已有的Enter自定义逻辑
      Enter: () => {
        emitCustomEvent("enter-key-tiptap");
        return true;
      },
      // 自定义Shift-Enter行为
      "Shift-Enter": () => {
        // 这里写你的业务逻辑，比如触发自定义事件或执行编辑器命令
        emitCustomEvent("shift-enter-custom");
        return true; // 阻止默认的<br>插入
      },
    };
  },
})

方式二：通过editorProps拦截键盘事件 #

在editorProps.handleKeyDown里监听Shift+Enter组合键，先阻止默认行为再执行自定义逻辑：

editorProps: {
  handleKeyDown(view, event) {
    if (event.shiftKey && event.key === "Enter") {
      event.preventDefault(); // 关键：阻止默认插入<br>
      // 执行你的自定义逻辑，比如触发新增列表项事件
      emitCustomEvent("new-line-list");
      return true;
    }
    // 其他键盘逻辑...
  },
}

2. 列表模式下Enter/Shift-Enter行为优化 #

你的需求是：列表激活时，按Enter发送消息，按Shift-Enter新增列表项并自动维护序号。当前出现空行的核心原因是未阻止Shift-Enter的默认<br>插入行为，且手动修改HTML会破坏编辑器内部状态，正确做法如下：

修复后的核心代码 #

第一步：修改editorProps的handleKeyDown（拦截默认行为）

editorProps: {
  attributes: {
    class: `prose prose-sm custom-note sm:prose-sm lg:prose-lg xl:prose-2xl mx-auto focus:outline-none`,
  },
  handleKeyDown(view, event) {
    // Shift+Enter：列表模式下新增列表项
    if (event.shiftKey && event.key === "Enter") {
      event.preventDefault(); // 阻止默认插入<br>
      emitCustomEvent("new-line-list");
      return true;
    }
    // Enter：列表模式下发送消息
    if (!event.shiftKey && event.key === "Enter") {
      event.preventDefault(); // 阻止默认的列表项拆分行为
      emitCustomEvent("enter-for-list");
      return true;
    }
    // 非列表场景的Enter行为（保留你原有的逻辑）
    if (!editor?.isActive("orderedList") && !editor?.isActive("bulletList") && event.key === "Enter") {
      emitCustomEvent("enter-key-tiptap");
      return true;
    }
  },
},

第二步：优化事件处理函数（用Tiptap命令操作内容）

const handleEnterKeyForList = () => {
  // 确认处于列表中，直接发送消息
  if (editor?.isActive("orderedList") || editor?.isActive("bulletList")) {
    onMessageSend();
  }
};

const handleNewLineUpdate = () => {
  // 用Tiptap内置命令拆分列表项，自动维护序号/项目符号
  if (editor?.isActive("orderedList") || editor?.isActive("bulletList")) {
    editor?.chain().focus().splitListItem("listItem").run();
  }
};

为什么之前的方法无效？ #

手动替换HTML中的<br>标签会导致编辑器内部状态与渲染内容不一致，Tiptap的内容操作必须通过其内置命令系统完成，同时要提前阻止默认键盘事件，从根源避免不需要的<br>插入。

内容的提问来源于stack exchange，提问作者Pawan