企业官网建设流程全解析

Lexical 富文本编辑器图片处理完整指南：上传、裁剪到持久化的实战与避坑

【免费下载链接】lexicalLexical is an extensible text editor framework that provides excellent reliability, accessibility and performance.项目地址: https://gitcode.com/GitHub_Trending/le/lexical

富文本编辑器的图片处理，是出 bug 最多的环节之一。本文以 Meta 的 Lexical 编辑器框架为例，完整拆解 Lexical 图片处理的完整链路：如何把一个选中的文件变成一条命令，如何落地拖拽裁剪，如何让图片在长文档里响应式展示，以及如何把图片数据写进持久化格式。

如果你正在做 CMS 或内容型产品，直接按这条链路走即可，不用每个环节自己重复造轮子。

图片节点的数据形态：src 与尺寸到底存哪

一个把渲染交给 React 的装饰器节点

很多人写图片上传，第一反应是先搭一个上传组件。其实更值得先搞清楚的是：在 Lexical 里，图片并不是一坨漂浮的对象，而是一段很朴素的数据。官方 playground 用ImageNode（继承DecoratorNode）来承载它，整个节点身上只有几个纯值字段：

class ImageNode extends DecoratorNode<JSX.Element> { __src: string; __altText: string; __width: 'inherit' | number; __height: 'inherit' | number; __maxWidth: number; createDOM(config: EditorConfig): HTMLElement { const span = $getDocument().createElement('span'); const className = config.theme.image; if (className !== undefined) { span.className = className; } return span; } decorate(): JSX.Element { return ( <ImageComponent src={this.__src} maxWidth={this.__maxWidth} ... /> ); } }

注意两处细节：createDOM只创建一个空 span 占位，真正的<img>由decorate()交给 React 组件渲染；正因为节点字段全是纯值，它可以原样序列化成 JSON，也才能天然支持撤销重做和多人协作。

exportJSON 决定了图片的落盘字段

换句话说，所谓"图片处理"，在数据层面就是对这些字段做增删改。把它按生命周期排一遍，思路会清楚很多：

记住这张表，后面所有场景你都能对号入座：加 src 是上传，改宽高是裁剪缩放，存盘就是序列化。

富文本编辑器图片上传：用命令系统串起选择与插入 📷

INSERT_IMAGE_COMMAND：UI 只管发命令，不管往哪插

理解数据形态后，上传链路的第一步是把"UI"和"插入逻辑"解耦。playground 的做法很干净——定义一条INSERT_IMAGE_COMMAND，任何入口（弹窗、拖拽、粘贴后的按钮）都只负责 dispatch，谁来消费、插到光标还是选中节点的位置，由注册命令的那一方决定：

export const INSERT_IMAGE_COMMAND: LexicalCommand<ImagePayload> = createCommand('INSERT_IMAGE_COMMAND'); editor.registerCommand(INSERT_IMAGE_COMMAND, (payload) => { $insertNodes([$createImageNode(payload)]); return true; }, COMMAND_PRIORITY_EDITOR); // 文件选择：统一转成 dataURL 后发命令 const reader = new FileReader(); reader.onload = () => { editor.dispatchCommand(INSERT_IMAGE_COMMAND, { src: String(reader.result), altText: file.name, }); }; reader.readAsDataURL(file);

这样上传逻辑与按钮、弹窗完全无关，同一个命令还能被快捷键、粘贴回调、协同邀请卡片复用。

拖拽上传：先分清"内部拖"和"外部拖"

图片入口除了文件对话框，还有 URL 直贴、外部文件拖入、剪贴板粘贴这几条：

• 文件对话框：accept="image/*"，选中后走readAsDataURL
• URL 直贴：先用new Image()的onload验证可访问，再插入
• 外部文件拖入：监听容器drop，用dataTransfer.types过滤出图片 MIME
• 粘贴图片：Lexical 的剪贴板管线会自动走img的 DOM 导入规则

避坑提示：Lexical 内置的DRAGSTART/DRAGOVER/DROP_COMMAND主要服务于"编辑器内部拖动节点"（playground 会把节点数据写进application/x-lexical-drag这个 MIME 类型）；外部文件落进编辑区，需要你在编辑器根元素上自己监听，且dragover里必须preventDefault()，否则drop根本不会触发。

Lexical 图片裁剪与拖拽缩放：在装饰层动手

拖拽缩放：resizer 只写 width 与 height 两个字段

Lexical 本身不附带裁剪组件，但节点模型让"缩放"变成了最便宜的实现：playground 的图片组件在右下角挂了个 resizer，mousemove时按拖拽距离算出新尺寸，直接调用node.setWidthAndHeight(nextWidth, nextHeight)。因为width/height支持'inherit'，初始状态下图片完全跟随容器，用户第一次拖拽之后才会落成具体数值——这个"惰性写尺寸"的设计值得抄。

插入前裁剪：用 canvas 出图，别让原图进文档

Lexical 图片裁剪类需求（按比例自动裁、用户框选裁切框），最好都发生在"插入之前"：用 canvas 的drawImage把裁剪区域画出来，再toBlob出一个新文件，最后才发INSERT_IMAGE_COMMAND。这样文档里存的永远是裁好的结果，节点字段不需要任何改动。

一个容易踩的坑是：canvas 裁出小图后，忘记同步改写width/height。下一次拖拽缩放会以旧尺寸做计算，图片观感会明显"跳一下"。裁剪回调里把新宽高一并写入即可；想让它自适应，直接写'inherit'。

响应式展示与图片懒加载：长文档不卡的关键

maxWidth 与 inherit：默认就不会撑破容器

插入之后，展示端的好消息是：默认行为已经是响应式的。ImageNode默认maxWidth: 500，width/height为'inherit'时，<img>随容器宽度等比收缩，移动端窄栏不会横向溢出。组件层再补一条max-width: 100%; height: auto，横竖屏切换基本不用操心。

图片懒加载的正确打开方式

长文档里图片多的时候，懒加载的正确姿势不是去改createDOM产出的 DOM，而是在decorate()返回的 React 组件里控制挂载时机：

• 占位元素先进 viewport 观察队列，进入可视区才挂载真实<img>
• 加载完成后disconnectobserver，组件卸载时一并清理
• src先放data-src，可见后再换入，避免不可见图片抢带宽
• 同文档多张图片复用同一套逻辑，节点模型零改动

数据持久化：把图片 URL 写进 editorState

editorState 序列化：图片字段跟着文档一起走

最后聊持久化。Lexical 的文档本质就是 editorState 的 JSON，而图片的src只是其中一个字段，所以持久化链路非常短：

import { serializedDocumentFromEditorState, editorStateFromSerializedDocument, } from 'lexical-file'; // 保存：图片 src 已在 editorState JSON 中 const doc = serializedDocumentFromEditorState(editor.getEditorState()); await saveToServer(doc); // 恢复：解析回去再 set，图片节点随之出现 const state = editorStateFromSerializedDocument(editor, doc); editor.setEditorState(state);

lexical-file 的 fileImportExport.ts 做的就是这件事：带上时间戳和版本号把 editorState 序列化成SerializedDocument，恢复时parseEditorState原路还原。图片节点连同它的src、宽高、alt 文本一起回到文档里。

先占位后回填：上传中的 pending 状态

生产环境里上传是异步的，别等上传完才插入节点。比较稳的做法是：插入时先用本地压缩后的 dataURL 占位，让用户可以继续写；上传完成后getWritable()换入 CDN 地址；刷新后如果发现还有 pending 节点，在恢复流程里把未完成的上传续上。

图片处理看起来是五个功能，落到 Lexical 里其实收敛成一条线：对节点字段做增删改，再对 editorState 做 JSON 序列化。把这条线抓住，上传、裁剪、展示与持久化的边界就清晰了。想看完整拖拽实现的话，可以直接读 ImagesExtension 的源码，playground 永远是最好的老师。

【免费下载链接】lexicalLexical is an extensible text editor framework that provides excellent reliability, accessibility and performance.项目地址: https://gitcode.com/GitHub_Trending/le/lexical