基于 ImGui Docking 的界面布局定制

在使用 Immediate Mode GUI 框架 ImGui 的高级功能时，停靠（Docking）系统允许开发者将多个窗口组合成可拖拽、合并的复合视图。虽然标准头文件提供基础接口，但若要构建特定的启动布局，需要调用内部头文件中的 DockBuilder API。

环境准备与依赖引入

要实现自定义的初始窗口排列，必须确保项目开启了 DockingEnable 配置标志，并引入内部接口声明：

#include <imgui.h>
#include <imgui-docking/imgui_internal.h>

主容器与停靠区域构建

首先需要一个宿主窗口来承载整个停靠空间。该窗口通常设置为全屏且无装饰，以便内部节点能够自由扩展至视口范围。以下示例展示了如何初始化这个根容器：

// 定义唯一标识符，避免 ID 冲突
static const char* C_ROOT_CONTAINER = "MainDockHost";
static const char* C_LAYOUT_ID      = "_DefaultLayoutSchema";

// 获取视口信息以适配主窗口位置
const ImGuiViewport* view_main = ImGui::GetMainViewport();
ImGui::SetNextWindowPos(view_main->WorkPos);
ImGui::SetNextWindowSize(view_main->WorkSize);
ImGui::SetNextWindowViewport(view_main->ID);

// 配置宿主窗口标志：去除背景、禁用移动与滚动
int base_flags = ImGuiWindowFlags_NoTitleBar 
               | ImGuiWindowFlags_NoResize 
               | ImGuiWindowFlags_NoMove 
               | ImGuiWindowFlags_NoBackground 
               | ImGuiWindowFlags_MenuBar
               | ImGuiWindowFlags_NoDocking; // 禁止将此窗口自身作为停靠点

接下来是核心逻辑，我们需要在每一帧检查是否已经构建了节点树。如果不存在根节点，则执行一次性的布局树构建操作：

ImGui::PushStyleVar(ImGuiStyleVar_WindowBorderSize, 0.0f);
ImGui::Begin(C_ROOT_CONTAINER, nullptr, base_flags);

if (ImGui::GetIO().ConfigFlags & ImGuiConfigFlags_DockingEnable) {
    ImGuiID master_node_id = ImGui::GetID(C_LAYOUT_ID);
    
    // 仅当未存在节点树时构建，防止重复重建
    if (!ImGui::DockBuilderGetNode(master_node_id)) {
        ImGui::DockBuilderRemoveNode(master_node_id); // 清理旧残留
        
        // 添加根节点
        ImGuiID center_root = ImGui::DockBuilderAddNode(master_node_id, ImGuiDockNodeFlags_None);
        
        // 设置根节点尺寸和位置
        ImGui::DockBuilderSetNodePos(center_root, ImVec2(0, 0));
        ImGui::DockBuilderSetNodeSize(center_root, ImGui::GetWindowSize());
        
        // --- 分层分割策略 ---
        
        // 第一步：从根节点切分出左侧区域 (占宽度的 25%)
        ImGuiID left_side_id;
        ImGui::DockBuilderSplitNode(center_root, ImGuiDir_Left, 0.25f, &left_side_id, &center_root);
        
        // 第二步：从剩余根节点切分出右侧区域 (占剩余空间的 33%)
        ImGuiID right_side_id;
        ImGui::DockBuilderSplitNode(center_root, ImGuiDir_Right, 0.25f / 0.75f, &right_side_id, &center_root);
        
        // 第三步：从当前中心节点向下切出底部区域
        ImGuiID bottom_area_id;
        ImGui::DockBuilderSplitNode(center_root, ImGuiDir_Down, 0.20f, &bottom_area_id, &center_root);
        
        // 第四步：细化左侧，分为上 (工具) 下 (属性)
        ImGuiID left_top_part, left_bot_part;
        ImGui::DockBuilderSplitNode(left_side_id, ImGuiDir_Up, 0.5f, &left_top_part, &left_bot_part);
        
        // --- 分配窗口到具体节点 ---
        
        // 隐藏最终中心节点的标签栏，使其成为纯绘图区
        ImGui::DockBuilderGetNode(center_root)->LocalFlags |= ImGuiDockNodeFlags_HiddenTabBar;
        
        // 绑定具体业务窗口 ID
        ImGui::DockBuilderDockWindow("View_Canvas_Main", center_root);
        ImGui::DockBuilderDockWindow("Panel_Resource_Tree", left_top_part);
        ImGui::DockBuilderDockWindow("Panel_Property_Sheet", left_bot_part);
        ImGui::DockBuilderDockWindow("Panel_Debug_Console", right_side_id);
        
        // 底部区域可同时容纳多个日志窗口
        ImGui::DockBuilderDockWindow("Log_System_Events", bottom_area_id);
        ImGui::DockBuilderDockWindow("Log_Performance_Metrics", bottom_area_id);
        
        // 完成构建序列
        ImGui::DockBuilderFinish(master_node_id);
    }
    
    // 渲染停靠空间，需保持样式一致
    ImGui::PushStyleColor(ImGuiCol_DockingEmptyBg, IM_COL32_BLACK_TRANS);
    ImGui::DockSpace(master_node_id, ImVec2(0, 0), ImGuiDockNodeFlags_None);
    ImGui::PopStyleColor();
}
ImGui::PopStyleVar();
ImGui::End();

子窗口内容渲染与复位逻辑

创建好节点结构后，各个子窗口仍需通过标准的 Begin/End 块进行绘制。此外，可以在某个工具栏中加入重置按钮，一旦触发，只需移除根节点即可让布局重新初始化。

// 示例：资源面板
if (ImGui::Begin("Panel_Resource_Tree")) {
    ImGui::Text("Hierarchy Structure");
    // ... UI elements
}
ImGui::End();

// 示例：调试控制台（包含布局重置功能）
if (ImGui::Begin("Panel_Debug_Console")) {
    ImGui::Text("Output Log...");
    
    if (ImGui::Button("Reset Default Layout")) {
        ImGuiID master_node_id = ImGui::GetID("_DefaultLayoutSchema");
        // 强制销毁当前布局，下一帧会自动重建为初始状态
        if (ImGui::DockBuilderGetNode(master_node_id)) {
            ImGui::DockBuilderRemoveNode(master_node_id);
        }
    }
}
ImGui::End();

节点分割函数的参数解析

理解 DockBuilderSplitNode 的行为对于自定义复杂布局至关重要。该函数签名大致如下：
ImGuiID SplitNode(ImGuiID node, ImGuiDir dir, float size_ratio, ImGuiID* out1, ImGuiID* out2)

• node: 待分割的父节点 ID。
• dir: 分割方向（左、右、上、下）。
• size_ratio: 新生成的第一个子节点相对于父节点的大小比例。
• out1 / out2: 用于接收生成的两个新节点的指针。

值得注意的是，如果 out1 传为 nullptr，则返回的值代表分割出的第一个节点；而第二个输出通常指代剩余的父节点部分。这意味着我们可以递归地调用此函数来构建树状结构。例如，先切分左侧，再将左侧切分为上下两部分，每次调用都会生成新的局部坐标系下的子容器。