# @haklex/rich-compose 中文文档

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

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

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

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

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

- 包体积（解压后）：9.1 MB，401 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：24 个
- peer 依赖：react \>=19，lexical ^0\.53\.0，react-dom \>=19，lucide-react ^1\.0\.0，@lexical/react ^0\.53\.0，@haklex/rich-editor ^0\.66\.0，@haklex/rich-ext-dynamic ^0\.66\.0
- 首次发布：2026-05-08T11:28:02.186Z
- 最新版本发布：2026-11-15T13:30:54.366Z
- 近 30 天下载量：13085（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：127（近 12 个月 127 个）

## 中文简介

由哈克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克.

## 安装

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

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

## README

# @haklex/ rich- compose (帮助)

为haklex丰富的内容作原始作曲——Gundam-style 组装Lexical节点,同步/懒惰渲染器,编辑-侧面装饰器,以及提供商堆. 双方的权力 `composeRenderer` (只读)和 `composeEditor` (编).

## 为什么

遗产 `@haklex/rich-kit-shiro/renderer` (已清除了)每个默认的造物者,都要急切地发去: `CodeBlock` 或者说 `LinkCard` 离开原作 `shiki` 财务报告和审定财务报表 `LinkCardRenderer` 锁链在捆绑. `rich-compose` 一次解决三个问题:

1.  **可切换** ——不导入而放弃模块.
2.  **可替换** ——互换一个默认渲染器,没有剩余字节.
3.  **广泛** ——在不接触包的情况下再添加新的渲染器槽(同步或懒散).

树震是由物理亚道隔离造成的(`./modules/<name>/node` a. 将Klasses与重渲染器编码相分离; `./modules/<name>` 对 `./modules/<name>/edit` 将静态-仅从只编辑链中分离出来)外加只发布无害环境管理.

## 安装

```bash
pnpm add @haklex/rich-compose
```

## 同伴依赖关系

| 软件包 | 版本 |
| --- | --- |
| `react` 编号 : `react-dom` | `>=19` |
| `lexical` 编号 : `@lexical/react` | `^0.45.0` |
| `@haklex/rich-editor` | 工作空间 |

每个模块上游包(`@haklex/rich-ext-*`, (中文(简体) ), `@haklex/rich-renderer-*`)是可选的同位素——只安装您创作的同位素.

## 快开始

### 只读渲染器

```tsx
import { composeRenderer } from '@haklex/rich-compose/core';
import { allRendererModules } from '@haklex/rich-compose/renderer';

const RichContent = composeRenderer({ modules: allRendererModules });

// Render
<RichContent value={editorState} theme="light" variant="article" />;
```

或者选樱桃:

```tsx
import { composeRenderer } from '@haklex/rich-compose/core';
import { embedModule } from '@haklex/rich-compose/modules/embed';
import { codeBlockModule } from '@haklex/rich-compose/modules/code-block';

const RichContent = composeRenderer({ modules: [embedModule, codeBlockModule] });
```

### 编辑器

```tsx
import { composeEditor } from '@haklex/rich-compose';
import { allEditorModules } from '@haklex/rich-compose/editor';

const RichEditor = composeEditor({ modules: allEditorModules });

// Use like @haklex/rich-editor's RichEditor — accepts the same props plus children for plugins.
<RichEditor initialValue={state} onChange={setState} variant="article" />;
```

两位帮助者都返回被纪念的React组件. `composeEditor` 内线 `composeRenderer` 用于嵌入式编辑状态.

### 可选渲染器虚拟化

默认的渲染仍然完整。 启用带有道具的再生器 :

```tsx
const scrollRef = useRef<HTMLDivElement>(null);
const virtualization = useMemo(() => ({ scrollContainer: scrollRef, preserveCapacity: 32 }), []);

<ScrollArea scrollRef={scrollRef}>
  <RichContent value={editorState} virtualization={virtualization} />
</ScrollArea>;
```

取景口必须有有界高. `scrollContainer` 接受其DOM元素、参考或获取器;它必须包含已提供的内容。 没有它,再生者会找到最近的卷轴祖先,然后使用窗口.

或者,将执行安装为构图模块:

```tsx
import { rendererVirtualizationModule } from '@haklex/rich-compose/virtualization';

const RichContent = composeRenderer({
  modules: [...allRendererModules, rendererVirtualizationModule({ preserveCapacity: 32 })],
});
```

明确 `virtualization={false}` 覆盖已安装的模块。 该模块提供一个渲染表面;它不会打开第二个完整的文件渲染器。 除非明确启用,巢造物器保持其普通表面.

编辑器和渲染器共享打入的回收池,测量到比值倒塌,以及保持挂载的管理器. 默认保留了多达32个屏幕外挂载;LRU的驱逐在重用实例之前节省了细节/动力状态。 设定 `preserveCapacity: 0` 立即恢复状态 需要动态组件 `getState`编号 :`setState` - 习惯成分可以使用 `useEditorBlock().nodeState()` 财务报告和审定财务报表 `retain()`。 。 。 .

从完整的文档中准备了标题锚和脚注编号,而反应树只为已渲染的窗口所创建. Opt- in virtual SSR 释放出一个被限制的初始窗口;默认 SSR 仍然完整 。 浮图和流经其清除块的文本仍然是一个原生的流出单元,如注中引出下一块的段落一样。 一个非常大的流量单元或单个表格内部不虚拟化. 初始解析和文档替换仍以文档大小为比例 。 更改文档,变体,或再生器选项重建瞬态视图缓存. 对未挂载内容的本地选择/复制,浏览器在页面上的查找仍仅限于挂载窗口.

演示会 **20 000个复杂节点** 预设支持编辑和Render。 两个都用UI `ScrollArea` 明显地,有一个固定的检查员旁边。 渲染和编辑共用相同的文章宽度和水平间隔.

## 三种消费模式

### 模式 A — 默认

导入模块糖. Klass + 渲染器 + (可选) 懒惰/ SSR回落自动被接线.

```tsx
import { embedModule } from '@haklex/rich-compose/modules/embed';
import { embedEditModule } from '@haklex/rich-compose/modules/embed/edit';
```

### 模式 B – 自定义渲染器( 默认树形)

导入 Klass 从 `/node`提供自己的制造器.

```tsx
import { GalleryNode } from '@haklex/rich-compose/modules/gallery/node';

const myGalleryModule: RichRendererModule = {
  name: 'gallery',
  nodes: [GalleryNode],
  renderers: { Gallery: MyGalleryRenderer },
};
```

仅用于渲染器模块(没有自定义 Klass),以匹配方式构建 `name`数字 :

```tsx
const myLinkCardModule: RichRendererModule = {
  name: 'link-card',
  renderers: { LinkCard: MyLinkCardRenderer },
};
```

### 模式 C —— 覆盖默认

将默认渲染器从 `/renderer` 并包装.

```tsx
import { LinkCardRenderer } from '@haklex/rich-compose/modules/link-card/renderer';

const wrappedModule: RichRendererModule = {
  name: 'link-card',
  renderers: {
    LinkCard: (props) => (
      <div className="extra-wrap">
        <LinkCardRenderer {...props} />
      </div>
    ),
  },
};
```

## 模块形状

`RichRendererModule` (只读)和 `RichEditorModule` (编辑超级集).

```ts
interface RichRendererModule {
  name: string; // dedup key
  nodes?: Klass<LexicalNode>[]; // base Klasses
  renderers?: Partial<RendererConfig>; // sync renderer map
  Provider?: ComponentType<{ children: ReactNode }>; // shared provider
  lazyRenderers?: Partial<{
    [K in RendererKey]: () => Promise<{ default: NonNullable<RendererConfig[K]> }>;
  }>;
  ssrFallback?: Partial<Record<RendererKey, ReactNode>>;
}

interface RichEditorModule extends RichRendererModule {
  editNodes?: Klass<LexicalNode>[]; // edit-side subclasses (override base by getType)
  editRenderers?: Partial<RendererConfig>; // override renderers in editor mode
  EditorProvider?: ComponentType<{ children: ReactNode }>; // editor-only provider
  plugins?: ReactNode; // module-owned editor plugins
  nestedEditorPlugins?: ReactNode; // plugins mounted inside LexicalNestedComposer surfaces
  actions?: ReactNode; // module-owned action UI
}
```

`composeRenderer` 消耗量 `RichRendererModule[]`· ; `composeEditor` 消耗量 `RichEditorModule[]`。每个编辑模块只传播其渲染器的对应器,所以 `allEditorModules` 是一个严格的超级集 `allRendererModules`。 。 。 .

## 规则

```
modules:
  reference seen   → skip silently
  same name        → warn (dev), replace previous module entirely
  else             → append

nodes:
  reference seen          → skip
  subclass override       → edit Klass replaces base Klass (same getType, A extends B)
  unrelated collision     → throw at compose time
                            (would break instanceof across module boundaries)
```

## 懒惰模块

`code-block` 财务报告和审定财务报表 `mermaid` 过失而懒惰的船 `ssrFallback`编号. `whiteboard`Klass 的代码分割通过它自己的内部 `decorate()`。 。 。 .

覆盖懒惰的渲染器(例如SSR的预切代码块),通过 `overrides`数字 :

```ts
composeRenderer({
  modules: allRendererModules,
  overrides: { CodeBlock: PreTokenizedCodeBlock },
});
```

懒人块仍然被排放,但从未在运行时取出.

## 平台不可知渲染

`RichRenderer` (和 `composeRenderer`)默认情况下释放出 DOM,但每个 DOM 触点都是可注射的,因此同种树行走可以瞄准另一个反应渲染器(React Industrial, 墨水, 测试带):

| 钩子 | 封面 |
| --- | --- |
| `builtinNodeOverrides[type]` | 元素节点( E)`paragraph`, (中文(简体) ), `heading`, (中文(简体) ), `list`,)和装饰节点(`image`, (中文(简体) ), `mermaid`, (...) (中文(简体) ) |
| `builtinNodeOverrides.text` | 文本叶-收到序列化文本节点(`text`, (中文(简体) ), `format`, (中文(简体) ), `style`(中文(简体) ) |
| `blockAnchor(el, blockId, key)` | 接载根级块包装器 `$.blockId`; 默认为 a `data-block-id` 数字 |
| `as` | 主机集装箱-任何 `ElementType`; 非字符串主机仅接收 `style` 财务报告和审定财务报表 `children` |

装饰者超接器作为单子接收默认装饰,并可能放弃:

```tsx
<RichRenderer
  as={View}
  blockAnchor={(el, blockId, key) => (
    <View key={key} nativeID={blockId}>
      {el}
    </View>
  )}
  builtinNodeOverrides={{
    text: (node, key) => (
      <Text key={key} style={textStyle(node.format)}>
        {node.text}
      </Text>
    ),
    paragraph: (_node, key, children) => <Text key={key}>{children}</Text>,
    mermaid: (node, key) => <NativeMermaid key={key} diagram={node.diagram} />,
  }}
  value={state}
/>
```

装饰机位( E)`rendererConfig` 模块 `renderers`接受任何反应组件,所以 `Image`, (中文(简体) ), `CodeBlock`, (中文(简体) ), `LinkCard` 以同样方式替换.

## 模块目录

| 模块 | 基础文件 | 编辑文件 | 模式 | 来源 |
| --- | --- | --- | --- | --- |
| `alert` | 内置 | —— 说 | 同步 | `rich-renderer-alert` |
| `banner` | 内置 | —— 说 | 同步 | `rich-renderer-banner` |
| `chart` | `ChartNode` | `ChartEditNode` | 同步 | `rich-ext-chart` |
| `chat` | `ChatNode` | `ChatEditNode` | 同步 | `rich-ext-chat` |
| `code-block` | 内置 | —— 说 | 懒惰 + sr 倒置 | `rich-renderer-codeblock` |
| `code-snippet` | `CodeSnippetNode` | `CodeSnippetEditNode` | 同步 | `rich-ext-code-snippet` |
| `embed` | `EmbedNode` | `EmbedEditNode` | 同步( 通过节点装饰) | `rich-ext-embed` |
| `whiteboard` | `WhiteboardNode` | `WhiteboardEditNode` | 通过节点装饰 | `rich-ext-whiteboard` |
| `gallery` | `GalleryNode` | `GalleryEditNode` | 同步 | `rich-ext-gallery` |
| `image` | 内置 | —— 说 | 同步 | `rich-renderer-image` |
| `katex` | —— 说 | 内置 | 只编辑( 无静态渲染器) | `rich-renderer-katex` |
| `link-card` | 内置 | —— 说 | 同步 | `rich-renderer-linkcard` |
| `mention` | 内置 | —— 说 | 同步 | `rich-renderer-mention` |
| `mermaid` | 内置 | —— 说 | 懒惰 + sr 倒置 | `rich-renderer-mermaid` |
| `nested-doc` | `NestedDocNode` | `NestedDocEditNode` | 递归( 通过作曲器) | `rich-ext-nested-doc` |
| `poll` | `PollNode` | `PollEditNode` | 同步 | `rich-ext-poll` |
| `ruby` | 内置 | —— 说 | 同步 | `rich-renderer-ruby` |
| `video` | 内置 | —— 说 | 同步 | `rich-renderer-video` |

`katex` 舰只编辑模块 — KaTeX 渲染只读侧面由主机渲染器通过 `decorate()`。 。 。 .

## 子路径导出

| 路径 | 说明 |
| --- | --- |
| `@haklex/rich-compose` | 相容性管:核心辅助器外加聚合方便器 |
| `@haklex/rich-compose/core` | 渲染器组成核心 : `composeRenderer`, (中文(简体) ), `RichRenderer`, 渲染器类型 |
| `@haklex/rich-compose/renderer` | 总管-每个出件模块+ `allRendererModules` |
| `@haklex/rich-compose/editor` | 总管-每个编辑模块+ `allEditorModules` |
| `@haklex/rich-compose/modules/<name>` | 制发器-侧模块管 |
| `@haklex/rich-compose/modules/<name>/edit` | 编辑器侧模块( 扩展渲染器模块) |
| `@haklex/rich-compose/modules/<name>/node` | 仅限Klass(在适用时) |
| `@haklex/rich-compose/modules/<name>/renderer` | 仅默认渲染器 |
| `@haklex/rich-compose/style.css` | 全能 CSS 捆绑 — 活体 + 符号 + 每个模块 |
| `@haklex/rich-compose/style/foundation.css` | 散文体 + 主题符号 + 变种类(无模块) |
| `@haklex/rich-compose/style/table.css` | 内置的表格渲染器 |
| `@haklex/rich-compose/style/<name>.css` | 每单元CSS(警报,横幅,图像,视频, |

合计桶是方便的默认;精细的 `/modules/<name>` 财务报告和审定财务报表 `/modules/<name>/edit` 子路径仍然可供动态输入和选择性输入使用.

## CSS战略

两种消费模式:

**全能( 默认) .** 一个输入覆盖一切 `rich-compose` 可以使:

```ts
import '@haklex/rich-compose/style.css';
```

**精进相取(上).** 当你超过一个或多个默认渲染器时使用这个 并想从你的包里放下他们的CSS 导入 `foundation.css` 加上你所保持的模块——永远不要伸入 `rich-renderer-*` 或者说 `rich-ext-*` 直接软件包 :

```ts
import '@haklex/rich-compose/style/foundation.css';
import '@haklex/rich-compose/style/alert.css';
import '@haklex/rich-compose/style/image.css';
import '@haklex/rich-compose/style/ruby.css';
// …only modules whose default renderer you kept
```

模块子路径与JS模块子路径相仿(`modules/<name>` ↔ `style/<name>.css`) (中文(简体) ).

### 为什么不通过自动注射 `import` 副作用

早期版本尝试从内部导入每个模块的 CSS 副作用 `modules/<name>/index.ts`结合 `sideEffects: ["**/*.css"]` (标记 `.mjs` 文件作为无副作用)和捆绑优化,例如Next.js `optimizePackageImports`这些光鲜的CSS进口品是被树震掉的——模块已经制造出来,但其造型缺失。 上面明晰的子路径模型消除了这把脚枪:消费者表示他们想要的CSS,而捆绑者则以决定性的方式尊重它.

## 哈克历克的一部分

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

## 许可证

麻省理工学院

## 常见问题

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

由哈克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克\.

### 如何安装 @haklex/rich-compose？

在项目目录运行 npm install @haklex/rich-compose，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19）、lexical（^0\.53\.0）、react-dom（\>=19）、lucide-react（^1\.0\.0）、@lexical/react（^0\.53\.0）、@haklex/rich-editor（^0\.66\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @haklex/rich-compose 支持 TypeScript 吗？

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

### @haklex/rich-compose 支持 ESM 还是 CommonJS？

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

### @haklex/rich-compose 可以商用吗？

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

### @haklex/rich-compose 的下载量有多少？

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

### @haklex/rich-compose 还在维护吗？

最新版本 0\.66\.0 发布于 2026/11/15（1 天前）；至今共发布 127 个版本，其中过去 12 个月发布了 127 个；首次发布于 2026/05/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

