# ERPNext 语法：Hooks (hooks.py) hooks.py 中的挂钩使自定义应用程序能够扩展 Frappe/ERPNext 功能。 ## 快速参考 ### doc_events - 文档生命周期 # 在 hooks.py 中文档事件 = { “*”：{ “after_insert”：“myapp.events.log_all_inserts” }, “销售发票”：{ “验证”：“myapp.events.si_validate”， "on_submit": "myapp.events.si_on_submit" } } # 在 myapp/events.py 中进口冰沙 def si_validate(doc, 方法=无): """doc = 文档对象，方法 = 事件名称""" 如果 doc.grand_total < 0: frappe.throw("总数不能为负数") ### Scheduler_events - 定期任务 # 在 hooks.py 中调度程序事件 = { “每日”：[“myapp.tasks.daily_cleanup”]， "hourly_long": ["myapp.tasks.heavy_sync"], “克朗”：{ "0 9 * * 1-5": ["myapp.tasks.weekday_morning"] } } # 在 myapp/tasks.py 中 def daily_cleanup(): """无参数 - 自动调用""" frappe.db.delete("Log", {"creation": ["<", one_month_ago()]}) ###extend_bootinfo - 客户端数据注入 # 在 hooks.py 中 extend_bootinfo =“myapp.boot.extend_boot” # 在 myapp/boot.py 中 defextend_boot(bootinfo): """bootinfo = 前往 frappe.boot 的字典""" bootinfo.my_setting = frappe.get_single("我的设置").value // 客户端 console.log(frappe.boot.my_setting); ** ** ## 最常用的 doc_events 活动 |当 |使用案例 ---|---|--- `验证` |每次保存之前 |验证、计算 `on_update` |每次保存后 |通知、同步 `插入后` |新文档之后 |仅限创造的行动 `on_submit` |提交后 |分类帐分录 `on_cancel` |取消后 |反向条目 `on_trash` |删除前|清理 **完整列表** ：参见 [doc-events.md]() ** ** ## 调度程序事件类型活动 |频率|队列/超时 ---|---|--- `每小时` |每小时 |默认/5 分钟 `每日` |每天 |默认/5 分钟 `每周` |每周 |默认/5 分钟 `每月` |每个月 |默认/5 分钟 `每小时_长` |每小时 |长/25分钟 `daily_long` |每天 |长/25分钟 `cron` |自定义计时|默认/5 分钟 **Cron 语法和示例** ：请参阅 [scheduler-events.md]() ** ** ## 关键规则 ### 1\.调度程序更改后工作台迁移 # 必需 - 否则更改将不会被采纳工作台--站点站点名称迁移 ### 2\. doc_events 中没有提交 # ❌ 错误 def on_update（文档，方法=无）： frappe.db.commit() # 中断事务 # ✅ 正确 - Frappe 自动提交 def on_update（文档，方法=无）：更新相关文档（doc） ### 3\. on_update 之后通过 db_set 进行的更改 # ❌ 错误 - 更改丢失 def on_update（文档，方法=无）： doc.status = "已处理" # ✅ 正确 def on_update（文档，方法=无）： frappe.db.set_value(doc.doctype, doc.name, "状态", "已处理") ### 4\.繁重的任务要_长队列 # ❌ 错误 - 5 分钟后超时调度程序事件 = { "daily": ["myapp.tasks.process_all_records"] # 可能需要 20 分钟 } # ✅ 正确 - 25 分钟超时调度程序事件 = { "daily_long": ["myapp.tasks.process_all_records"] } ### 5\.任务不接收任何参数 # ❌ 错误 def my_task(some_arg): 通过 # ✅ 正确 def my_task(): # 获取函数内部的数据通过 ** ** ## Cron 语法备忘单 * * * * * * │ │ │ │ │ │ │ │ │ └── 星期几 (0-6, Sun=0) │ │ │ └──── 月份（1-12） │ │ └────── 一月中的哪一天 (1-31) │ └──────── 小时 (0-23) └────────── 分钟 (0-59) 图案|含义 ---|--- `*/5 * * * *` |每5分钟一班 `0 9 * * *` |每日 09:00 `0 9 * * 1-5` |平日 09:00 `0 0 1 * *` |每月第一天 `0 17 * * 5` |周五 17:00 ** ** ## doc_events 与控制器 Hook 方面| doc_events (hooks.py) | 文档事件控制器方法 ---|---|--- 地点 | `hooks.py` | `doctype/xxx/xxx.py` 范围 |挂钩其他文档类型 |只有自己的文档类型多个处理程序 | ✅ 是（列表）| ❌ 没有优先|后控制器 |第一通配符 (`*`) | ✅ 是的 | ❌ 没有 **使用 doc_events 时**： * 从您的自定义应用程序中挂钩其他应用程序的 DocType * 响应所有 DocType（通配符） * 注册多个处理程序 **在以下情况下使用控制器方法： * 使用您自己的 DocType * 您想要完整的生命周期控制 ** ** ## 参考文件文件|内容 ---|--- [doc-events.md]() |所有文档事件、签名、执行顺序 [scheduler-events.md]() |调度程序类型、cron 语法、超时 [bootinfo.md]() | extend_bootinfo，会话挂钩 [overrides.md]() |覆盖和扩展模式 [permissions.md]() |权限挂钩 [fixtures.md]() |夹具配置 [examples.md]() |完整的 hooks.py 示例 [anti-patterns.md]() |错误与更正 ** ** ## 配置挂钩 ### 覆盖 DocType 控制器 # 在 hooks.py 中 override_doctype_class = { “销售发票”：“myapp.overrides.CustomSalesInvoice” } # 在 myapp/overrides.py 中从 erpnext.accounts.doctype.sales_invoice.sales_invoice 导入 SalesInvoice 类 CustomSalesInvoice(SalesInvoice): def 验证（自我）： super().validate() # 关键：始终调用 super()！ self.custom_validation() **警告**：当多个应用程序覆盖相同的 DocType 时，最后安装的应用程序获胜。 ### 覆盖白名单方法 # 在 hooks.py 中 override_whitelisted_methods = { "frappe.client.get_count": "myapp.overrides.custom_get_count" } # 方法签名必须与原始方法签名相同！ def custom_get_count(doctype,filters=None,debug=False,cache=False): # 自定义实现返回frappe.db.count（文档类型，过滤器） ### 权限挂钩 # 在 hooks.py 中权限查询条件= { “销售发票”：“myapp.permissions.si_query_conditions” } 有权限={ “销售发票”：“myapp.permissions.si_has_permission” } # 在 myapp/permissions.py 中 def si_query_conditions（用户）： """返回用于列表过滤的 SQL WHERE 片段""" 如果不是用户：用户 = frappe.session.user 如果 frappe.get_roles(user) 中的“销售经理”： return "" # 无限制返回 f"`tabSales Invoice`.owner = {frappe.db.escape(user)}" def si_has_permission（文档，用户=无，permission_type=无）： """文档级权限检查""" 如果permission_type ==“写”并且doc.status ==“已关闭”：返回错误 return None # 回退到默认值 **注意**：“permission_query_conditions”仅适用于“get_list”，不适用于“get_all”！ ### 赛程 # 在 hooks.py 中赛程 = [ {“dt”：“自定义字段”，“过滤器”：[[“模块”，“=”，“我的应用程序”]]}， {“dt”：“属性设置器”，“过滤器”：[[“模块”，“=”，“我的应用程序”]]}， {“dt”：“角色”，“过滤器”：[[“名称”，“喜欢”，“MyApp%”]]} ] # 将灯具导出为 JSON 长凳 --site sitename 导出装置 ### 资产包括 # 在 hooks.py 中 # 桌面（后端）资产 app_include_js =“/assets/myapp/js/myapp.min.js” app_include_css =“/assets/myapp/css/myapp.min.css” # 网站/门户资产 web_include_js =“/assets/myapp/js/web.min.js” web_include_css =“/assets/myapp/css/web.min.css” # 表单脚本扩展 doctype_js = { “销售发票”：“public/js/sales_invoice.js” } ### 安装/迁移 Hooks # 在 hooks.py 中 after_install =“myapp.setup.after_install” after_migrate = "myapp.setup.after_migrate" # 在 myapp/setup.py 中 def after_install(): 创建默认角色（） def after_migrate(): 清除自定义缓存() ** ** ## 完整的决策树你想实现什么目标？ │ ├─► 对其他应用程序的记录事件做出反应？ │ └─► doc_events │ ├─► 运行 PERIODIC 任务？ │ └─► 调度程序_事件 │ ├─► < 5 分钟 → 每小时/每天/每周/每月 │ ├─► > 5 分钟 → 每小时_长/每日_长/等。 │ └─► 具体时间 → cron │ ├─► 在页面加载时向客户端发送数据？ │ └─► 扩展_bootinfo │ ├─► 修改现有DocType的CONTROLLER？ │ ├─► Frappe v16+ →extend_doctype_class（推荐） │ └─► Frappe v14/v15 → override_doctype_class │ ├─► 修改API ENDPOINT？ │ └─► override_whitelisted_methods │ ├─► 自定义权限？ │ ├─► 列表过滤→permission_query_conditions │ └─► 文档级 → has_permission │ ├─► 导出/导入配置？ │ └─► 灯具 │ ├─► 将 JS/CSS 添加到桌面或门户？ │ ├─► 桌子 → app_include_js/css │ ├─► 传送门 → web_include_js/css │ └─► 表单特定 → doctype_js │ └─► 安装/迁移时设置？ └─► after_install、after_migrate ** ** ## 版本差异特色 | v14 | v15 | v16 ---|---|---|--- 文档事件 | ✅ | ✅ | ✅ 调度程序事件 | ✅ | ✅ | ✅ 扩展启动信息 | ✅ | ✅ | ✅ override_doctype_class | 覆盖文档类型类✅ | ✅ | ✅ 扩展文档类型类 | ❌ | ❌ | ✅ 权限查询条件 | ✅ | ✅ | ✅ 有权限 | ✅ | ✅ | ✅ 固定装置| ✅ | ✅ | ✅ ** ** ## 反模式总结 ❌ 错 | ✅ 正确 ---|--- 处理程序中的 `frappe.db.commit()` Frappe 自动提交 on_update 中的 `doc.field = x` `frappe.db.set_value()` “日常”任务繁重 |使用“daily_long” 无需迁移即可更改调度程序 |始终“板凳迁移” bootinfo 中的敏感数据 |仅公共配置不使用 `super()` 进行覆盖 |总是先`super().method()` 带有权限查询的`get_all`使用“get_list” 不带过滤器的装置|按模块/应用程序过滤 **完整反模式** ：参见 [anti-patterns.md]()

Erpnext 语法挂钩

包含技能