@haklex/rich-editor

中文文档
0.66.0发布于 2026/11/15MITTypeScriptES Module构建来源已验证近 30 天下载 2.2万

Core rich text editor based on Lexical

原始使用文档
文档目录17 节
  1. Installation
  2. Peer Dependencies
  3. Usage
  4. Experimental editor recycler
  5. Exports
  6. Components
  7. Node Registries
  8. Node Classes
  9. Plugins
  10. Commands
  11. Utilities
  12. Slot Keys
  13. Extending RendererConfig
  14. Types
  15. Sub-path Exports
  16. Part of Haklex
  17. License

@haklex/rich-editor

Core rich text editor based on Lexical. Provides the RichEditor component, all builtin and custom nodes, built-in plugins, and editor contexts.

Installation

pnpm add @haklex/rich-editor lexical @lexical/react react react-dom

Peer Dependencies

Lexical 0.44+ exposes code blocks in @lexical/code-core (no Prism). This package depends on it; add @lexical/code-core to your app only if you import it yourself (e.g. custom code-block tooling).

PackageVersionRequired
@base-ui/react^1.1.0Yes
@lexical/extension^0.45.0Yes
@lexical/link^0.45.0Yes
@lexical/list^0.45.0Yes
@lexical/markdown^0.45.0Yes
@lexical/react^0.45.0Yes
@lexical/rich-text^0.45.0Yes
@lexical/table^0.45.0Yes
lexical^0.45.0Yes
lucide-react^1.0.0Yes
react>=19Yes
react-dom>=19Yes
katex>=0.16.0Optional
shiki^3.0.0Optional

Usage

import { RichEditor } from '@haklex/rich-editor';
import '@haklex/rich-editor/style.css';

<RichEditor variant="article" initialValue={savedState} onChange={(value) => save(value)} />;

For read-only rendering, use @haklex/rich-compose (exports RichRenderer and the modular composition API).

Experimental editor recycler

Virtualization is off by default. The optional plugin keeps the full document in the main editor and projects visible blocks into editable Lexical instances. The recycler implementation loads on demand. Native selection currently spans one editing instance; collaboration and custom plugins still need compatibility work. See the integration contract and validation.

const scrollRef = useRef<HTMLDivElement>(null);

<div ref={scrollRef} style={{ height: 600, overflow: 'auto' }}>
  <RichEditor
    initialValue={savedState}
    onChange={save} // receives the full document
    virtualization={{ scrollContainer: scrollRef, preserveCapacity: 32 }}
  />
</div>;

Alternatively, inject the same recycler as a child plugin:

import { RichEditor } from '@haklex/rich-editor';
import { VirtualizationPlugin } from '@haklex/rich-editor/virtualization';

<RichEditor initialValue={savedState} onChange={save}>
  <VirtualizationPlugin scrollContainer={scrollRef} />
</RichEditor>;

The scroll container must contain the editor; pass its DOM element, ref, or getter. Without an explicit container, the recycler finds the nearest scrolling ancestor, falling back to the window. virtualization={false} overrides a plugin. Options also accept overscan in pixels and estimateBlockHeight(block, width) for custom block estimates.

preserveCapacity defaults to 32 offscreen nodes. Their portals, DOM and editor instances stay mounted in detached hosts. Returning to a preserved node keeps its internal state directly. Once the budget is exceeded, the least recently used offscreen node falls back to state capture and recycling; 0 always uses that fallback. Focused/composing nodes and retained async operations are excluded from eviction. Dormant DOM plugins are suspended, while node components remain mounted. Components with background work can use useEditorBlock().active to pause it.

The core exposes generic EditorSurfacePlugin and EditorSurfacePlugins extension points. The virtualization plugin owns its view, node preservation/LRU policy, measurement, scrolling and document bridge. EditorSurfacePlugins installs DOM/selection plugins in the selected view; save/history plugins remain on the document editor. ActiveEditorScope routes toolbar actions to the focused view editor, and useActiveEditor() exposes that editor. In composed modules, use surfacePlugins for DOM/selection plugins and plugins for document-level extensions, including VirtualizationPlugin itself. Do not put the surface-registering plugin inside EditorSurfacePlugins.

useEditorBlock() provides logical node state and retain() for UI/async operations. Retention also postpones a requested view switch until the operation commits. Built-in media uploads use this contract. Custom components need a fallback state adapter if their internal state must survive LRU eviction; details and dynamic components are already adapted. Dynamic getState() should return an independent snapshot, and setState(undefined) must reset a fresh binding.

Exports

Components

ExportDescription
RichEditorMain editor component
ColorSchemeProviderContext provider for light/dark theme
FootnoteDefinitionsProviderContext provider for footnote definitions
NestedContentRendererProviderContext provider for nested content rendering

Node Registries

ExportDescription
allNodesAll static nodes (builtin + custom)
builtinNodesLexical builtin nodes only
customNodesCustom static nodes only
allEditNodesAll edit-mode nodes (builtin + custom edit)
customEditNodesCustom edit-mode nodes only

Node Classes

ExportDescription
MermaidNode, $createMermaidNode, $isMermaidNodeMermaid diagram node
RubyNode, $createRubyNode, $isRubyNodeRuby annotation node
GridContainerNode, $createGridContainerNode, $isGridContainerNodeGrid layout container
FootnoteSectionNode, $createFootnoteSectionNode, $isFootnoteSectionNodeFootnote section node
FootnoteSectionEditNodeFootnote section edit-mode node
ImageNode, $createImageNode, $isImageNodeImage node
LinkCardNode, $createLinkCardNode, $isLinkCardNodeLink card node
KaTeXBlockNode, $isKaTeXBlockNodeKaTeX block equation node
KaTeXInlineNode, $isKaTeXInlineNodeKaTeX inline equation node
MentionNode, $createMentionNode, $isMentionNodeMention node

Plugins

ExportDescription
AutoLinkPluginAutomatic link detection
BlockExitPluginExit block nodes with Enter/arrow keys
HorizontalRulePluginHorizontal rule insertion
ImagePluginImage node handling
ImageUploadPluginImage upload dialog and logic
KaTeXPluginKaTeX equation insertion
LinkFaviconPluginFavicon resolution for links
MarkdownShortcutsPluginMarkdown syntax shortcuts
MermaidPluginMermaid diagram insertion
FootnotePluginFootnote insertion and management

Commands

ExportDescription
INSERT_ALERT_COMMANDInsert an alert/callout block
INSERT_IMAGE_COMMANDInsert an image node
OPEN_IMAGE_UPLOAD_DIALOG_COMMANDOpen the image upload dialog
INSERT_KATEX_BLOCK_COMMANDInsert a KaTeX block equation
INSERT_KATEX_INLINE_COMMANDInsert a KaTeX inline equation
INSERT_MERMAID_COMMANDInsert a Mermaid diagram

Utilities

ExportDescription
extractTextContentExtract plain text from editor state
collectCommandItemsCollect slash menu / toolbar command items
computeImageMetaCompute thumbhash and dimensions for an image
decodeThumbHashDecode a thumbhash string to a data URL
createRendererDecorationCreate a renderer decoration for decorator nodes
getVariantClassGet the CSS class for a variant
defaultImageUploadDefault image upload implementation
buildBlockAnchor, buildRangeAnchorComment anchor utilities
ALL_TRANSFORMERSAll Markdown transformers (inline + block)

Slot Keys

RendererConfig keys are exposed as as const constants for safer call sites. Use them in createRendererDecoration and module override maps instead of bare string literals:

import {
  ALERT_NODE_KEY,
  BANNER_NODE_KEY,
  CODE_BLOCK_NODE_KEY,
  FOOTNOTE_NODE_KEY,
  FOOTNOTE_SECTION_NODE_KEY,
  IMAGE_NODE_KEY,
  KATEX_NODE_KEY,
  LINK_CARD_NODE_KEY,
  MENTION_NODE_KEY,
  MERMAID_NODE_KEY,
  RUBY_NODE_KEY,
  TAG_NODE_KEY,
  VIDEO_NODE_KEY,
} from '@haklex/rich-editor';

Extension packages (@haklex/rich-ext-*) expose their own slot keys (e.g. POLL_NODE_KEY, CHAT_NODE_KEY).

Extending RendererConfig

@haklex/rich-editor ships only the built-in slots. Extension and downstream packages add their own slots via TypeScript module augmentation:

import type { ComponentType } from 'react';
import type { MyChartProps } from './MyChart';
// Force the augmentation target to resolve as an external module.
import type {} from '@haklex/rich-editor';

declare module '@haklex/rich-editor' {
  interface RendererConfig {
    MyChart?: ComponentType<MyChartProps>;
  }
}

export {};

Re-export the augmentation file as a side-effect from every public entry (/node, /renderer, /edit, /static, /index) so consumers see the slot regardless of which sub-path they import.

Types

RichEditorProps, RichEditorVariant, RendererConfig, ColorScheme, RendererMode, ImageUploadFn, ImageUploadResult, CommandItemConfig, SlashMenuItemConfig, ToolbarGroup, CommandPlacement, and built-in renderer prop types (AlertRendererProps, ImageRendererProps, CodeBlockRendererProps, etc.). Extension renderer props (PollRendererProps, ChatRendererProps, CodeFile, GalleryRendererProps, …) live in their owning packages — import from @haklex/rich-ext-<name>/node.

Sub-path Exports

Import PathDescription
@haklex/rich-editorFull export (components, nodes, plugins, commands, contexts, types)
@haklex/rich-editor/editorEditor-specific entry (RichEditor + node configs)
@haklex/rich-editor/nodesNode classes + edit-mode node classes
@haklex/rich-editor/pluginsBuilt-in plugins
@haklex/rich-editor/commandsInsert / open commands + CommandItemConfig
@haklex/rich-editor/renderersBuilt-in renderer components, prop types, and slot key constants
@haklex/rich-editor/staticStatic/SSR utilities (for renderer and extension packages)
@haklex/rich-editor/stylesStyle variables and variant class exports
@haklex/rich-editor/style.cssCompiled editor stylesheet

Part of Haklex

This package is part of the Haklex rich editor ecosystem.

License

MIT

版本与发布记录

@haklex/rich-editor 共发布 241 个版本,首次发布于 2026/02/20;过去 12 个月发布了 241 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.66.0latest2026/11/151 天前
0.65.72026/11/143 天前
0.65.62026/11/124 天前
0.65.52026/11/124 天前
0.65.42026/11/124 天前
0.65.32026/11/124 天前

关于 @haklex/rich-editor 的常见问题

@haklex/rich-editor 是什么?

Core rich text editor based on Lexical

如何安装 @haklex/rich-editor?

在项目目录运行 npm install @haklex/rich-editor,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(>=19)、lexical(^0.53.0)、react-dom(>=19)、lucide-react(^1.0.0)、@lexical/link(^0.53.0)、@lexical/list(^0.53.0)、@base-ui/react(>=1.5.0)、@lexical/react(^0.53.0)、@lexical/table(^0.53.0)、@lexical/markdown(^0.53.0)、@lexical/extension(^0.53.0)、@lexical/rich-text(^0.53.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@haklex/rich-editor 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@haklex/rich-editor 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@haklex/rich-editor 可以商用吗?

@haklex/rich-editor 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@haklex/rich-editor 的下载量有多少?

根据 npm 官方下载统计,@haklex/rich-editor 在 2026/10/17 – 2026/11/15 这 30 天内被下载 21,809 次,日均约 727 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@haklex/rich-editor 还在维护吗?

最新版本 0.66.0 发布于 2026/11/15(1 天前);至今共发布 241 个版本,其中过去 12 个月发布了 241 个;首次发布于 2026/02/20。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。