ngx summernote补全下拉值时出现行错位的格式异常

异常现象 #

在基于ngx-summernote开发自定义下拉值补全功能时，常规操作场景下补全逻辑运行正常，但存在固定可复现的异常：

• 用户按下回车键完成换行操作
• 在新生成的输入行输入部分触发补全匹配规则的文本
• 触发自定义补全下拉面板并选中目标补全值时，补全内容会错位插入到当前输入行的下一行，完全不符合预期的当前行插入效果
• 未发生换行的常规输入场景下，补全插入逻辑无任何异常

问题核心根因 #

该错位本质是Summernote内部Range对象的光标定位校准失效导致：
Summernote 自身维护的光标Range实例，会在回车换行触发DOM结构变更（生成新的文本块节点）时，无法实时同步更新绑定关系。很多开发者在开发补全功能时，习惯缓存输入事件触发瞬间的Range对象，等用户选择补全值时直接拿缓存的Range执行插入，此时缓存的Range已经因为节点变更失效，最终导致插入位置偏移到相邻文本块。

可落地的解决步骤 #

• 不跨事件长期缓存光标Range对象，每次即将执行补全插入的动作前，实时重新获取最新的光标Range
  插入前的光标校准参考代码：

  // 获取绑定了summernote实例的编辑器DOM节点
  const editorDom = document.querySelector('.summernote');
  // 基于当前编辑器DOM实时创建最新的Range对象，替换之前缓存的失效Range
  const latestRange = $.summernote.range.create(editorDom);
  latestRange.select(); // 重新将光标绑定到最新的有效位置
  

• 补全文本插入完成后，立即对光标位置做二次校准，避免后续输入的位置偏移：

  // 调用summernote原生API插入选中的补全值
  $('.summernote').summernote('insertText', 选中的补全值);
  // 插入完成后重新获取Range，将光标定位到刚插入文本的末尾
  const postInsertRange = $.summernote.range.create(editorDom);
  postInsertRange.collapse(false).select();
  

• 针对回车生成的空段落场景，提前校验当前光标所在的父块状态：如果当前段落是刚生成的空文本块，插入补全值前先清除块内的占位空节点，避免插入时被DOM解析为新的相邻块。

常见避坑提示 #

• 不要使用原生document.execCommand执行文本插入，该方法和Summernote的内部DOM模型不兼容，会进一步加剧光标定位偏移
• 不要在补全面板弹出抢焦的节点获取光标Range，此时编辑器焦点临时丢失，拿到的Range必然存在位置偏差，一定要在用户点击补全选项、即将执行插入动作的瞬间，先让编辑器恢复焦点，再重新获取最新的光标范围。

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