---

name: using-keys description: ReactUMG key 使用规范。在渲染列表、map 循环、拖拽预览、动态组件等场景时激活。key 标识组件身份而非位置，禁止使用坐标/索引等频繁变化的值作为 key，避免性能问题和组件重建。

ReactUMG key 使用规范

核心原则

key 标识组件身份，不是状态！

❌ 绝对禁止：坐标作为 key

Copy// ❌❌❌ 严重错误！每帧都重建组件
<DragPreview
    key={`${mouseX}-${mouseY}`}  // 鼠标移动就变！
    Slot={{Left: mouseX, Top: mouseY}}
/>
// 后果：性能崩溃、动画失效、大量 GC

✅ 正确做法：身份标识作为 key

Copy// ✅ 正确：key 标识"这是哪个物品"
<DragPreview
    key={item.id}  // 只有换物品才变
    item={item}
    Slot={{Left: mouseX, Top: mouseY}}  // 位置通过 Slot 更新
/>

key 使用决策表

React 的工作原理

Copy// key 相同 → 复用组件，只更新 props
<Component key="fixed" Slot={{Left: 100}} />
<Component key="fixed" Slot={{Left: 150}} />
// React：调用 update(oldProps, newProps)

// key 不同 → 销毁旧组件，创建新组件
<Component key="a" />
<Component key="b" />
// React：RemoveChild(旧) + CreateWidget(新)

UE 开发者注意

Copy// React 的 render() ≠ UE 的 CreateWidget()
render() {
    return <DragPreview key={item.id} />;
}
// 这不会每次都创建新 Widget！
// React 会复用 key 相同的组件

记住：key 应该回答"这是谁"，而不是"它在哪里"或"它长什么样"。