@node-wright/react 是官方 React 适配层,把底层核心 @node-wright/core/view 的编辑器控制器渲染为 React 组件。props、事件、ref API 与默认 DOM 节点行为都与 Vue 版一致(两者运行同一份适配层契约测试),本文说明 React 侧的用法与专属约定。
- 依赖:
@node-wright/core(随本包安装)。 - peer dependencies:
react、react-dom^18.3.0 || ^19.0.0;@types/react为可选 peer。 - 样式:
@node-wright/react/style.css(已打包@node-wright/core/view/style.css),需要显式导入一次。
import {
DefaultDomNode,
NodeWright,
useNodeWrightApi,
type NodeWrightHandle,
} from '@node-wright/react'
import '@node-wright/react/style.css'| 导出 | 说明 |
|---|---|
NodeWright |
编辑器组件(forwardRef,ref 类型为 NodeWrightHandle) |
DefaultDomNode |
默认 DOM 节点组件(memo,props 为 NodeWrightDomNodeProps) |
useNodeWrightApi() |
在 render props 内容与 DOM 节点组件中取得所在编辑器的 NodeWrightApi |
NodeWrightProps |
组件 props 类型 |
NodeWrightHandle |
ref 的值,即 NodeWrightApi |
NodeWrightEventHandlers |
全部事件回调 props 的类型 |
NodeWrightEventHandlerName<Name> |
事件名到回调 prop 名的类型映射('graph-change' → 'onGraphChange') |
NodeWrightDomComponent |
DOM 节点组件类型:ComponentType<NodeWrightDomNodeProps> |
NodeWrightBackgroundRenderProps / NodeWrightOverlayRenderProps |
render props 的参数类型 |
最小可运行示例见 README 与 getting-started.md。
NodeWrightProps = NodeWrightEditorOptions(不含 onEvent)+ 事件回调 + 以下 React 专属 props。编辑器选项的类型、默认值与语义见 controller-api.md。
| Prop | 类型 | 说明 |
|---|---|---|
ariaLabel |
string |
根元素可访问名称,默认 'Node graph editor' |
className |
string |
追加到根元素 nw-root 之后 |
style |
CSSProperties |
与主题根样式合并(后者为 CSS 自定义属性) |
domComponents |
Readonly<Record<string, NodeWrightDomComponent>> |
DOM 节点组件注册表,键为 DOM 渲染器的 component |
renderBackground |
(props: NodeWrightBackgroundRenderProps) => ReactNode |
渲染在画布之上、DOM 节点层之下 |
renderOverlay |
(props: NodeWrightOverlayRenderProps) => ReactNode |
渲染在所有编辑器图层之上 |
- 编辑器选项按引用比较:每次提交后,适配层逐项比较选项值,只有某一项引用变化时才调用
controller.update()。请传入稳定引用——模块级常量、state 或useMemo的结果。 - 新的注册表数组(
nodeDefinitions、edgeDefinitions、commands、plugins)或新的connectionValidator会以当前图重建内部 Store,并清空撤销历史。 - 事件回调 props 不参与比较,每次渲染都可以是新的函数;适配层总是调用最近一次渲染的回调。
initialViewport、initialSelection只在控制器创建时读取。
const [graph, setGraph] = useState(initialGraph)
<NodeWright graph={graph} onGraphChange={setGraph} />graph + onGraphChange 对应 Vue 的 v-model:graph。onGraphChange 回传的图对象原样传回 graph 时被识别为回声,不会替换图,撤销历史得以保留;传入其他图对象时替换图并清空历史。只传 graph 不接 onGraphChange 时,编辑器内部仍然可以编辑,graph 只在引用变化时覆盖内部状态。
每个 NodeWrightEventMap 事件对应一个 on + 驼峰名的回调 prop,参数与 Vue 事件相同:graph-change → onGraphChange、selection-change → onSelectionChange、node-drag-end → onNodeDragEnd、connect → onConnect、command-error → onCommandError。
<NodeWright
graph={graph}
onGraphChange={setGraph}
onSelectionChange={(selection, _graph, source) => console.log(source, selection.nodes)}
onConnectionCancel={(event) => openCreateMenu(event)}
/>const editor = useRef<NodeWrightHandle>(null)
useLayoutEffect(() => {
editor.current?.view.fit.graph(72)
}, [])
return <NodeWright ref={editor} graph={graph} onGraphChange={setGraph} />- ref 中的
NodeWrightApi从挂载的同一次提交起可用:父组件第一个useLayoutEffect/useEffect中即可调用。 - StrictMode 的模拟重挂载会换成新的控制器,ref 随之指向新控制器的 API。
onMount(api)在每个控制器挂载到渲染出的元素后调用,是首次适配视口的位置:StrictMode 重挂载与key变化创建的新控制器都会再调用一次,因此不会遗漏,例如onMount={(api) => api.view.fit.graph(72)}。useNodeWrightApi()只能在renderBackground/renderOverlay渲染的内容和 DOM 节点组件中调用,其他位置会抛错。
renderBackground 与 renderOverlay 的参数与 Vue 的 background / overlay 插槽 props 相同:
| render prop | 参数 |
|---|---|
renderBackground |
api、graph、readonly、gridState、interactionState、nodeEditorState、toggleGrid、renderContext |
renderOverlay |
api、graph、selection、gridState、interactionState、nodeEditorState、contextMenuState |
import { useState } from 'react'
import type { GraphSnapshot } from '@node-wright/core/protocol'
import type { NodeWrightToolbarItem } from '@node-wright/core/view'
import { NodeWright, type NodeWrightOverlayRenderProps } from '@node-wright/react'
declare const initialGraph: GraphSnapshot
declare const toolbarItems: NodeWrightToolbarItem[]
function Toolbar({ api }: NodeWrightOverlayRenderProps) {
return (
<div className="toolbar">
{api.menu.resolve.toolbar().map((item) => (
<button
key={item.id}
type="button"
disabled={item.disabled}
onClick={(event) => item.run(event.nativeEvent)}
>
{item.label}
</button>
))}
</div>
)
}
export function Editor() {
const [graph, setGraph] = useState(initialGraph)
return (
<NodeWright
graph={graph}
onGraphChange={setGraph}
toolbarItems={toolbarItems}
renderOverlay={Toolbar}
/>
)
}render props 在控制器创建之后才会调用;服务端渲染与首次提交之前不调用。
theme.colorScheme('dark' 默认或 'light')选择内置调色板,根元素渲染为 data-color-scheme(服务端渲染时由 theme 直接得出),style.css 中的设计令牌随之切换;其余主题字段逐项覆盖颜色。nodeStatus 按节点 id 传入执行状态,默认 DOM 节点显示状态角标(DefaultDomNode 的 memo 比较包含 status),自定义 DOM 节点从 props 的 status 读取。两者都按引用比较,用模块常量或 state:
const LIGHT = { colorScheme: 'light' } as const
const [nodeStatus, setNodeStatus] = useState<Record<string, NodeWrightNodeStatus>>({})
return <NodeWright graph={graph} onGraphChange={setGraph} theme={LIGHT} nodeStatus={nodeStatus} />节点类型的 accent 决定默认节点标题栏的色标,见 controller-api.md。
minimap prop 打开小地图:true 使用默认尺寸 200 × 136,也可以传入 NodeWrightMinimapOptions(width、height、padding):
<NodeWright graph={graph} onGraphChange={setGraph} minimap />
<NodeWright graph={graph} onGraphChange={setGraph} minimap={{ width: 240, height: 160 }} />小地图渲染在根元素内、性能浮层之后、renderOverlay 的内容之前(.nw-minimap,内含 .nw-minimap__canvas 与可见区域框 .nw-minimap__viewport,拖动时加 .nw-minimap--dragging),外观来自 style.css,可以在应用样式中覆盖这些类名。点击小地图把视口中心移到该处,拖动平移视口,获得焦点后方向键平移视口(Shift 加速);平移结束时调用一次 onViewportChange(source 为 'minimap' 或 'minimap.keyboard')。完整行为见 controller-api.md。
minimap与其他选项一样按引用比较:内联对象每次渲染都会触发一次update(),但控制器按值比较尺寸,内容相同时不会重算或重绘。- 小地图元素在 layout effect 中挂载到控制器,StrictMode 的模拟重挂载会先解绑再重新挂载;关闭
minimap或卸载组件时解绑。 - 与其他编辑器图层一样,小地图在控制器创建之后才渲染,服务端渲染不输出它。
控制器是外部资源,适配层从不在渲染过程中创建它,而是在一个 layout effect 中创建、mount,并在清理时 destroy:
- StrictMode(React 18 与 19)的模拟卸载会销毁第一个控制器并创建新的控制器,不会泄漏,也不会调用已销毁的控制器。
- 传入外部
store时,任何时刻只有一个控制器订阅它;它持有图与注册表,不能同时传graph、nodeDefinitions、edgeDefinitions、commands、connectionValidator(会抛错),见 controller-api.md。 - 默认 DOM 节点的交互控件(
createDomNodeControls)同样在 layout effect 中挂载,StrictMode 下会随之销毁并重新挂载。
- 服务端只输出根元素(含
className、aria-label)与两个画布,不访问 DOM,也不调用 render props;gridVisible={false}时网格画布带display:none。 - 客户端首次渲染与服务端输出一致,hydrate 不会出现不一致;节点层在挂载后的提交中渲染。
- 适配层在服务端使用
useEffect代替useLayoutEffect,React 18 不会报告 layout effect 警告。 - 包内没有
'use client'指令。在 React Server Components 框架中,请在客户端组件里渲染NodeWright。
domApi 的手势入口(interaction.pointerDown、ports.startConnection / finishConnection、resize.start)和 createDomNodeControls 按 DOM 监听语义工作:
- 手势在
event.currentTarget上捕获指针(例如尺寸手柄在拖动过程中保持光标); event.stopPropagation()阻止原生冒泡,避免节点内的控件触发画布手势。
React 的合成事件委托在根容器上派发,nativeEvent.currentTarget 不是绑定元素,原生冒泡也已经发生,因此自定义 React DOM 节点必须用原生监听器把事件交给 domApi。默认 DOM 节点就是这样实现的。示例:
import { memo, useEffect, useRef } from 'react'
import type {
NodeWrightDomNodeApi,
NodeWrightDomNodeProps,
NodeWrightResolvedDomNodePort,
} from '@node-wright/core/view'
import type { NodeWrightDomComponent } from '@node-wright/react'
function TaskPort(props: {
port: NodeWrightResolvedDomNodePort
side: 'input' | 'output'
domApi: NodeWrightDomNodeApi
}) {
const { port, side, domApi } = props
const ref = useRef<HTMLSpanElement>(null)
useEffect(() => {
const element = ref.current
if (!element) {
return undefined
}
const down = (event: PointerEvent) => {
event.stopPropagation()
domApi.ports.startConnection(port.id, event)
}
const up = (event: PointerEvent) => {
domApi.ports.finishConnection(port.id, event)
}
const enter = () => {
domApi.ports.previewConnection(port.id)
}
const leave = () => {
domApi.ports.previewConnection(null)
}
element.addEventListener('pointerdown', down)
element.addEventListener('pointerup', up)
element.addEventListener('pointerenter', enter)
element.addEventListener('pointerleave', leave)
return () => {
element.removeEventListener('pointerdown', down)
element.removeEventListener('pointerup', up)
element.removeEventListener('pointerenter', enter)
element.removeEventListener('pointerleave', leave)
}
}, [domApi, port.id])
return (
<span
ref={ref}
className={`task-node__port task-node__port--${side}`}
style={{ top: port.top }}
/>
)
}
function TaskNodeView({ domApi, domModel, selected }: NodeWrightDomNodeProps) {
const ref = useRef<HTMLElement>(null)
useEffect(() => {
const element = ref.current
if (!element) {
return undefined
}
const down = (event: PointerEvent) => {
domApi.interaction.pointerDown(event)
}
element.addEventListener('pointerdown', down)
return () => element.removeEventListener('pointerdown', down)
}, [domApi])
return (
<article ref={ref} className={selected ? 'task-node task-node--selected' : 'task-node'}>
<header className="task-node__title">{domModel.title}</header>
{domModel.inputs.map((port) => (
<TaskPort key={port.key} port={port} side="input" domApi={domApi} />
))}
{domModel.outputs.map((port) => (
<TaskPort key={port.key} port={port} side="output" domApi={domApi} />
))}
</article>
)
}
/** 只比较本组件读取的 props,平移和缩放不会重渲染它。 */
export const TaskNode: NodeWrightDomComponent = memo(
TaskNodeView,
(previous, next) =>
previous.domModel === next.domModel &&
previous.domApi === next.domApi &&
previous.selected === next.selected,
)普通的点击、输入等不涉及 domApi 手势的交互可以照常使用 React 事件;如需阻止它们触发画布手势,同样要在原生 pointerdown 监听器中调用 stopPropagation()。
- 键为节点类型
dom.component的值,值为ComponentType<NodeWrightDomNodeProps>;缺失的键在渲染该节点时抛出NodeWright has no DOM node component registered as "<key>".。默认节点的键(NODE_WRIGHT_DEFAULT_DOM_COMPONENT)由适配层内置,无需注册。 - 组件收到的 props 见 DOM 节点组件契约,另加渲染器
props(context)返回的附加字段。 context、screenBounds、zoom、theme、inputs/outputs每个视口帧都会更新;domModel与domApi在节点本身变化前保持引用不变。默认节点只比较domModel、domApi、selected、dragging、connectionSource;自定义组件需要时用memo自行比较。- 连线锚点按
domModel计算:输入端口在节点左边缘、输出端口在右边缘,纵向位置为port.top。 - 组件内可以调用
useNodeWrightApi()取得编辑器 API。 - 注册的组件请在模块级定义:在渲染过程中内联创建的组件每次渲染都是新的组件类型,会导致对应节点反复卸载重挂。
domComponents不是编辑器选项,变化时不会重建 Store。