XCEngine/docs/api/XCEngine/Editor/UI/ReferencePicker/ReferencePicker.md

ReferencePicker

命名空间: XCEngine::Editor::UI

类型: utility-header

源文件: editor/src/UI/ReferencePicker.h

描述: 提供统一的资产 / 场景对象引用选择控件，支持搜索、拖拽资产、双 tab 浏览和清空当前引用。

概述

ReferencePicker 是当前 Inspector 和脚本字段编辑里最重要的“引用类型 UI”之一。

它解决的是：在不直接暴露原始路径文本框的前提下，让用户选择：

• 项目资产
• 当前场景中的对象

当前公开内容

类型

• ReferencePickerTab
• ReferencePickerOptions
• ReferencePickerInteraction

主入口

• DrawReferencePickerControl(...)

当前行为

调用后会先画出一个只读引用字段，随后支持：

• 点击打开 popup
• 接收 ASSET_ITEM 拖放 payload
• 显示 Assets / Scene 双 tab
• 搜索过滤
• 清空当前引用

资产候选当前来自 ProjectManager 的项目树；场景候选当前来自 SceneManager 的根节点递归遍历。

返回值会表达三种结果：

• assignedAssetPath
• assignedSceneObjectId
• clearRequested

当前依赖关系

• 资产路径会通过 ProjectFileUtils::MakeProjectRelativePath(...) 归一化到项目相对路径。
• 搜索逻辑复用 SearchText。
• 图标绘制复用 BuiltInIcons。

当前使用位置

• InspectorPanel.cpp
• ScriptComponentEditor.h
• AssetReferenceEditorUtils.h

当前实现边界

• 当前 scene 选择范围只覆盖当前已加载场景层级。
• 状态缓存通过 ImGuiID 持有，不是独立可序列化对象。
• 这套控件同时支持资产和场景对象，但具体调用方可以通过选项关闭任一 tab。

相关文档

• 当前模块
• SearchText
• AssetReferenceEditorUtils