XCEngine/docs/api/XCEngine/Editor/Actions/ProjectActionRouter/ProjectActionRouter.md

ProjectActionRouter

命名空间: XCEngine::Editor::Actions

类型: header-helper

源文件: editor/src/Actions/ProjectActionRouter.h

描述: Project 面板交互路由 helper，负责资源拖拽载荷、资源打开、返回上级导航、背景清选和项目项右键菜单目标建立。

概述

ProjectActionRouter 当前不是一个“大而全的项目面板行为中心”，而是一组比较薄的交互 helper。

它的职责边界和 ProjectPanel / ProjectCommands 的分工很明确：

• ProjectPanel 负责目录树、面包屑、资源网格和上下文菜单的具体布局
• ProjectActionRouter 负责把少量通用交互翻译成稳定动作
• ProjectCommands 负责真正修改项目内容

因此当前这页不应再描述成“承载创建文件夹弹窗、重命名、复制粘贴等完整资源 workflow”。那些语义如今主要已经在面板层和命令层展开了。

当前覆盖的能力

按 editor/src/Actions/ProjectActionRouter.h 当前实现，这组 helper 主要覆盖：

• 资源拖拽 payload 协议
• 判断某个资源是否正处于拖拽中
• 打开资源
• 工具栏返回上级导航
• Project 背景左键清选
• Project 空白区右键菜单请求
• Project 资源项右键菜单目标记录

关键 helper

拖拽载荷

当前项目资源拖拽协议固定为：

• ProjectAssetPayloadType() -> "ASSET_ITEM"

拖拽数据本身不是 AssetItemPtr，而是：

• item->fullPath.c_str()

也就是说，当前 Project 拖拽协议使用的是“资源全路径字符串载荷”，而不是对象指针。

这和 Hierarchy 里的实体拖拽不同，也更适合项目资源这种需要跨刷新定位的对象。

相关 helper 包括：

• GetDraggedProjectAssetPath()
• IsProjectAssetBeingDragged(item)
• BeginProjectAssetDrag(item, iconKind)

打开资源

OpenProjectAsset(...) 当前只是一个薄封装：

1. 先调用 Commands::CanOpenAsset(item)
2. 合法时再调用 Commands::OpenAsset(context, item)

因此“什么资源可以打开”的判定权并不在 action router，而在命令层。

返回上级

DrawProjectNavigateBackAction(...) 当前负责：

• 基于 projectManager.CanNavigateBack() 计算按钮是否启用
• 点击后调用 projectManager.NavigateBack()

这是 Project 工具栏里少量直接在 action 层完成的导航动作之一。

背景清选

HandleProjectBackgroundPrimaryClick(...) 的当前语义是：

• 只有窗口悬停
• 左键点击
• 当前没有悬停任意 item
• 当前不处于 rename 状态

时，才调用：

• projectManager.ClearSelection()

这让 ProjectPanel 可以在“空白处点一下取消选中”和“行内重命名期间不要误清选”之间保持一致行为。

右键菜单目标

当前 router 提供了两组与上下文菜单相关的 helper：

• RequestProjectEmptyContextPopup(...)
• HandleProjectItemContextRequest(...)

前者只负责在空白区域右键时请求 popup；后者则会：

1. 先把该项设为当前选中资源
2. 再把它写入 TargetedPopupState<AssetItemPtr>

这样项目项右键菜单在打开时，选择状态和 popup target 是同步的。

当前没有负责什么

为了避免和旧文档混淆，需要明确当前这组 helper 不 负责：

• 资源重命名提交
• 创建文件夹 / 创建材质
• 删除资源
• 移动资源到目录
• 复制路径

这些行为如今分别在：

• ProjectPanel
• ProjectCommands

中完成。

设计说明

当前 ProjectActionRouter 的设计取向是合理的，因为它只保留那些真正适合抽成共享交互协议的部分：

• 拖拽 payload
• 打开资源入口
• 背景清选
• 右键菜单目标建立

而把更强业务语义留给 ProjectPanel 和命令层。这比把所有资源 workflow 都堆进一个 router header 更容易维护。

当前限制

• 当前动作层本身不提供资源复制 / 粘贴协议。
• iconKind 参数在 BeginProjectAssetDrag(...) 里当前没有实际参与绘制，拖拽预览被关闭。
• 这组 helper 仍然假设调用点位于 Project 面板即时模式 UI 主循环中。

相关文档

• Actions
• ProjectPanel
• ProjectCommands
• PopupState