用途:定制 Frappe Desk 管理界面,覆盖表单脚本、列表视图脚本、对话框与客户端 JavaScript API,用于构建交互式 Desk 体验。
主要能力:在表单中添加自定义按钮与操作;动态过滤 Link 字段;按条件切换字段显隐;定制列表视图指示器与批量操作;构建交互式对话框与提示;保存前进行客户端校验;通过 hooks 向其他应用的 DocType 注入脚本。
使用方式:先选择脚本类型——应用级表单脚本位于 <app>/<module>/doctype/<doctype>/<doctype>.js(受版本控制),Client Script 存于数据库(站点级),Hook 注入脚本通过 hooks.py 的 doctype_js 扩展其他应用 DocType。表单脚本用 frappe.ui.form.on 绑定 setup、refresh、validate、字段变更、before_save、after_save 等事件;子表事件以字段名为键。对话框可用 frappe.prompt、frappe.ui.Dialog、frappe.confirm。服务端调用用 frappe.call 或 frappe.xcall。列表视图通过 frappe.listview_settings 配置 get_indicator、onload 批量操作等。实时事件用 frappe.realtime.on。路由用 frappe.set_route。添加 hook 脚本后需执行 bench build --app my_app。
适用场景:需要为 Frappe 应用或站点扩展 Desk 交互行为时。
限制与注意:始终通过 frm.doc 访问文档;校验用 validate 事件而非 before_save;frappe.call 为异步,需用回调或 async/await;程序化改值后调用 frm.refresh_field;注意 frm.is_new() 与 frm.doc.docstatus。脚本不加载时检查路径并执行 bench build;按钮不出现检查 refresh 条件;事件不触发检查名称大小写;hook 脚本被忽略检查 hooks.py 路径并重建资源;frappe.call 失败检查方法路径与服务端 @frappe.whitelist()。服务端控制器逻辑、RPC 端点、Frappe UI(Vue 3)前端分别转交对应开发技能。