FreeCAD Start 工作台重构解析从 QtWebEngine 依赖到纯 C/QML 的模型-视图架构【免费下载链接】FreeCADOfficial source code of FreeCAD, a free and opensource multiplatform 3D parametric modeler.项目地址: https://gitcode.com/GitHub_Trending/fr/FreeCAD本文深入剖析 FreeCAD 项目中 Start 工作台的重新设计与实现。作为 FreeCAD 启动页的核心载体新 Start 工作台以消除对 QtWebEngine 的依赖为出发点采用纯 C 编写模型层、以 Qt Widgets 构建界面并规划了向 QtQuick/QML 迁移的长期路线。读完本文你将掌握 Start 工作台的三区域布局结构、基于 MVC 模式的最近文件/示例文件展示机制、以及供主题Preference Pack作者使用的三个界面参数及其底层作用路径。一、背景为什么要重写 Start 工作台在 FreeCAD 中Start 工作台Workbench负责呈现应用启动后首先看到的页面——包括新建文件入口、最近文件列表与内置示例。旧版 Start 页面基于 HTML 组件构建依赖 Qt 的 WebEngine 模块。新 Start 工作台存在的首要理由就是消除 FreeCAD 对 QtWebEngine 的依赖——通过重新设计 Start 页面彻底去掉其中的 HTML 组件见 src/Mod/Start/README.md。这一依赖消除带来的直接收益包括减小运行时与构建体积不再需要随应用分发 WebEngine 及其渲染资源降低与 Qt 版本升级相关的兼容风险WebEngine 在部分平台、部分 Qt 版本上的可用性与维护成本较高为后续使用声明式 UI 技术QtQuick/QML铺路。需要说明的是新 Start 工作台与旧页面在一段时间内是并存过渡关系它最终将取代旧 Start 页面并继承其名称。二、长期规划向 QtQuick/QML 迁移README 明确给出了该工作台的技术演进路线当前阶段整个工作台用 C 编写界面基于 Qt Widgets长期目标从 Qt Widgets 迁移到 QtQuick/QML由 C 后端提供数据访问能力例如读取 FreeCAD 的最近文件列表。迁移的时机有明确约束需要在不再支持基于 Qt 5.12 的 Ubuntu 20.04 LTS 构建之后进行。原因在于Qt 5.15 及后续版本大幅改善了在同一个 CMake 工程中同时集成 QML 与 C 的体验而在 Qt 5.12 上做同样的 QML/C 混编集成会相当痛苦。值得强调的设计决策是当前阶段坚持用 C 编写是为了让模型model层可以被未来复用。README 原文的表述是the workbench is written in C so that the models can be reused later, and only the UI itself will have to change——即模型层现在就用 C 实现并保持 UI 无关未来迁移到 QML 时只需替换 View 层模型层可以直接平移。这一点在源码中也得到了印证DisplayedFilesModel的roleNames()方法见 DisplayedFilesModel.cpp把每一个数据角色映射成字符串名字author、baseName、company等注释明确说明这是为了与 QML 通信而定义——这些名字将来正是 QML 侧可直接引用的属性名。三、界面结构一个 QScrollArea 与三个区域Start 页面的主 UI 文件是 Gui/StartView.cpp核心类StartView本身是一个QScrollArea滚动区域它被嵌入到一个新建的 FreeCADMDIView多文档接口视图中。在滚动区域内部页面被划分为三个主要区域New File新建文件一组QPushButton每个按钮内嵌布局同时展示一张图标和两行文本标题 说明。当前这些按钮在QGridLayout中手动排布README 指出未来理想的做法是动态计算布局使得空间充足时按钮可以排成单行。从 StartView.cpp 可以看到当前实现已经演进为使用自定义的FlowLayout见 Gui/FlowLayout.h来承载 6 个NewFileButtonParametric Body、Assembly、2D Draft、BIM/Architecture、Empty File、Open File每个按钮点击后分别触发对应工作台的创建流程例如 PartDesign 按钮执行Std_New→ 激活PartDesignWorkbench→ 执行PartDesign_Body。Recent Files最近文件两个文件卡片File Card区域之一展示最近打开过的文件列表。该区域采用经典的Model-View-ControllerMVC架构以获得灵活性与可复用性。Examples示例另一个文件卡片区域复用与最近文件相同的视图类但挂接不同的模型展示 FreeCAD 资源目录examples下的内置示例文件。除这三个区域外源码还实现了可选的Custom Folder自定义文件夹区域通过CustomFolder参数启用以及首次启动引导页FirstStartWidget受FirstStart2024参数控制和主题选择页ThemeSelectorWidget它们通过QStackedWidget切换——这些属于 README 之外由源码补充的扩展细节。四、文件卡片区域的 MVC 架构README 用较多篇幅讲解 Recent Files 区域背后的 MVC 设计这也是新 Start 工作台最核心的架构亮点。在 Qt 的语境下该架构把职责拆分为三层Model模型数据本身即要展示什么View视图呈现数据的整体机制即怎么摆放Delegate委托当单个条目过于复杂、无法用简单视图直接渲染时例如要在特定布局中同时展示图片和文本由委托负责绘制具体条目。4.1 模型层RecentFilesModel与DisplayedFilesModelRoles最近文件的模型是RecentFilesModelApp/RecentFilesModel.h它继承自DisplayedFilesModelApp/DisplayedFilesModel.h是一个只读接口数据源是 FreeCAD 的偏好系统参数系统。其构造函数从User parameter:BaseApp/Preferences/RecentFiles参数组读取数据loadRecentFiles()会读取整型参数RecentFiles作为条数然后依次读取MRU0、MRU1、MRU2……等 ASCII 参数作为文件路径见 RecentFilesModel.cpp。也就是说最近文件列表的数据源头与 FreeCAD 菜单最近打开的文件是同一套MRU参数。DisplayedFilesModel是一个QAbstractListModel子类通过一组User Roles暴露每个文件的各项数据。DisplayedFilesModelRoles枚举DisplayedFilesModel.h定义了全部角色及其取值角色说明baseName文件名不含路径image缩略图/图标QByteArraysize文件大小人类可读格式如 KB/MBauthorFCStd 文件的作者元数据creationTime创建时间modifiedTime修改时间description文件描述company公司信息license许可证信息path文件完整路径并非所有文件都具备全部数据例如author这类元数据只对包含元信息头的FCStd文件可用。在代码中通过index.data(DisplayedFilesModelRoles::author)即可获取对应数据README 特别强调这些角色名author、baseName等也会以名字形式暴露给未来的 QML 层这正是 4.1 节提到的roleNames()映射。DisplayedFilesModel还内置了异步数据加载机制DisplayedFilesModel.cppaddFile()先校验文件可读并通过App::GetApplication().getImportTypes()判断扩展名是否为 FreeCAD 可打开类型不满足则直接跳过对fcstd文件投递FcstdInfoSource任务到全局QThreadPool异步读取文档元数据与内嵌缩略图对其他可打开类型投递ThumbnailSource任务生成缩略图fcmacro、py、csv、txt等被显式排除因为这类文件只显示通用图标结果通过信号回传后由processNewFcstdInfo/processNewThumbnail写回缓存并发出dataChanged全程用QMutex保护保证操作线程安全。4.2 视图层FileCardView视图是QListView的派生类FileCardViewGui/FileCardView.h。它在标准QListView之上只增加了一项功能height for width——根据文件卡片的数量与屏幕宽度把卡片自动排布成网格并据此正确计算控件高度实现自适应缩放。这是让多张文件卡片在窗口宽度变化时能整齐换行重排的关键。4.3 委托层FileCardDelegate卡片的具体外观由FileCardDelegateGui/FileCardDelegate.cpp负责渲染。该类使用简单的QVBoxLayout来绘制三样内容图标缩略图、文件名、文件大小。此外它还维护了一个QCacheQString, QPixmap缩略图缓存FileCardDelegate.cpp缓存容量按FileThumbnailIconsSize计算避免重复解码图片造成的性能开销。4.4 示例区域ExamplesModelExamples 区域复用上面同一套视图与委托类仅替换模型ExamplesModelApp/ExamplesModel.h。其数据来源是 FreeCAD 资源目录下的examples子目录App::Application::getResourceDir()examples见 ExamplesModel.cpploadExamples()列出该目录下所有可读文件并逐条加入模型按文件名排序若目录不可读则向控制台输出警告。仓库中与它对应的真实示例数据位于 data/examples包含PartDesignExample.FCStd、FEMExample.FCStd、ArchDetail.FCStd等。五、UI 设计原则与三个可配置参数README 明确了一条设计原则新 Start 工作台做最少的设计定制把外观控制权交给样式表Stylesheet作者通过 Qt 标准的QSSQt Style Sheets机制实现主题化。为此工作台只通过 3 个 FreeCAD 参数来控制组件间距与图标尺寸它们全部位于BaseApp/Preferences/Mod/Start/偏好组参数名默认值作用FileCardSpacing20文件卡片之间及周围的间距FileThumbnailIconsSize128文件卡片上缩略图的尺寸像素NewFileIconSize48每个新建文件按钮上图标的尺寸像素在源码中的实际消费位置可以印证参数的作用路径FileThumbnailIconsSize在 FileCardDelegate.cpp 等多处读取决定缩略图的绘制尺寸与缓存容量计算FileCardSpacing在 FileCardView.cpp网格卡片间距与 StartView.cpp页面布局间距中被读取NewFileIconSize在 NewFileButton.cpp 中读取决定新建文件按钮的图标尺寸。注上述参数在仓库不同代码路径中的读取默认值存在少量差异例如FileCardSpacing在 StartView.cpp 中默认 15、在 FileCardView.cpp 中默认 16README 给出的设计默认值为 20。主题作者如需精确控制应以实际设置值为准。5.1 参数的使用场景与限制README 特别指出当前阶段的三个限制这三个参数目前都没有直接暴露给普通用户新的 Start 工作台暂时没有偏好设置面板不过仓库中已存在 Gui/DlgStartPreferences.ui 与DlgStartPreferencesImp说明偏好面板已进入实现阶段这些参数的设计意图是供 Preference Pack偏好包/主题包作者使用用来辅助定制 FreeCAD 主题的外观等收到主题设计者的反馈后很可能进一步扩展参数集合。换言之若你想为 FreeCAD 定制一套主题并调整 Start 页的疏密与图标大小可以在偏好包配置中写入上述三个参数或直接通过 FreeCAD 参数编辑器在BaseApp/Preferences/Mod/Start分组下创建它们而不必改动任何代码。六、构建与源码导览新 Start 工作台的完整源码位于 src/Mod/Start目录结构如下App 层模型纯 CApp/RecentFilesModel.cpp、App/ExamplesModel.cpp、App/DisplayedFilesModel.cpp 及CustomFolderModel、FcstdInfoSource、ThumbnailSource、FileUtilitiesGui 层视图与界面Gui/StartView.cpp、Gui/FileCardView.cpp、Gui/FileCardDelegate.cpp、Gui/NewFileButton.cpp、Gui/FlowLayout.cpp 以及首次启动、主题选择、偏好面板等辅助组件资源与翻译Gui/Resources/Start.qrc 统一管理图标与主题缩略图Gui/Resources/translations 下提供了包括StartPage_zh-CN.ts简体中文在内的数十种语言翻译文件Python 入口Init.py 与 InitGui.py 负责工作台的注册与初始化另有 StartMigrator.py 处理从旧 Start 页面到新实现的迁移。构建方面工作台随 FreeCAD 主工程一起编译其 CMake 配置见 src/Mod/Start/CMakeLists.txt由于模型层全部为 C 实现且不依赖 QtWebEngine在支持 Qt 5.12 及以上版本的构建环境中均可正常编译这也正是当前不急于迁移 QML 的原因——QML 集成需要 Qt 5.15 才足够顺滑。七、小结新 Start 工作台是 FreeCAD 中一个小而精的架构改造范例它用一个纯 C 的模型层DisplayedFilesModel家族统一承载最近文件、示例文件与自定义文件夹三种数据源用可复用的FileCardViewFileCardDelegate渲染文件卡片界面风格完全交给 QSS 与偏好包参数掌控。整个设计始终在为未来切换到 QtQuick/QML保留接口——角色名映射、线程安全的模型操作、只读偏好数据源都是为 QML 前端预留的稳定契约。对于希望在 FreeCAD 中定制主题的开发者理解BaseApp/Preferences/Mod/Start分组下的三个参数及其代码消费路径是最直接也最安全的切入点。【免费下载链接】FreeCADOfficial source code of FreeCAD, a free and opensource multiplatform 3D parametric modeler.项目地址: https://gitcode.com/GitHub_Trending/fr/FreeCAD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考