# @haklex/rich-editor 中文文档

规范地址：https://npmcn.com/package/%40haklex/rich-editor/

版本：0\.66\.0
npm 元数据更新时间：2026-11-15T13:30:32.121Z
中文译文更新时间：2026-11-17T06:31:15.292Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40haklex/rich-editor
原文对照：https://npmcn.com/package/%40haklex/rich-editor/?lang=original
项目主页：https://github.com/Innei/haklex#readme
源码仓库：https://github.com/Innei/haklex

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：717 kB，411 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：katex \>=0\.16\.0，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
- 首次发布：2026-02-20T10:07:31.651Z
- 最新版本发布：2026-11-15T13:30:31.813Z
- 近 30 天下载量：21809（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：241（近 12 个月 241 个）

## 中文简介

基于 Lexical 的核心丰富文本编辑器

## 安装

```sh
npm install @haklex/rich-editor
```

也可以使用：`pnpm add @haklex/rich-editor`、`yarn add @haklex/rich-editor`、`bun add @haklex/rich-editor`

## README

# @haklex/ rich- 编辑器

基于 Lexical 的 Core 丰富的文本编辑器. 规定 `RichEditor` 组件,所有内建和自定义节点,内建插件,以及编辑上下文.

## 安装

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

## 同伴依赖关系

Lexic 0.44+ 显示代码块 `@lexical/code-core` (无棱相. 此软件包取决于它; 添加 `@lexical/code-core` 只当您自己导入时( 如自定义代码块工具) .

| 软件包 | 版本 | 需求 |
| --- | --- | --- |
| `@base-ui/react` | `^1.1.0` | 对 |
| `@lexical/extension` | `^0.45.0` | 对 |
| `@lexical/link` | `^0.45.0` | 对 |
| `@lexical/list` | `^0.45.0` | 对 |
| `@lexical/markdown` | `^0.45.0` | 对 |
| `@lexical/react` | `^0.45.0` | 对 |
| `@lexical/rich-text` | `^0.45.0` | 对 |
| `@lexical/table` | `^0.45.0` | 对 |
| `lexical` | `^0.45.0` | 对 |
| `lucide-react` | `^1.0.0` | 对 |
| `react` | `>=19` | 对 |
| `react-dom` | `>=19` | 对 |
| `katex` | `>=0.16.0` | 可选 |
| `shiki` | `^3.0.0` | 可选 |

## 使用量

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

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

用于只读渲染、使用 `@haklex/rich-compose` (出口 `RichRenderer` 和模块构成 API).

## 实验编辑器回收器

虚拟化是 **默认关闭**。可选插件将主编辑器中的完整文档保留在可编辑的 Lexical 实例中。 回收机执行量按需承担. 本地选择目前跨越一个编辑实例;协作和自定义插件仍然需要兼容工作. 见 [一体化合同和验证](https://npmcn.com/package/demo/src/poc-virtualization/EDITOR-RESULTS.md)。 。 。 .

```tsx
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>;
```

或者,注入与儿童插件相同的再生器:

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

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

滚动容器必须包含编辑器;通过它的 DOM 元素, ref,或 getter. 没有明确的容器,再生者会找到最近的滚动祖先,倒回窗口. `virtualization={false}` 覆盖插件。 选项也接受 `overscan` 以像素和 `estimateBlockHeight(block, width)` 用于自定义块估计.

`preserveCapacity` 默认为 **32个屏外节点**。它们的门户、 DOM 和编辑器实例仍安装在独立的主机中。 回到一个保留了的节点,直接保持其内部状态. 一旦超出预算,最近使用最少的屏外节点又回到国家的捕获和再利用; `0` 总是用回落。 重点/制造节点和保留合成操作被排除在驱逐之外。 Dormant DOM插件被暂停,而节点组件仍然被挂载. 有背景工作的组件可以使用 `useEditorBlock().active` 暂停它.

核心暴露为一般 `EditorSurfacePlugin` 财务报告和审定财务报表 `EditorSurfacePlugins` 扩展点。 虚拟化插件拥有它的视图,节点保存/LRU政策,测量,滚动和文档桥. `EditorSurfacePlugins` 在选中视图中安装 DOM/ 选择插件; 保存/ 历史插件留在文档编辑器上 . `ActiveEditorScope` 路径工具栏动作到焦点视图编辑器,以及 `useActiveEditor()` 揭露了那个编辑 模块,使用 `surfacePlugins` dOM/ 选择插件和 `plugins` 用于文档级别扩展,包括 `VirtualizationPlugin` 自己来 不将表层注册插件放入内部 `EditorSurfacePlugins`。 。 。 .

`useEditorBlock()` 提供逻辑节点状态 `retain()` 用于UI/同步操作。 保留还推迟请求的视图开关,直到操作开始。 内建媒体上传使用本合同. 自定义组件需要后退状态适配器,如果其内部状态必须在LRU驱出后幸存;细节和动态组件已经适应了. 动态 `getState()` 应返回独立快照,以及 `setState(undefined)` 必须重新设置新装订.

## 出口

### 构成部分

| 导出 | 说明 |
| --- | --- |
| `RichEditor` | 主编辑部分 |
| `ColorSchemeProvider` | 轻/暗主题的背景提供者 |
| `FootnoteDefinitionsProvider` | 脚注定义的上下文提供者 |
| `NestedContentRendererProvider` | 嵌入内容渲染的背景提供者 |

### 节点登记

| 导出 | 说明 |
| --- | --- |
| `allNodes` | 所有静态节点( 已建入 +自定义) |
| `builtinNodes` | 仅使用 Lexical 内置节点 |
| `customNodes` | 只自定义静态节点 |
| `allEditNodes` | 所有编辑模式节点( 已建入 + 自定义编辑) |
| `customEditNodes` | 只自定义编辑模式节点 |

### 节点类

| 导出 | 说明 |
| --- | --- |
| `MermaidNode`, (中文(简体) ), `$createMermaidNode`, (中文(简体) ), `$isMermaidNode` | 美人鱼图表节点 |
| `RubyNode`, (中文(简体) ), `$createRubyNode`, (中文(简体) ), `$isRubyNode` | Ruby 注释节点 |
| `GridContainerNode`, (中文(简体) ), `$createGridContainerNode`, (中文(简体) ), `$isGridContainerNode` | 网格布局容器 |
| `FootnoteSectionNode`, (中文(简体) ), `$createFootnoteSectionNode`, (中文(简体) ), `$isFootnoteSectionNode` | 脚注节节点 |
| `FootnoteSectionEditNode` | 脚注部分编辑-模式节点 |
| `ImageNode`, (中文(简体) ), `$createImageNode`, (中文(简体) ), `$isImageNode` | 图像节点 |
| `LinkCardNode`, (中文(简体) ), `$createLinkCardNode`, (中文(简体) ), `$isLinkCardNode` | 链接卡节点 |
| `KaTeXBlockNode`, (中文(简体) ), `$isKaTeXBlockNode` | KaTeX 块方程式节点 |
| `KaTeXInlineNode`, (中文(简体) ), `$isKaTeXInlineNode` | KaTeX 内置等式节点 |
| `MentionNode`, (中文(简体) ), `$createMentionNode`, (中文(简体) ), `$isMentionNode` | 提及节点 |

### 插件

| 导出 | 说明 |
| --- | --- |
| `AutoLinkPlugin` | 自动链接检测 |
| `BlockExitPlugin` | 用 Enter/ arrow 键退出块节点 |
| `HorizontalRulePlugin` | 水平规则插入 |
| `ImagePlugin` | 图像节点处理 |
| `ImageUploadPlugin` | 图像上传对话框和逻辑 |
| `KaTeXPlugin` | KaTeX 等式插入 |
| `LinkFaviconPlugin` | 链接法维康解析 |
| `MarkdownShortcutsPlugin` | 标记下语法快捷键 |
| `MermaidPlugin` | 美人鱼图插入 |
| `FootnotePlugin` | 脚注插入和管理 |

### 图标

| 导出 | 说明 |
| --- | --- |
| `INSERT_ALERT_COMMAND` | 插入提醒/调用块 |
| `INSERT_IMAGE_COMMAND` | 插入图像节点 |
| `OPEN_IMAGE_UPLOAD_DIALOG_COMMAND` | 打开图像上传对话框 |
| `INSERT_KATEX_BLOCK_COMMAND` | 插入 KATeX 块方程式 |
| `INSERT_KATEX_INLINE_COMMAND` | 插入 KATeX 内入等式 |
| `INSERT_MERMAID_COMMAND` | 插入美人鱼图 |

### 公用事业

| 导出 | 说明 |
| --- | --- |
| `extractTextContent` | 从编辑器状态提取纯文本 |
| `collectCommandItems` | 收集斜拉菜单/工具栏命令项 |
| `computeImageMeta` | 计算图像的缩略图和尺寸 |
| `decodeThumbHash` | 将缩略图字符串解码为数据 URL |
| `createRendererDecoration` | 为装饰节点创建渲染器装饰 |
| `getVariantClass` | 获取 CSS 类的变体 |
| `defaultImageUpload` | 默认图像上传执行 |
| `buildBlockAnchor`, (中文(简体) ), `buildRangeAnchor` | 评论主机 |
| `ALL_TRANSFORMERS` | 所有马克下调变压器(内置+块) |

### 槽密钥

`RendererConfig` 密钥以 `as const` 用于安全呼叫站点的常数。 用进去 `createRendererDecoration` 和模块覆盖地图而不是赤色字符串文字:

```ts
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';
```

扩展包`@haklex/rich-ext-*`)暴露自己的槽键(例如. `POLL_NODE_KEY`, (中文(简体) ), `CHAT_NODE_KEY`) (中文(简体) ).

### 扩展 `RendererConfig`

`@haklex/rich-editor` 只有内置的舱位 扩展和下游包通过 TypeScript 模块扩能增加自己的槽:

```ts
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 {};
```

将增强文件作为副作用从每个公共条目再出口(`/node`, (中文(简体) ), `/renderer`, (中文(简体) ), `/edit`, (中文(简体) ), `/static`, (中文(简体) ), `/index`因此,消费者无论进口哪条子路径都可以看到槽.

### 类型

`RichEditorProps`, (中文(简体) ), `RichEditorVariant`, (中文(简体) ), `RendererConfig`, (中文(简体) ), `ColorScheme`, (中文(简体) ), `RendererMode`, (中文(简体) ), `ImageUploadFn`, (中文(简体) ), `ImageUploadResult`, (中文(简体) ), `CommandItemConfig`, (中文(简体) ), `SlashMenuItemConfig`, (中文(简体) ), `ToolbarGroup`, (中文(简体) ), `CommandPlacement`,以及 **内置** 渲染器道具类型(`AlertRendererProps`, (中文(简体) ), `ImageRendererProps`, (中文(简体) ), `CodeBlockRendererProps`(见A/C.5/49/70,附件)。 扩展渲染道具( E)`PollRendererProps`, (中文(简体) ), `ChatRendererProps`, (中文(简体) ), `CodeFile`, (中文(简体) ), `GalleryRendererProps`,.)生活在自己的包中——从 `@haklex/rich-ext-<name>/node`。 。 。 .

### 子路径导出

| 导入路径 | 说明 |
| --- | --- |
| `@haklex/rich-editor` | 完全导出( 组件、 节点、 插件、 命令、 上下文、 类型) |
| `@haklex/rich-editor/editor` | 编辑器专用条目(RichEditor + 节点配置) |
| `@haklex/rich-editor/nodes` | 节点类+编辑-模式节点类 |
| `@haklex/rich-editor/plugins` | 内建插件 |
| `@haklex/rich-editor/commands` | 插入/ 打开命令+ `CommandItemConfig` |
| `@haklex/rich-editor/renderers` | 内建渲染器组件、道具类型和槽键常数 |
| `@haklex/rich-editor/static` | 静态/SR设施(用于制造器和扩展包) |
| `@haklex/rich-editor/styles` | 样式变量和变异类导出 |
| `@haklex/rich-editor/style.css` | 编译编辑器样式表 |

## 哈克历克的一部分

此软件包是 [哈克历](https://npmcn.com/package/README.md) 丰富的编辑生态系统.

## 许可证

麻省理工学院

## 常见问题

### @haklex/rich-editor 是什么？

基于 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 和提交记录判断。

