Payload 与 Lexical 富文本编辑器完全指南payloadcms/richtext-lexical 的安装、配置与功能扩展【免费下载链接】payloadPayload is the open-source, fullstack Next.js framework, giving you instant backend superpowers. Get a full TypeScript backend and admin panel instantly. Use Payload as a headless CMS or for building powerful applications.项目地址: https://gitcode.com/GitHub_Trending/pa/payloadpayloadcms/richtext-lexical 是 Payload 官方为 LexicalMeta 开源的富文本框架开发的富文本编辑器适配器为 Payload CMS 的richText字段提供编辑与序列化能力。本文以该包的 README 为骨架结合仓库内的源码、类型定义与配套文档系统讲解它的安装方式、接入 Payload 配置的两种写法、lexicalEditor的四个核心参数、基于 Feature 的扩展模型、默认启用的功能清单以及客户端/服务端渲染与内容转换的使用要点帮助你把一个默认可用的富文本编辑器逐步改造成贴合业务需求的定制化编辑器。一、包定位Payload 官方的 Lexical 富文本适配器在 Payload 体系中富文本能力并不内置在核心包里而是通过「编辑器适配器」的形式提供。payloadcms/richtext-lexical就是官方维护的那一个它的package.json中description字段写得很直白“The officially supported Lexical richtext adapter for Payload”。查看 packages/richtext-lexical/package.json 可以看到包名payloadcms/richtext-lexical仓库内当前版本为4.0.0-canary.14许可证MIT与 Lexical 相关依赖锁定在0.48.0lexical、lexical/headless、lexical/html、lexical/link、lexical/list、lexical/markdown、lexical/react、lexical/rich-text、lexical/table、lexical/utils等均为同一版本peerDependencies要求payload、React^19.0.1 || ^19.1.2 || ^19.2.1、react-dom同版本以及 UI 相关的faceless-ui/modal、faceless-ui/scroll-infoengines.node要求 24.15.0在仓库根目录的 docs/getting-started/concepts.mdx 与 docs/migration-guide/v4.mdx 中同样印证了它在 Payload 生态中的地位从 Payload 4.0 起payloadcms/richtext-lexical是唯一受官方支持的富文本编辑器旧的payloadcms/richtext-slate包已被移除。说明本仓库是一个包含packages/richtext-lexical源码、docs/文档与test/测试在内的 Payload monorepo。下文提到的配置示例、功能清单与代码路径均来自仓库当前状态适用时以仓库实际代码为准。二、安装与依赖环境README 给出了最简安装命令npmnpm install payloadcms/richtext-lexical由于本仓库使用 pnpm workspace 管理docs/rich-text/overview.mdx 也提供了 pnpm 与“常用编辑器周边包一并安装”的写法# 使用 pnpm 安装 pnpm install payloadcms/richtext-lexical # 安装富文本编辑器 图片处理 GraphQL如果用到 pnpm i payloadcms/richtext-lexical sharp graphqlgetting-started/installation.mdx 还提醒如果你完全不使用富文本也可以不安装本包。安装时需要留意几个由 packages/richtext-lexical/package.json 明示的运行前提项目要求Node.js 24.15.0Payload作为 peer dependency仓库中以workspace:*关联React / React DOM^19.0.1 || ^19.1.2 || ^19.2.1Lexical 系列依赖统一为0.48.0由包自身带齐无需手动安装三、接入 Payload根配置与逐字段配置README 中的 Usage 展示了最核心的接入方式——在buildConfig中把lexicalEditor()赋给顶层的editor字段import { buildConfig } from payload import { lexicalEditor } from payloadcms/richtext-lexical export default buildConfig({ editor: lexicalEditor({}), // ...rest of config })editor一旦在根配置中声明所有type: richText字段默认都会使用这个编辑器。官方文档 docs/rich-text/overview.mdx 补充了两个实用细节一个配置就够了不需要为每个字段重复声明——顶层配置中的编辑器会作为全局默认。你可以按字段覆盖设置。例如在某个 Collection 里给content字段单独传入另一个lexicalEditor(...)字段级配置会覆盖而不是合并全局配置import type { CollectionConfig } from payload import { lexicalEditor } from payloadcms/richtext-lexical export const Pages: CollectionConfig { slug: pages, fields: [ { name: content, type: richText, // 在此字段上使用可以覆盖顶层设置的Lexical 编辑器 editor: lexicalEditor({}), }, ], }为什么字段级配置的覆盖能力这么强因为从源码结构看richText字段本身就只是一个普通字段类型它的editor属性可以指向任意实现了 PayloadRichTextAdapter接口的对象。lexicalEditor()返回的正是一个这样的适配器 Provider见 packages/richtext-lexical/src/types/index.ts 中LexicalRichTextAdapterProvider的定义Payload 在配置净化sanitization阶段会调用它并注入净化后的全局config从而得到包含editorConfig与features的LexicalRichTextAdapter该调用链可在 packages/richtext-lexical/src/index.ts 看到。另外要提醒的是如果整个项目的富文本统一使用同一套设置直接在根editor配置即可只有像“内容区用全功能编辑器、摘要区只允许纯段落”这类差异化诉求才适合在字段级单独配置。四、lexicalEditor 的可配置参数lexicalEditor接受一个可选的LexicalEditorProps参数对象。从 packages/richtext-lexical/src/types/index.ts 可以看到它的完整形状export type LexicalEditorProps { admin?: LexicalFieldAdminProps features?: FeaturesInput lexical?: LexicalEditorConfig views?: PayloadComponent }admin管理后台表现admin用来控制编辑器在 Admin Panel 中的界面表现。对应类型LexicalFieldAdminProps见 packages/richtext-lexical/src/types/index.ts提供了如下选项属性默认值作用placeholder-编辑器为空时显示的占位文案LabelFunction或静态文本hideGutterfalse隐藏编辑器左侧的沟槽灰色竖线与内边距区域hideInsertParagraphAtEndfalse隐藏编辑器末尾出现的“”按钮快速插入段落hideDraggableBlockElementfalse隐藏悬停节点时出现的拖拽手柄hideAddBlockButtonfalse隐藏悬停节点时出现的“添加块”按钮官方文档 docs/rich-text/overview.mdx 给出了两个最常见的用法示例{ name: richText, type: richText, editor: lexicalEditor({ admin: { hideGutter: true, // 关闭左侧沟槽让内容更贴近页面边缘 }, }), }{ name: richText, type: richText, editor: lexicalEditor({ admin: { placeholder: Type your content here..., // 自定义空状态占位文案 }, }), }features扩展与裁剪能力features是本包最重要的扩展点。它既可以是一个 Feature 数组也可以是一个接收{ defaultFeatures, rootFeatures }并返回数组的函数对应类型FeaturesInput见 packages/richtext-lexical/src/types/index.tseditor: lexicalEditor({ features: ({ defaultFeatures }) [...defaultFeatures, FixedToolbarFeature()], })两个回调参数的语义参数含义defaultFeatures官方推荐的“默认功能”数组。展开它们可以得到一个功能完整的开箱即用编辑器也可以从中删掉某些功能实现精简rootFeatures根富文本编辑器在根payload.config.ts中定义的那个已启用的功能数组。如果当前字段就是根编辑器或根编辑器不是 Lexical则该数组为空lexical底层 Lexical 配置lexical可以直接覆盖 Lexical 引擎本身的EditorConfig主题theme、节点注册等。如果你想在改一小点的同时又保留默认配置最稳妥的方式是用“接收默认配置并返回新配置”的函数写法。文档 packages/richtext-lexical/src/types/index.ts 中的类型注释给出了示例lexical: (defaultConfig) ({ ...defaultConfig, theme: { ...defaultConfig.theme, paragraph: my-paragraph }, })views多视图渲染views允许为同一批 Lexical 节点定义多套渲染逻辑如default、preview、debug等命名视图在编辑器与 JSX 转换器之间保持一致渲染。它以带#exportName的导入路径字符串指定视图映射文件例如文档 docs/rich-text/overview.mdx 中editor: lexicalEditor({ // 使用 ./views.js 中导出的 postViews 视图映射 views: ./views.js#postViews, }),五、Feature 机制默认能力与自定义扩展默认包含哪些 Feature调用lexicalEditor({})且不传features时源码会直接使用defaultEditorFeatures见 packages/richtext-lexical/src/index.ts它来自 packages/richtext-lexical/src/lexical/config/server/default.ts。该默认数组在当前仓库中包含类别Feature行内格式BoldFeature()、ItalicFeature()、UnderlineFeature()、StrikethroughFeature()、SubscriptFeature()、SuperscriptFeature()、InlineCodeFeature()块结构ParagraphFeature()、HeadingFeature()、AlignFeature()、IndentFeature()、BlockquoteFeature()、HorizontalRuleFeature()列表UnorderedListFeature()、OrderedListFeature()、ChecklistFeature()内容引用LinkFeature()、RelationshipFeature()、UploadFeature()工具栏InlineToolbarFeature()从源码的默认列表看仓库并未把FixedToolbarFeature()计入默认——也就是说默认是行内浮动工具栏。如果你习惯固定在顶部的工具栏需要手动追加import { FixedToolbarFeature, lexicalEditor } from payloadcms/richtext-lexical editor: lexicalEditor({ features: ({ defaultFeatures }) [...defaultFeatures, FixedToolbarFeature()], })若把defaultFeatures整个清空得到的就是一个近乎空白的编辑器——这正是 Feature 模型的意义需要什么就加什么甚至可以从零构建自定义 Feature官方仓库中features与toolbars等目录的源码结构可作为自行实现的参考见 packages/richtext-lexical/src/features。用官方 Feature 组装复杂编辑器在根编辑器上扩展能力时最典型的做法是把BlocksFeature复用 Payload Block 作为富文本块、LinkFeature、UploadFeature一起组合进去。仓库文档 docs/rich-text/overview.mdx 给出了一个完整的例子import { BlocksFeature, LinkFeature, UploadFeature, lexicalEditor, } from payloadcms/richtext-lexical import { Banner } from ../blocks/Banner import { CallToAction } from ../blocks/CallToAction { editor: lexicalEditor({ features: ({ defaultFeatures, rootFeatures }) [ ...defaultFeatures, LinkFeature({ // 演示如何给 LinkFeature 内置的字段追加自定义字段 fields: ({ defaultFields }) [ ...defaultFields, { name: rel, label: Rel Attribute, type: select, hasMany: true, options: [noopener, noreferrer, nofollow], admin: { description: The rel attribute defines the relationship between a linked resource and the current document., }, }, ], }), UploadFeature({ collections: { uploads: { // 演示如何给上传节点追加字段 fields: [ { name: caption, type: richText, editor: lexicalEditor(), }, ], }, }, }), // 直接复用 Payload 的 Block 作为富文本内容块 BlocksFeature({ blocks: [Banner, CallToAction], }), ], }) }提示将BlocksFeature纳入编辑器后前端渲染时仍会按 Payload Block 的模式读取字段数据。官方功能的全量介绍见仓库内的 docs/rich-text/official-features.mdx自定义 Feature 的开发指引见 docs/rich-text/custom-features.mdx。六、源码视角lexicalEditor 运行时做了什么深入阅读入口 packages/richtext-lexical/src/index.ts 可以帮助你理解这套配置体系背后的机制版本一致性检查。非生产环境且未设置环境变量PAYLOAD_DISABLE_DEPENDENCY_CHECKERtrue时首次调用lexicalEditor会执行checkDependencies将lexical与各lexical/*包的版本统一约束到lexicalTargetVersion 0.48.0见index.ts中lexicalTargetVersion常量与相关逻辑。如果项目中残留多个不同版本的 lexical会在开发期得到明确告警。配置净化sanitization。若未传args或既没传features也没传lexical则直接采用缓存过的getDefaultSanitizedEditorConfig与defaultEditorFeatures否则进入featuresInputToEditorConfig把函数式/数组式的features输入解析成按依赖排序的 feature 列表与去重的解析结果映射相关实现见 packages/richtext-lexical/src/utilities/editorConfigFactory.ts。i18n 注入。每个 Feature 可以携带自己的多语言词条。lexicalEditor会把它们按当前 config 支持的语言合并进全局config.i18n.translations通过deepMergeSimple保证管理后台出现的新按钮文案随语言切换index.ts中可见featureI18n、supportedLanguagesToMerge等处理逻辑。返回一套完整适配器。最终返回的对象同时提供服务端渲染所需的editorConfig、features管理后台的字段/单元格组件如RscEntryLexicalField、RscEntryLexicalCell通过payloadcms/richtext-lexical/rsc子路径引用、GraphQL 关联数据填充逻辑graphQLPopulationPromises、字段 hooks、JSON Schema 以及验证函数richTextValidateHOC。也就是说编辑、存储校验、GraphQL 查询和类型生成全都在适配器层被串联起来了。公开的类型与工具。index.ts还导出了大量序列化节点类型、Feature 类型与实用函数例如convertHTMLToLexical、convertLexicalToMarkdown、convertMarkdownToLexical、buildEditorState、hasText等供上层按需引入。七、数据格式、类型与前端渲染存储与读取格式富文本内容在数据库中保存的是 Lexical 序列化 JSON而不是 HTML。要交给浏览器渲染时需要走转换器。README 所指的“更详细用法见官方文档”在仓库里对应的是 docs/rich-text/overview.mdx、docs/rich-text/converting-html.mdx、docs/rich-text/converting-markdown.mdx 与 docs/rich-text/rendering-on-demand.mdx 等页面。类型安全包为每一个节点都导出了以Serialized前缀命名的类型例如SerializedParagraphNode、SerializedTextNode、SerializedLinkNode、SerializedUploadNode、SerializedBlockNode。类型化的编辑器状态可以这样构造示例见 docs/rich-text/overview.mdximport type { TypedEditorState, SerializedParagraphNode, SerializedTextNode } from payloadcms/richtext-lexical const state: TypedEditorStateSerializedParagraphNode | SerializedTextNode { root: { type: root, direction: ltr, format: , indent: 0, version: 1, children: [ { children: [ { detail: 0, format: 0, mode: normal, style: , text: Some text. Every property here is fully-typed, type: text, version: 1, }, ], direction: ltr, format: , indent: 0, type: paragraph, textFormat: 0, version: 1, }, ], }, }如果你启用了类型生成payload generate:types那么每个richText字段的类型会被自动按该编辑器实际启用的功能收敛成精确的节点联合例如Post[richText]配合buildEditorStatePost[richText]({ text: Hello world })即可类型安全地构造初始状态而无需手工拼一个巨大的节点联合。相关辅助类型DefaultTypedEditorState、RichTextNodes等都从payloadcms/richtext-lexical主入口导出。判空工具一个容易踩的坑是内容被清空后字段值不是null而是一个“只含空段落”的 JSON 对象。文档 docs/rich-text/overview.mdx 推荐使用专门的判空工具import { hasText } from payloadcms/richtext-lexical/shared hasText(richtextData)渲染到 HTML服务端按需渲染最直接的方式是用 HTML 转换器子路径payloadcms/richtext-lexical/htmlimport { convertLexicalToHTML } from payloadcms/richtext-lexical/html const html convertLexicalToHTML({ data: post.richText })八、子路径导出一览与 Payload 的管理后台和前端渲染架构相匹配本包提供了非常细化的 package exports。参考 packages/richtext-lexical/package.json常用的子路径如下子路径用途payloadcms/richtext-lexical主入口lexicalEditor、全部 Feature、序列化类型与核心工具payloadcms/richtext-lexical/client管理后台可用的客户端组件与 Hooks如块组件 UI 原语payloadcms/richtext-lexical/reactReact 渲染相关导出payloadcms/richtext-lexical/rscReact Server Components 入口RSC 字段/单元格组件payloadcms/richtext-lexical/htmlHTML 转换convertLexicalToHTMLpayloadcms/richtext-lexical/html-async异步 HTML 转换含lexicalHTMLField同步字段等payloadcms/richtext-lexical/plaintext纯文本转换payloadcms/richtext-lexical/lexical直通lexical及lexical/*各子包link、list、markdown、react/*插件等payloadcms/richtext-lexical/ast/mdxMDX/AST 相关服务端能力payloadcms/richtext-lexical/shared前后端共享工具如hasText九、更进一步仓库内的学习资料本仓库同时包含该包的完整文档、源码与测试建议按以下顺序深入包级使用文档与官方功能索引docs/rich-text/overview.mdx、docs/rich-text/official-features.mdx、docs/fields/rich-text.mdx字段级配置项与editor参数块、关系、上传等官方 Feature 的深入用法docs/rich-text/blocks.mdx、docs/rich-text/converters.mdx、docs/rich-text/views.mdx自定义 Feature 的完整开发指南docs/rich-text/custom-features.mdx、docs/rich-text/converting-jsx.mdx序列化节点类型与接口定义packages/richtext-lexical/src/types、packages/richtext-lexical/src/features可对照每个 Feature 的 server/client 目录了解实现结构小结从一次npm install payloadcms/richtext-lexical和一行editor: lexicalEditor({})开始你便为 Payload 的richText字段接入了基于 Lexical 的富文本引擎随后通过features、admin、lexical、views四个参数以及覆盖全部内置格式、列表、链接、关系、上传、Block 等能力的官方 Feature 体系可以按字段粒度裁剪或增强编辑器能力。存储上它产出强类型的序列化 JSON渲染上通过rsc/html/plaintext等子路径与转换器在服务端、管理后台与前端之间自由切换。若需要在此基础上构建自己的富文本节点仓库内的 docs/rich-text/custom-features.mdx 与 packages/richtext-lexical/src/features 的源码结构就是最直接的参照。【免费下载链接】payloadPayload is the open-source, fullstack Next.js framework, giving you instant backend superpowers. Get a full TypeScript backend and admin panel instantly. Use Payload as a headless CMS or for building powerful applications.项目地址: https://gitcode.com/GitHub_Trending/pa/payload创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考