用途:指导在 Blender 中实现复杂操作符(Operator),覆盖模态操作符、文件浏览器、批处理和多步交互工作流,并规避定时器泄漏、撤销失效等常见错误。
主要能力与要点:
- 模态操作符与定时器:用 wm.event_timer_add(0.01, window=context.window) 与 wm.modal_handler_add(self) 实现分帧处理;必须在 cancel() 和 {'FINISHED'} 路径都清理定时器;modal() 中处理 ESC 与 RIGHTMOUSE 以允许取消。
- 文件浏览器:使用 ImportHelper/ExportHelper 混入类,ExportHelper 必须设置 filename_ext;也可用 fileselect_add 手动实现;导入导出菜单分别注册到 TOPBAR_MT_file_import/export,并在 unregister() 中移除。
- 撤销:修改场景数据的操作符应设 bl_options = {'REGISTER', 'UNDO'},'UNDO' 单独无效;重复快速调用用 'UNDO_GROUPED';返回 {'CANCELLED'} 不产生撤销步骤,取消前需恢复状态。
- 批处理:迭代前复制集合(如 list(context.selected_objects)、obj.modifiers[:]);Blender 4.0+ 用 context.temp_override() 覆盖上下文。
- 进度报告:wm.progress_begin/update/end,或 header_text_set;4.0+ 可用 layout.progress()。
- 多步工作流:invoke_props_dialog 收集参数,或在 modal() 中用状态机处理连续点击。
- 延迟执行:bpy.app.timers.register() 适合后台任务与线程桥接,返回 None 只执行一次,返回 float 则重复;禁止从后台线程修改 bpy.data,应通过 queue.Queue 转回主线程。
限制与注意:定时器间隔为最小值,实际可能更长;同步 execute() 期间界面冻结、不会重绘;wm.progress_end() 不会立即重置光标(已知 Blender 缺陷);文档含 Blender 3.x/4.0+/5.x 兼容性差异,如字典式上下文覆盖在 4.0 已移除。具体 API 签名与完整示例见其 references 目录,本资料未提供更多细节。