@haklex/ rich- compose (帮助)
为haklex丰富的内容作原始作曲——Gundam-style 组装Lexical节点,同步/懒惰渲染器,编辑-侧面装饰器,以及提供商堆. 双方的权力 composeRenderer (只读)和 composeEditor (编).
为什么
遗产 @haklex/rich-kit-shiro/renderer (已清除了)每个默认的造物者,都要急切地发去: CodeBlock 或者说 LinkCard 离开原作 shiki 财务报告和审定财务报表 LinkCardRenderer 锁链在捆绑. rich-compose 一次解决三个问题:
- 可切换 ——不导入而放弃模块.
- 可替换 ——互换一个默认渲染器,没有剩余字节.
- 广泛 ——在不接触包的情况下再添加新的渲染器槽(同步或懒散).
树震是由物理亚道隔离造成的(./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 |
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 可以使:
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,而捆绑者则以决定性的方式尊重它.
哈克历克的一部分
此软件包是 哈克历 丰富的编辑生态系统.
许可证
麻省理工学院