Lexical 富文本编辑器 iframe 嵌入实战:基于 vanilla-js-iframe 示例的零框架接入指南

原创2026-09-11 23:10:431,957 阅读
文章标签:前端富文本UI组件设计系统

Lexical 富文本编辑器 iframe 嵌入实战:基于 vanilla-js-iframe 示例的零框架接入指南

导读

本文以开源仓库 Lexical(examples/vanilla-js-iframe/README.md)中的 vanilla-js-iframe 示例为蓝本,讲解如何在完全不借助 React / Vue 等框架绑定层的前提下,用原生 TypeScript 将 Lexical 富文本编辑器嵌入 <iframe> 中运行。读完本文,你将掌握 @lexical/rich-text、@lexical/history、@lexical/dragon 三个核心包的注册方式、iframe 内容注入技巧、编辑器初始状态的程序化填充,以及如何通过更新监听器构建一个"所见即所得"的编辑器状态调试视图。

示例概览:最简单的 iframe 富文本编辑器

该示例的核心卖点在于"简单"与"隔离"并存:它只依赖 5 个 Lexical 相关 npm 包,且编辑器的 contentEditable 表面被完整放置在 iframe 内部,从而与宿主页面(示例本身的主文档)在样式与脚本层面天然隔离。

从 package.json 可以看到完整的依赖清单(版本 0.50.0):

包名 作用
lexical 编辑器核心框架
@lexical/rich-text 富文本能力(Heading、Quote 节点及 registerRichText 插件)
@lexical/history 撤销/重做历史记录
@lexical/dragon Dragon NaturallySpeaking 语音/无障碍输入支持
@lexical/utils 工具函数(mergeRegister)

运行方式非常简单,按 README 给出的命令即可本地启动(采用 Vite 作为开发服务器):

pnpm i && pnpm run dev

在 monorepo 仓库根目录下,也可以使用专门为仓库内联开发准备的脚本 pnpm run monorepo:dev,它会加载 vite.config.monorepo.ts 中配置的 lexicalMonorepoPlugin(来自 scripts/vite/lexicalMonorepoPlugin.ts),让示例直接引用仓库内的 Lexical 源码而非已发布的 npm 包。

页面结构:用 <template> + iframe 承载编辑器

查看 index.html,页面结构体现了两个关键设计:

  1. 编辑器 DOM 定义在 <template id="app-template"> 中:模板内包含一个 contenteditable 的 #lexical-editor 容器和一个用于展示编辑器状态的 #lexical-state 文本域。模板在 HTML 解析时不会渲染、也不会被搜索引擎或外部样式污染,是一个干净的"编辑器外壳"。
  2. iframe 铺满整个视口:#app-iframe 通过 position: absolute 配合 left/top/right/bottom: 0 实现全屏铺开,border: none 去除边框。
<template id="app-template">
  <h1>Lexical Basic - Vanilla JS iframe</h1>
  <div class="editor-wrapper">
    <div id="lexical-editor" contenteditable></div>
  </div>
  <h4>Editor state:</h4>
  <textarea id="lexical-state"></textarea>
</template>
<iframe id="app-iframe" width="100%" height="100%" style="..."></iframe>

提示:模板中的 #lexical-state 文本域是纯调试用途,它实时展示编辑器的 JSON 状态,方便观察 Lexical 内部的状态结构。

核心逻辑逐行拆解

src/main.ts 是整份示例的核心,整个初始化流程可拆为四个阶段。

阶段一:将模板注入 iframe 文档

const template = document.querySelector<HTMLTemplateElement>('#app-template')!;
const iframe = document.querySelector<HTMLIFrameElement>('#app-iframe')!;
const iframeDoc = iframe.contentDocument!;
iframeDoc.body.replaceChildren(iframeDoc.importNode(template.content, true));
const editorRef = iframeDoc.querySelector<HTMLDivElement>('#lexical-editor')!;
const stateRef = iframeDoc.querySelector<HTMLTextAreaElement>('#lexical-state')!;

这里使用 Document.importNode(template.content, true) 深拷贝模板内容,再 replaceChildren 进 iframe 的 body。随后在 iframe 的 document 作用域内查询编辑器挂载点 #lexical-editor 与状态展示区 #lexical-state。这是 iframe 方案与普通方案最核心的差异点:所有 DOM 查询与后续编辑器挂载,都必须针对 iframe.contentDocument 进行,而不是主文档。

阶段二:创建编辑器实例并挂载

const initialConfig = {
  namespace: 'Vanilla JS Demo',
  nodes: [HeadingNode, QuoteNode],
  onError: (error: Error) => {
    throw error;
  },
  theme: {
    quote: 'PlaygroundEditorTheme__quote',
  },
};
const editor = createEditor(initialConfig);
editor.setRootElement(editorRef);

createEditor 接收的配置项含义:

  • namespace:编辑器命名空间,用于区分同一页面上多个编辑器实例;
  • nodes:注册 @lexical/rich-text 专属的 HeadingNode(标题)与 QuoteNode(引用)节点,这是富文本能力的节点基础;
  • onError:错误处理回调,示例选择直接抛出以便尽早发现问题;
  • theme:样式类名映射,这里把 quote 节点映射到 styles.css 中定义的 PlaygroundEditorTheme__quote 类,为其提供左侧边框、缩进等视觉样式。

editor.setRootElement(editorRef) 将 iframe 内部的 #lexical-editor 指定为编辑器根元素,Lexical 会在其上建立 contentEditable 表面。

阶段三:注册插件(rich-text / dragon / history)

mergeRegister(
  registerRichText(editor),
  registerDragonSupport(editor),
  registerHistory(editor, createEmptyHistoryState(), 300),
);

mergeRegister(实现见 packages/lexical/src/utils/mergeRegister.ts)接收一组"注册函数",每个函数执行后返回其对应的清理函数;mergeRegister 会合并返回一个统一的清理函数,便于在组件卸载或编辑器销毁时一次性反注册所有监听器。

三个注册函数分别对应三个包:

  • registerRichText(editor)(packages/lexical-rich-text/src/index.ts):为编辑器注册富文本能力——键入时自动生成段落、标题、引用节点,以及加粗/斜体/代码等文本格式(escapeFormatTriggers、shouldHandlePasteAsFiles 等可选参数可进一步定制行为);
  • registerDragonSupport(editor)(packages/lexical-dragon/src/index.ts):接入 Dragon NaturallySpeaking 语音输入支持,提升辅助功能与可访问性;
  • registerHistory(editor, createEmptyHistoryState(), 300)(packages/lexical-history/src/index.ts):注册撤销/重做历史记录,第二个参数传入 createEmptyHistoryState() 创建的初始历史状态,第三个参数 300 表示"合并延迟"——即连续输入间隔小于 300ms 的按键会合并为同一个历史记录条目,从而让一次连续打字只占一次撤销步长。

阶段四:程序化填充初始内容

editor.update(prepopulatedRichText, {tag: HISTORY_MERGE_TAG});

editor.update 是 Lexical 在非用户交互场景下修改编辑器状态的标准方式(用户输入走的是编辑器的合成事件管线)。这里传入的更新函数来自 src/prepopulatedRichText.ts:

export default function $prepopulatedRichText() {
  const root = $getRoot();
  if (root.getFirstChild() !== null) {
    return;
  }
  // ...构建 h1 标题、引用、带 code/bold/italic 格式的段落
}

其中 $getRoot() 等 $ 前缀函数是 Lexical 的"更新作用域"API,只能在 update / read 等上下文中调用;函数开头对 root.getFirstChild() !== null 的防御判断,确保编辑器已有内容时不会重复填充。

值得注意的细节:更新选项 {tag: HISTORY_MERGE_TAG} 使用 HISTORY_MERGE_TAG(从 lexical 核心包导入)作为标记,它告诉历史插件"这是一次初始化性质的状态变更,应与后续操作合并处理",避免把初始化写入单独的历史条目、干扰用户的撤销体验。

状态调试视图:监听更新并序列化

editor.registerUpdateListener(({editorState}) => {
  stateRef!.value = JSON.stringify(editorState.toJSON(), undefined, 2);
});

registerUpdateListener 在每次编辑器状态更新后触发,示例将 editorState.toJSON() 序列化为格式化 JSON 写入 iframe 底部的 #lexical-state 文本域。你可以一边输入一边观察状态如何变化,这是理解 Lexical 状态模型的极佳调试入口。

iframe 场景下的样式与细节

  • 编辑器相关样式定义在 styles.css:.editor-wrapper 提供灰色边框容器,#lexical-state 固定为 300px 高的调试区,.PlaygroundEditorTheme__quote 通过左边框、缩进与颜色让引用节点具备可视化区分度;
  • 由于编辑器 DOM 位于 iframe 内部,宿主页的全局样式不会泄漏进编辑器(反之亦然),这是该示例"iframeless 干扰"的设计初衷;
  • contenteditable 属性直接写在模板中的 #lexical-editor 上,Lexical 挂载后接管其行为。

运行与构建

npm scripts 一览(见 package.json):

命令 说明
pnpm run dev Vite 开发服务器(使用 vite.config.ts,空配置)
pnpm run monorepo:dev 以 monorepo 模式启动,引用仓库内 Lexical 源码热更新
pnpm run build 先执行 tsc 类型检查,再执行 vite build 产出生产包
pnpm run preview 本地预览构建产物

TypeScript 侧(tsconfig.json)采用 moduleResolution: "bundler"、strict: true 与 noEmit,符合 Vite 生态的标准配置。

总结:从示例到你的项目

vanilla-js-iframe 展示了一条清晰的 Lexical 无框架接入路径,可直接迁移到任意需要富文本能力、又不想引入 React 绑定的项目(如 Web Component、原生 JS 页面、微前端 iframe 应用):

  1. 用 <template> + iframe 隔离编辑器 DOM;
  2. createEditor(initialConfig) 创建实例并 setRootElement 挂载;
  3. 用 mergeRegister 组合 registerRichText、registerHistory、registerDragonSupport 等插件;
  4. 通过 editor.update(fn, {tag: HISTORY_MERGE_TAG}) 程序化写入初始内容;
  5. 用 registerUpdateListener 实现状态序列化与调试。

参考配套示例(同样采用无框架 + iframe 思路的还有 shadow-dom 示例 与 shadow-dom-web-component 示例),可以进一步探索 Lexical 在隔离渲染环境中的更多玩法。

登录后查看全文
lexical