using-keys

15195999826's avatarfrom 15195999826

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

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 9, 2026
[Code Review]

When & Why to Use This Skill

This Claude skill establishes essential best practices for ReactUMG key usage, specifically designed to optimize UI performance and component stability. It solves the critical problem of unnecessary widget reconstruction and performance degradation by ensuring keys identify component identity rather than transient states like coordinates or indices.

Use Cases

  • Optimizing dynamic list rendering and map loops to ensure efficient component reuse instead of full re-renders.
  • Implementing high-performance drag-and-drop previews where position updates (X/Y) must not trigger component destruction.
  • Managing state transitions during user switching or dynamic component loading to maintain UI continuity.
  • Reducing Unreal Engine Garbage Collection (GC) overhead by preventing the frequent creation and destruction of UI widgets.
nameusing-keys
descriptionReactUMG key 使用规范。在渲染列表、map 循环、拖拽预览、动态组件等场景时激活。key 标识组件身份而非位置，禁止使用坐标/索引等频繁变化的值作为 key，避免性能问题和组件重建。

ReactUMG key 使用规范

核心原则

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

❌ 绝对禁止：坐标作为 key

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

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

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

key 使用决策表

场景 key 值 正确性
列表渲染 item.id ✅
拖拽预览 item.id ✅
切换用户 userId ✅
位置更新 ${x}-${y} ❌
动画帧 frameIndex ❌

React 的工作原理

// 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 开发者注意

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

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