JavaScript setRangeText 替换文本后怎样保留选区

在输入框里把选中的变量名替换成模板片段后，如果光标突然跳到末尾，通常不是替换失败，而是没有明确告诉 setRangeText() 替换完成后应该怎样处理选区。这个方法可以作用于 input 和 textarea：省略区间时使用当前选区，第四个参数用来决定新的选区落点。

官方地址：https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setRangeText

想保留原选区的相对位置，优先使用 setRangeText(replacement, start, end, "preserve")；想选中新插入文本用 select，想把光标放到插入文本前后分别用 start 或 end。

触发信号：文本替换成功但选区不对

先把问题拆成两层：第一层是 value 中哪一段被替换，第二层是替换后 selectionStart 和 selectionEnd 落在哪里。只盯着输入框显示内容，很容易把“替换区间传错”和“选区模式不合适”混成一个问题。

值班时可以先记录三个信号：替换前的 value、selectionStart/selectionEnd，以及调用时实际传入的 start/end。如果前两项正确而光标位置错误，优先检查第四个参数。

快速判断：替换区间是当前选区还是显式区间

start 和 end 都不传时，方法使用控件当前的 selectionStart 和 selectionEnd。传入后，它们表示从 start 开始、到 end 之前结束的 0-based 区间；也就是说，end 指向“最后一个被替换字符的后面”。

下面这个小函数适合把“当前选中的文本”替换成新内容，同时把选区策略作为调用方的明确决定。注释说明了半开区间和默认模式，避免后续维护时把参数位置写错。

function replaceCurrentSelection(control, replacement, mode = "preserve") {
  // selectionStart 和 selectionEnd 组成 [start, end) 半开区间。
  const start = control.selectionStart;
  const end = control.selectionEnd;

  // 显式传入四个参数，让替换范围和替换后的选区策略可追踪。
  control.setRangeText(replacement, start, end, mode);
}

const input = document.querySelector("#editor");
input.focus();
replaceCurrentSelection(input, "${name}", "preserve"); // 保留原选区的相对关系

如果业务就是替换用户当前选中的文本，也可以直接调用 control.setRangeText(replacement)。但在需要稳定复现光标行为的组件里，显式保存区间通常更容易排查。

处理步骤：四种 selectMode 怎样选择

第四个参数不是“是否选中”的布尔值，而是一个结果策略：

可以把模式写成组件配置，而不是散落在事件处理器里的字符串。这样当产品要求从“替换后继续输入”变成“替换后高亮检查”时，只需调整调用参数。

function insertToken(control, token, mode) {
  // 用当前选区作为替换边界，避免固定下标随文本变化而失效。
  const start = control.selectionStart;
  const end = control.selectionEnd;

  // mode 由调用方决定：preserve、select、start 或 end。
  control.setRangeText(token, start, end, mode);
}

const textarea = document.querySelector("#message");
textarea.focus();
insertToken(textarea, "{{user_name}}", "end"); // 插入后把光标放在 token 后

回滚路径：误替换时恢复 value 和选区

如果观察到替换片段不对，先不要继续点击按钮覆盖现场。调用前保存 value、selectionStart 和 selectionEnd，发现 start/end 计算错误时先恢复这三个状态，再修正区间计算。对中文、表情符号或组合字符，要特别注意：这些 DOM 下标按 JavaScript 字符串的 UTF-16 code unit 计数，不等同于用户看到的“字数”。

function snapshotSelection(control) {
  // 快照用于排障回滚，不把当前状态猜成固定下标。
  return {
    value: control.value,
    start: control.selectionStart,
    end: control.selectionEnd
  };
}

function restoreSelection(control, snapshot) {
  // 先恢复文本，再恢复选区，避免旧下标落在新文本之外。
  control.value = snapshot.value;
  control.setSelectionRange(snapshot.start, snapshot.end);
}

告警确认与复盘：把选区行为写进检查项

确认问题关闭前，至少覆盖“无选区插入”“选中一段文本替换”“显式 start/end 替换”“input 与 textarea”四种情况，并分别记录采用的模式。若只是想让光标稳定地接在新文本后，优先使用 end；若要让用户检查刚插入的内容，使用 select；只有确实需要保留原选区语义时才依赖 preserve 的默认行为。

最后记住两个边界：setRangeText() 返回 undefined，结果要从控件的 value 和选区状态观察；浏览器兼容性虽已较好，但组件仍应在目标浏览器中确认中文输入法、焦点转移和无障碍交互不会覆盖选区。

常见问题

为什么传了 replacement 却没有替换我选中的内容？

先检查调用时控件是否仍是焦点元素，再打印 selectionStart 和 selectionEnd。若传入了 start/end，实际替换的是显式区间，不再由当前选区决定。

preserve 和 end 应该怎么选？

需要尽量保持原选区关系时用 preserve；希望用户紧接着在新文本后继续输入时用 end。两者表达的是不同的交互意图，不是哪个更“正确”。