从零实现contenteditable富文本编辑器：核心原理与实战避坑指南

你有没有注意过，现在网页里那些能输入内容的“富文本区域”，不管界面做得多么花哨，底层几乎都站着一个低调到不行的HTML属性——contenteditable。博客后台的编辑器、协同文档的正文区、活动页面的可编辑卡片，甚至你正在用的聊天框里的表情回复，都可能是它的功劳。真正上手之后你会发现，让它“能打字”只需要一个单词，但让它“好用”几乎是把浏览器编辑机制的边边角角都翻了一遍。

这篇文章我想聊的重点不是“念文档”，而是把一个基于 contenteditable 的笔记编辑器从零做到能上线，中间会遇到哪些问题、浏览器为你做了什么、哪些地方必须你来兜底。适合正在做富文本编辑、内容创作后台或者协同编辑功能的同学参考，也适合刚入门前端、想搞懂“编辑到底是怎么发生的”的读者。内容偏实战，建议配合代码一起看。

1. 从输入框到富文本：contenteditable 到底改变了什么

1.1 一个属性让任意元素变成编辑器

先把最基础的部分说清楚。contenteditable 是 HTML 的全局属性，只要在元素上加上 contenteditable="true"，这个元素就变成了可编辑区域。比如下面这段代码，一个 div 直接就能在页面上输入文字：

html复制<div contenteditable="true">双击我，可以像编辑 word 一样改这里的内容</div>

跑一下你会发现，这是真正的“所见即所得”：输入的换行会保留，粘贴一段带格式的文字（比如从带标题样式的网页复制过来），它会把标题的层级也带进来，而不是像 textarea 那样只给一堆纯文本。这也是 contenteditable 和普通输入控件最本质的区别——它不把“文本”当输入单位，而是直接把一段可被浏览器编辑的 DOM 树交给你。

这种设计在早期是最省事的富文本方案：不需要维护一个虚拟模型，用户看到什么就改什么。但省事只是表象，等你要控制“用户能改什么”“改了之后保存成什么”“多端内容一致”的时候，才知道底层有多野。

1.2 和 textarea 不是替代关系，而是两套输入哲学

很多初学者会问：既然 textarea 也能多行输入，为什么还要用 contenteditable。答案是你要输入的“内容”到底是什么。

textarea 只接受纯文本，输入的是字符串，换行是 \n，加粗的“加粗”两个字到了 textarea 里就是普通文字，没有任何格式信息。而 contenteditable 生成的是 HTML 结构：

html复制<div contenteditable="true">
  <p>这是一段可以<b>加粗</b>的文字</p>
</div>

用户在界面上看到的“加粗”，在 DOM 里对应一个 <b> 标签或者 span style="font-weight: bold;"。这决定了后续保存格式、渲染回显、数据分享时的核心差异。

所以选型时逻辑很简单：

• 只需要纯文本，比如留言、评论、系统配置项，优先 textarea，简单可靠不踩坑。
• 需要段落、标题、加粗、列表、图片穿插，或者要输出带格式的 HTML，那基本绕不开 contenteditable。

1.3 可继承性和三个取值：true、false 与 plaintext-only

contenteditable 属性最让我吃过亏的一点是它的继承性。它不是一个独立开关，而是会向下传递的：当一个父容器设置为可编辑，里面的所有子元素默认也都是可编辑的。这通常没问题，但如果你在编辑器内部嵌了一个小插件需要“只读”，就要在子元素上显式设置 contenteditable="false" 把它“挖”出来。

html复制<div contenteditable="true">
  我可以编辑
  <div contenteditable="false">这里的按钮和提示文字不能改</div>
</div>

另外两个取值是 contenteditable="plaintext-only" 和 contenteditable="inherit"。其中 inherit 表示跟随父元素状态；而 plaintext-only 在部分浏览器里有效，它允许输入多行，但会去掉粘贴进来的格式，算是一个折中方案。不过兼容性不稳定，实际项目里我一般不会依赖它，而是在粘贴事件里手动处理（后面会细说）。

2. 你看到的“编辑”，其实是一条事件和光标组成的流水线

真正深入使用 contenteditable 之前，建议先建立一个心智模型：在这个区域里发生的一切用户交互，最终都归结为“修改 DOM 树”和“维护光标位置”这两件事。浏览器帮我们做了大量工作，但它的很多默认行为对业务来说并不友好。

2.1 输入事件的核心链条

一次最简单的按键输入，在可编辑区域里经历的关键节点是：

text复制keydown -> beforeinput -> 浏览器修改 DOM -> input

其中 beforeinput 是近几年才被广泛支持的拦截点，它给了我们一个改变默认输入行为的机会。事件对象里有一个关键属性 inputType，可以判断当前输入是插入文字（insertText）、删除（deleteContentBackward）、插入换行（insertParagraph），还是插入列表（insertOrderedList）等。

比如想在用户输入纯文本时，把可能出现的 HTML 符号转义，可以这样拦截：

javascript复制editor.addEventListener('beforeinput', (event) => {
  if (event.inputType === 'insertText' && event.data && event.data.includes('<')) {
    event.preventDefault();
    document.execCommand('insertText', false, event.data.replace(/</g, '&lt;'));
  }
});

很多团队不知道 beforeinput，只能在 input 事件之后再去做内容“修正”，这时候 DOM 已经变了，很容易出现闪烁和光标跳走的问题。所以尽量把逻辑前置到 beforeinput 去处理。

2.2 光标不是“光标”，而是一对 Range 端点

在 contenteditable 里，光标和我们平时看到的“一条竖线”是两回事。它本质上是 Selection 对象的起点和终点，也就是 Range 的 startContainer 和 endContainer。

这带来一个非常常见的坑：你用 JavaScript 对编辑器内部做一些操作（比如插入链接、替换文本）之后，如果不主动恢复光标位置，浏览器会把选区折叠到操作结果的位置，甚至干脆丢到编辑器的开头或结尾。用户就会感觉“打着字，输入位置突然跳走了”。

一个保底做法是在修改 DOM 前保存选中范围，之后恢复：

javascript复制function saveSelection() {
  const selection = window.getSelection();
  if (selection && selection.rangeCount > 0) {
    return selection.getRangeAt(0).cloneRange();
  }
  return null;
}

function restoreSelection(range) {
  const selection = window.getSelection();
  selection.removeAllRanges();
  selection.addRange(range);
}

这个技巧在实现插入链接、插入图片、自定义列表的时候几乎每次都要用到。

2.3 组合输入（IME）是逻辑判断的头号敌人

中文输入法下，用户敲拼音的过程中，编辑器内部会处于“组合状态”。此时如果你监听到 keydown 就去执行格式化或者内容校验，很容易打断输入法，甚至出现拼音打到一半被当作英文提交的诡异现象。

常见的判断方式是：

javascript复制editor.addEventListener('compositionstart', () => {
  isComposing = true;
});

editor.addEventListener('compositionend', () => {
  isComposing = false;
});

所有涉及“用户是否输入了某个字符”的逻辑，都要等 compositionend 之后再做。比如做标签输入，用户输入中文“标签”时，不能按每个拼音字母去匹配候选词，否则体验会非常碎。

2.4 execCommand：看似过时，却是为数不多的“正规军”

在 ContentEditable 领域有一个绕不开的 API：document.execCommand。虽然官方标记为废弃，但它依然是浏览器提供的、不需要自己实现选区扩展和 DOM 操作的格式化命令。最常用的几个：

javascript复制document.execCommand('bold');           // 加粗
document.execCommand('italic');         // 斜体
document.execCommand('underline');      // 下划线
document.execCommand('insertUnorderedList'); // 无序列表
document.execCommand('createLink', false, url); // 插入链接
document.execCommand('removeFormat');   // 清除格式

使用时的核心注意点是：执行前必须确保编辑器区域有焦点且有选区，否则很多浏览器会直接无事发生。另外，execCommand 执行后选区会折叠到格式化后的文本上，这也是为什么很多封装库会在每次命令后手动调整光标。

3. 实战复盘：一个轻量笔记编辑器的核心实现

我做过一个面向团队内部的笔记工具，编辑区就是一个 contenteditable。产品需求不算复杂：能输入多段文字，能加粗斜体，能插入链接，能加无序列表，附带图片粘贴上传，支持本地草稿保存。但就是这些“基础功能”，实现过程中踩了不少坑。

3.1 编辑器壳与工具栏设计

编辑器结构很简单，外层容器包裹工具栏和内容区：

html复制<div class="editor-wrapper">
  <div class="toolbar">
    <button data-command="bold">加粗</button>
    <button data-command="italic">斜体</button>
    <button data-command="insertUnorderedList">列表</button>
    <button data-command="createLink">链接</button>
    <button data-command="removeFormat">清除格式</button>
  </div>
  <div class="editor" contenteditable="true"></div>
</div>

工具栏按钮点击时，先给编辑器容器加上焦点，再执行命令：

javascript复制toolbar.addEventListener('click', (event) => {
  const button = event.target.closest('button');
  if (!button) return;
  const command = button.dataset.command;
  editor.focus();
  if (command === 'createLink') {
    const url = window.prompt('输入链接地址');
    if (url) document.execCommand('createLink', false, url);
  } else {
    document.execCommand(command);
  }
});

这套代码基本能跑通，但有一个问题非常明显：按钮点击会触发 blur，导致编辑器失焦，选区还没选区就被清了。所以工具栏常规操作是给按钮的 mousedown 事件加一个 event.preventDefault()，防止焦点从编辑器上移除：

javascript复制button.addEventListener('mousedown', (event) => {
  event.preventDefault();
});

这样处理之后，点击按钮不会让编辑器失焦，光标位置也就保住了。

3.2 加粗/斜体背后隐藏的 DOM 差异

execCommand('bold') 在 Chrome 和 Safari 里生成的 DOM 结构可能有差异：有的浏览器生成 <b>，有的生成 <strong>，有的生成 <span style="font-weight: bold;">。如果后续保存内容需要对 DOM 做校验或统一，不能只匹配一种标签。

我采取的方案是：保存前做一次标签归一化，把 <strong> 统一成 <b>，把 <span style="font-weight: bold;"> 也转成 <b>，这样后端存储的内容结构更可控。

javascript复制function normalizeDOM(html) {
  const template = document.createElement('template');
  template.innerHTML = html;
  template.content.querySelectorAll('strong').forEach((node) => {
    const b = document.createElement('b');
    b.innerHTML = node.innerHTML;
    node.replaceWith(b);
  });
  template.content.querySelectorAll('span').forEach((node) => {
    if (node.style.fontWeight === 'bold') {
      const b = document.createElement('b');
      b.innerHTML = node.innerHTML;
      node.replaceWith(b);
    }
  });
  return template.innerHTML;
}

3.3 列表与缩进：insertUnorderedList 的“惊喜”

insertUnorderedList 虽然名字看起来只负责插入无序列表，但它实际上是一个“切换”命令：你选中一段普通文本，点击之后变成 <ul><li>文本</li></ul>；再点击一次，它又恢复成普通段落。如果你的需求是“这个按钮只在选中内容不是列表时生效”，那就需要先判断当前选区是否在 li 内部。

javascript复制function isInsideList() {
  const selection = window.getSelection();
  if (!selection.rangeCount) return false;
  let node = selection.getRangeAt(0).startContainer;
  while (node && node !== editor) {
    if (node.tagName === 'LI') return true;
    node = node.parentNode;
  }
  return false;
}

另外一个很容易让用户崩溃的点是：在列表的最后一个项按回车，新行仍然带着列表符号。如果需要“回车退出列表”，通常要监听 keydown，在 Enter 被按下且当前 li 内容为空时，阻止默认行为并把 li 替换成空段落。

3.4 插入链接与清除格式时的光标抢救

这部分是调 bug 数最多的。插入链接后，内容确实变成了 <a href="...">文本</a>，但如果操作后不恢复 Range，后续再次输入会直接在链接内部继续，导致一堆嵌套链接和奇怪的样式。

保险的做法是在执行 createLink 前保存选区，命令执行后不要依赖浏览器的光标行为，自己定位到链接末尾：找到刚插入的 <a> 元素，把 Range 设置到它的末尾。

javascript复制function insertLink(url) {
  const savedRange = saveSelection();
  document.execCommand('createLink', false, url);
  const selection = window.getSelection();
  selection.removeAllRanges();
  const aTags = editor.querySelectorAll('a');
  const lastA = aTags[aTags.length - 1];
  if (lastA) {
    const range = document.createRange();
    range.setStart(lastA.firstChild || lastA, lastA.childNodes.length);
    range.collapse(true);
    selection.addRange(range);
  }
}

注意上面的简单方案只适合在末尾插入的场景，更严谨的做法是在操作前记录选区，操作后以选区起始位置为锚点去寻找新增的 <a> 节点。

3.5 禁用浏览器默认拼写检查和网络文本替换

线上笔记编辑器有一个很少人提前想到的问题：浏览器的自动拼写检查和“把网址自动变成链接”功能，会在编辑区域里“自作主张”。我的做法是在初始化的时候统一禁掉：

html复制<div
  contenteditable="true"
  spellcheck="false"
  autocorrect="off"
  autocapitalize="off"
  data-gramm="false"
  data-gramm_editor="false"
></div>

data-gramm 是给 Grammarly 扩展用的，虽然它不能保证彻底屏蔽所有浏览器扩展，但至少常规的拼写检查和自动链接可以关掉。

4. 粘贴、拖拽、移动端：内容进入的三个失控入口

4.1 粘贴带来的不只是文本，还有一整套“历史包袱”

用户从 Word 或者网页里复制内容粘贴进来时，浏览器默认会把源内容的所有格式都带过来。我见过最夸张的一次：粘贴进来一段十几行的文字，DOM 里出现了几百个嵌套的 <span style="...">，还有一些 Word 专用的 <o:p> 标签。如果这些内容直接被保存，后期渲染要么慢，要么样式全乱。

核心策略是：监听 paste 事件，拦截它，自己决定插入什么。

javascript复制editor.addEventListener('paste', (event) => {
  event.preventDefault();
  const htmlData = event.clipboardData.getData('text/html');
  const textData = event.clipboardData.getData('text/plain');
  if (htmlData) {
    const cleaned = cleanPastedHTML(htmlData);
    document.execCommand('insertHTML', false, cleaned);
  } else {
    document.execCommand('insertText', false, textData);
  }
});

4.2 完整清洗流程：从富文本到可接受的“纯净”HTML

我的 cleanPastedHTML 有一个递进式策略。第一步，把粘贴内容放进一个脱离文档的 template 里解析；第二步，移除危险标签和属性；第三步，如果是非允许标签，全部转换成 span 或保留文本；第四步，清掉空标签。

javascript复制function cleanPastedHTML(html) {
  const template = document.createElement('template');
  template.innerHTML = html;

  // 移除脚本、样式、对象等危险标签
  template.content.querySelectorAll('script,style,link,meta,iframe,object,embed').forEach((node) => node.remove());

  // 统一移除 onerror 等事件属性
  template.content.querySelectorAll('*').forEach((node) => {
    [...node.attributes].forEach((attr) => {
      if (attr.name.startsWith('on')) node.removeAttribute(attr.name);
    });
  });

  // 移除 Word 的兼容标签
  template.content.querySelectorAll('o\\:p, [class^="Mso"], [class*="Mso"]').forEach((node) => node.remove());

  return template.innerHTML;
}

对于允许的标签，我会设置白名单：p, br, div, b, strong, i, em, u, a, ul, ol, li。白名单之外的元素，如果是块级标签，替换为 p；如果是行内标签，保留其文本内容但去掉标签本身。这个策略不一定适合所有业务，但能有效控制保存内容的复杂度。

提示：清洗逻辑不能只在浏览器端完成。后端保存时必须再做一次同样的消毒，否则绕过前端可以直接提交恶意 HTML。

4.3 图片粘贴：base64 数据是个甜蜜的陷阱

笔记工具需要支持粘贴截图。浏览器会把图片转成 base64 数据塞进 img 的 src，直接粘贴是能显示，但如果你把整个 innerHTML 存到数据库，数据库会被撑爆。我这个项目选择的方式是：在 paste 事件里检测 image/png 或 image/jpeg，拿到数据后上传到对象存储，再把上传后的 URL 插回编辑器。

javascript复制editor.addEventListener('paste', async (event) => {
  const items = event.clipboardData.items;
  for (const item of items) {
    if (item.type.startsWith('image/')) {
      event.preventDefault();
      const file = item.getAsFile();
      const url = await uploadImage(file); // 伪代码，对接对象存储
      document.execCommand('insertHTML', false, `<img src="${url}" alt="粘贴图片" />`);
    }
  }
});

需要注意：粘贴图片时 clipboardData.items 里的 item 在异步处理时可能已经不可用，建议在 getAsFile() 之后立即把文件对象存下来，后续只操作文件。

4.4 拖拽：默认行为有时是帮倒忙

可编辑区域默认支持拖拽图片和文本。但默认行为往往不可控——文本拖拽可能变成移动而不是复制，图片拖拽则可能跳转。推荐统一接管 dragover 和 drop：

javascript复制editor.addEventListener('dragover', (event) => event.preventDefault());
editor.addEventListener('drop', (event) => {
  event.preventDefault();
  const files = event.dataTransfer.files;
  if (files.length > 0) {
    // 走图片上传逻辑
  }
});

这能避免很多不可预期的行为，也让加载中的图片不会莫名变成一个新标签页。

4.5 移动端光标的“自由发挥”

移动端浏览器处理 contenteditable 的策略差异比较大。最典型的问题是：在部分安卓浏览器里，连续输入中文时，光标位置会偶尔跳到段落开头；另一个坑是点击图片会触发系统选择的遮罩层，造成选区计算混乱。

我的经验是：移动端尽量少依赖 keydown 做复杂逻辑，多依赖 input 事件 + requestAnimationFrame 延后处理；图片插入后用 img[contenteditable="false"] 包裹，避免图片被光标选中后导致整块内容“翻车”。

5. 保存、安全与框架协作：让编辑器真正可用于产品

5.1 保存前的 HTML 规范化

用户的随意操作会让编辑器内部 DOM 变得非常“脏”。保存之前我会做几件固定的事：

• 把 <div> 替换成 <p>，保证不同浏览器下段落结构一致。
• 删除 class 和 id，除非这是业务需要的标记。
• 合并相邻的 style 属性，能转成标签的优先转成标签。
• 去掉空白文本节点中不必要的部分，避免前后端对比时总是 diff 失败。

这个规范化过程不能只在编辑结束时时做，最好在初始化编辑器时也做一次（比如从服务端加载已有内容时），这样编辑起点就是干净的。

5.2 XSS 不是开玩笑，消毒必须做两层

contenteditable 保存的内容本质是 HTML，直接渲染到页面上的危险程度等同于直接设置 innerHTML。我曾见过有人通过粘贴内容注入了一个 <img onerror="alert(1)">，虽然前端清洗拦截了一部分，但后来发现绕过前端直接提交接口仍然能成功。

所以安全策略必须包含两层：

1. 前端清洗：过滤粘贴和编辑过程中产生的非法标签、属性、事件。
2. 后端消毒：保存时用服务端白名单过滤（可以用 DOMPurify 之类工具的逻辑，也可以让后端参与校验）。

后端永远不能相信前端校验，这是原则。

5.3 防抖保存与内容快照

编辑器内部有 input 事件，但每次输入都去保存不太现实，我会做防抖，比如停止输入 800ms 之后保存一次草稿：

javascript复制let timer = null;
editor.addEventListener('input', () => {
  clearTimeout(timer);
  timer = setTimeout(() => {
    const content = normalizeDOM(editor.innerHTML);
    localStorage.setItem('note_draft', content);
  }, 800);
});

这里要注意：保存内容时如果直接调用 editor.innerHTML，用户可能刚好在输入过程中，内容处于组合状态，保存的可能是半截拼音。所以在 compositionend 之前不要执行保存逻辑，或者保存时用 isComposing 做一次判断。

5.4 与前端框架共存：光标丢失问题

如果用 React 或 Vue 管理页面，最让人头疼的是框架重新渲染导致光标丢失。一个经典场景是：编辑器输入一个字符后，某个状态变化触发了 setState，然后又触发虚拟 DOM diff，React 把 contenteditable 里的 DOM 重新更新，光标瞬间消失。

我的建议是：能隔离就隔离。编辑器区域不要由框架频繁控制，内部 DOM 变更让浏览器自己管；如果必须从外部更新内容（比如加载数据、清空内容），只在特定时机设置 innerHTML，不要每次渲染都赋值。

javascript复制// React 中不建议这样频繁赋值
// 编辑器内容一旦交给 React 的 children，就很容易在 diff 时重置光标
<div contenteditable dangerouslySetInnerHTML={{ __html: state.content }} />

更稳妥的办法是把 contenteditable 区域当作一个“不受控”组件，外部数据只在初次挂载或显式重置时写入。

5.5 占位文本和可访问性

contenteditable 没有原生 placeholder 属性，空内容时通常用 CSS :empty::before 做占位：

css复制.editor:empty::before {
  content: "请输入内容…";
  color: #aaa;
}

但要注意，如果编辑区域内有空的 p 标签或 br 标签，:empty 选择器不会生效，需要处理空结构。此外，给可编辑区域加上 aria-label 或 role="textbox" 能提升屏幕阅读器的体验。

6. 几个让我“长记性”的小细节

最后补几个不太起眼但实际项目里很关键的细节，都是我踩过之后才注意到的。

第一，contenteditable 内部如果出现用户在行首按 Enter，不同浏览器会生成不同的标签：Chrome 有时是 <div>，Firefox 有时是 <br>。如果你对最终 HTML 的段落结构有严格要求，建议在 keydown 里拦截 Enter，手动使用 document.execCommand('insertHTML', false, '<p><br></p>') 保证结构统一。

第二，设置 caret-color 可以改变光标颜色。如果你把编辑器背景调成深色，默认的黑色光标会看不清，这不是 bug，是样式没跟上。

css复制.editor {
  caret-color: #fff;
}

第三，执行 execCommand('removeFormat') 时，它不会清除链接。想要彻底剥离链接，需要自己遍历选区里的 a 标签并 replaceWith 其文本内容。这和大多数用户的直觉不一致，但浏览器就是这样做的。

第四，不要在 keydown 事件里直接 preventDefault() 所有按键，否则会影响组合输入、系统快捷键和自定义键盘操作。拦截要尽可能精确，最好通过 event.key、event.code 和 isComposing 共同判断。

第五，编辑器初始有默认的 outline 样式，在 :focus 时浏览器会画一个蓝色的焦点框。很多组件库会顺手去掉，但如果你把它去掉，记得自定义一个明显的焦点样式，无障碍要求下这一点很重要。

做 contenteditable 相关功能最耗时间的往往不是“实现”，而是“兜底”。浏览器的默认行为、用户的手滑操作、各种扩展的自动介入，都可能在不知不觉中改变你的内容结构。但换个角度看，正是这些不确定性让这个领域即使这么多年过去，仍然有很多值得打磨的细节。如果你正在做一个和富文本编辑相关的项目，希望这篇文章能帮你少走一些弯路。