第15章：插件与自定义工作台开发

1. 为什么开发工作台

当宏变多、命令需要图标、菜单、工具栏、任务面板和偏好设置时，就应考虑开发工作台。工作台可以把一组业务工具组织成 FreeCAD 原生界面，例如企业标准件库、行业建模工具、自动出图工具、格式转换工具。

2. 工作台基本结构

典型 Python 工作台包含：

• Init.py：App 层初始化。
• InitGui.py：GUI 层工作台注册。
• 命令类：定义资源、激活逻辑、可用状态。
• 图标资源：SVG 或 PNG。
• 任务面板：Qt UI 或 Python 构建界面。
• 模块代码：几何、导入导出、工具函数。

FreeCAD 官方模块目录中大量工作台也采用 Init.py、InitGui.py 入口。阅读现有模块是最好的学习方式。

3. 命令设计

一个好命令应具备：

• 清晰名称和工具提示。
• 可预测的输入对象。
• 对错误选择给出提示。
• 支持撤销/重做或至少不破坏文档。
• 尽量通过对象属性保存参数。
• 在报告视图输出有用信息。

命令不应把业务逻辑都写在按钮回调中。应将核心算法与 GUI 分离，便于测试和脚本调用。

4. 任务面板

任务面板用于复杂输入。设计原则：

• 字段按工作流程排列。
• 提供默认值。
• 明确单位。
• 对非法输入即时提示。
• “预览”和“确定”逻辑分离。
• 取消时恢复或不提交修改。

Qt Designer 可制作 UI 文件，也可用 PySide 动态创建界面。

5. 资源与图标

图标应简洁，符合 FreeCAD 工具栏视觉。建议使用 SVG，便于缩放。资源路径不要写死，应相对模块目录解析。

6. 参数化对象封装

工作台的核心价值常在于创建业务对象，而不是一次性几何。例如“槽钢”“法兰”“支吊架”“设备基础”。这些对象应：

• 有明确属性。
• 支持重计算。
• 可从属性面板修改。
• 可导出标准几何。
• 可被工程图和装配引用。

7. 插件发布

发布插件前检查：

• 目录结构清晰。
• README 或文档说明安装和用法。注意本博客教程目录不生成 README，但插件项目本身通常需要。
• 许可证明确。
• 支持的 FreeCAD 版本明确。
• 无硬编码本机路径。
• 依赖可安装。
• 典型模型测试通过。

Addon Manager 生态要求插件元数据规范，正式发布前应参考官方插件要求。

8. 兼容性

FreeCAD API 会随版本演进。插件应避免依赖未公开内部细节。建议：

• 在稳定版和开发版都测试。
• 对可选 API 做存在性检查。
• 捕获异常并给出版本提示。
• 不要覆盖全局配置。
• 保持 Python 代码风格清晰。

9. 从宏到工作台的迁移

迁移步骤：

1. 把宏中的业务逻辑提取为函数。
2. 创建命令类调用这些函数。
3. 加入图标和菜单。
4. 增加任务面板输入参数。
5. 将输出对象改为参数化对象。
6. 补充示例文件和文档。

完成迁移后，用户可以像使用内置命令一样使用你的工具。