@haklex/rich-compose

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

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

中文使用文档
文档目录21 节
  1. 为什么
  2. 安装
  3. 同伴依赖关系
  4. 快开始
  5. 只读渲染器
  6. 编辑器
  7. 可选渲染器虚拟化
  8. 三种消费模式
  9. 模式 A — 默认
  10. 模式 B – 自定义渲染器( 默认树形)
  11. 模式 C —— 覆盖默认
  12. 模块形状
  13. 规则
  14. 懒惰模块
  15. 平台不可知渲染
  16. 模块目录
  17. 子路径导出
  18. CSS战略
  19. 为什么不通过自动注射 import 副作用
  20. 哈克历克的一部分
  21. 许可证

@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 将静态-仅从只编辑链中分离出来)外加只发布无害环境管理.

安装

pnpm add @haklex/rich-compose

同伴依赖关系

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

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

快开始

只读渲染器

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" />;

或者选樱桃:

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] });

编辑器

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 用于嵌入式编辑状态.

可选渲染器虚拟化

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

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

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

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

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

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回落自动被接线.

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

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

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

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

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

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

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

模式 C —— 覆盖默认

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

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 (编辑超级集).

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编号. whiteboardKlass 的代码分割通过它自己的内部 decorate()。 。 。 .

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

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

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

<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
chartChartNodeChartEditNode同步rich-ext-chart
chatChatNodeChatEditNode同步rich-ext-chat
code-block内置—— 说懒惰 + sr 倒置rich-renderer-codeblock
code-snippetCodeSnippetNodeCodeSnippetEditNode同步rich-ext-code-snippet
embedEmbedNodeEmbedEditNode同步( 通过节点装饰)rich-ext-embed
whiteboardWhiteboardNodeWhiteboardEditNode通过节点装饰rich-ext-whiteboard
galleryGalleryNodeGalleryEditNode同步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-docNestedDocNodeNestedDocEditNode递归( 通过作曲器)rich-ext-nested-doc
pollPollNodePollEditNode同步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 可以使:

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

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

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,而捆绑者则以决定性的方式尊重它.

哈克历克的一部分

此软件包是 哈克历 丰富的编辑生态系统.

许可证

麻省理工学院

版本与发布记录

@haklex/rich-compose 共发布 127 个版本,首次发布于 2026/05/08;过去 12 个月发布了 127 个版本。最新版本附带 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-compose 的常见问题

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