# Node Dev
> React Flow 节点开发的完整指南。包含节点类型、Handles 连接规则、数据传递架构和开发模板。适用于创建新的自定义节点或修改现有节点。
- Skill: `majiayu000/node-dev` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/node-dev`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/node-dev/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/node-dev
---
# React Flow 节点开发技能 v2.0
> **更新日期**: 2026-01-23
> **版本**: v2.0.0
> **定位**: WinJin AIGC 项目的节点开发核心指南
---
## 节点类型分类
| 类型 | 颜色 | Handle 位置 | 示例 |
|------|------|-----------|------|
| **输入节点** | 蓝色 (#3b82f6) | Handle 在右侧 | APISettingsNode, CharacterLibraryNode |
| **处理节点** | 绿色 (#10b981) | Handle 在左右两侧 | VideoGenerateNode, PromptOptimizerNode |
| **输出节点** | 浅蓝 (#0ea5e9) | Handle 在左侧 | TaskResultNode, CharacterResultNode |
---
## Handles 连接规范 ⭐ 核心
### 输入端口到源节点类型的映射
| 目标端口 | Handle ID | 源节点类型 | 数据传递 | 用途 |
|---------|-----------|----------------|----------|------|
| `prompt-input` | 右侧 | textNode, promptOptimizerNode, narratorProcessorNode | connectedPrompt | 文本提示词输入和优化 |
| `character-input` | 右侧 | characterLibraryNode | connectedCharacters | 角色库数据传递 |
| `images-input` | 右侧 | referenceImageNode | connectedImages | 参考图片传递 |
| `api-config` | 右侧 | apiSettingsNode | apiConfig | API 配置连接 |
| `task-input` | 左侧 | videoGenerateNode, storyboardNode, characterCreateNode | taskId | 任务结果监听 |
### Handle 连接验证机制
```javascript
// ✅ App.jsx 中的验证逻辑
const validCharacterSourceTypes = ['characterLibraryNode'];
if (sourceNode && validCharacterSourceTypes.includes(sourceNode.type)) {
newData.connectedCharacters = sourceNode.data.connectedCharacters;
} else {
newData.connectedCharacters = undefined; // 静默失败
}
```
---
## 数据传递架构 ⭐ 重要
### 核心原则
**源节点直接更新目标节点，避免依赖父组件中转**
```javascript
// ✅ 正确：源节点直接更新目标节点
const edges = getEdges();
const outgoingEdges = edges.filter(e => e.source === nodeId);
setNodes((nds) =>
nds.map((node) => {
// 更新自己
if (node.id === nodeId) {
return { ...node, data: { ...node.data, selectedCharacters } };
}
// 直接更新目标节点（绕过 App.jsx）
const isConnected = outgoingEdges.some(e => e.target === node.id);
if (isConnected) {
return { ...node, data: { ...node.data, connectedCharacters } };
}
return node;
})
);
```
### 事件系统（异步数据）
```javascript
// 发送节点
window.dispatchEvent(new CustomEvent('video-task-created', {
detail: { sourceNodeId: nodeId, taskId: id }
}));
// 接收节点
useEffect(() => {
const handleVideoCreated = (event) => {
const { sourceNodeId, taskId } = event.detail;
if (data.connectedSourceId === sourceNodeId) {
setTaskId(taskId);
}
};
window.addEventListener('video-task-created', handleVideoCreated);
return () => window.removeEventListener('video-task-created', handleVideoCreated);
}, [data.connectedSourceId]);
```
---
## 节点开发最佳实践
### 1. useState 同步到 node.data
```javascript
// 初始化
const [manualPrompt, setManualPrompt] = useState(data.manualPrompt || '');
// 同步到 node.data
useEffect(() => {
if (manualPrompt !== data.manualPrompt) {
setNodes((nds) =>
nds.map((node) =>
node.id === nodeId
? { ...node, data: { ...node.data, manualPrompt } }
: node
)
);
}
}, [manualPrompt, nodeId, setNodes, data.manualPrompt]);
```
### 2. useEffect 依赖最佳实践
```javascript
// ❌ 错误：依赖 data 对象
useEffect(() => {
// ...
}, [data]); // data 每次都是新引用
// ✅ 正确：依赖具体值
useEffect(() => {
// ...
}, [data.value]); // 只依赖实际变化的值
```
### 3. 防止节点内交互触发拖动
```jsx
{/* 使用 nodrag 类 */}
```
### 4. 双显示功能（角色引用）
```javascript
// 创建映射
const usernameToAlias = React.useMemo(() => {
const map = {};
connectedCharacters.forEach(char => {
map[char.username] = char.alias || char.username;
});
return map;
}, [connectedCharacters]);
// 真实ID → 显示别名
const realToDisplay = (text) => {
let result = text;
Object.entries(usernameToAlias).forEach(([username, alias]) => {
const regex = new RegExp(`@${username}(?=\\s|$|@)`, 'g');
result = result.replace(regex, `@${alias}`);
});
return result;
};
// 显示别名 → 真实ID
const displayToReal = (text) => {
let result = text;
const sortedAliases = Object.entries(usernameToAlias)
.sort((a, b) => b[1].length - a[1].length);
sortedAliases.forEach(([username, alias]) => {
const regex = new RegExp(`@${alias}(?=\\s|$|@)`, 'g');
result = result.replace(regex, `@${username}`);
});
return result;
};
// Textarea 显示别名