用途:为 Frappe 应用构建客户端 UI,提供从组件选型到实现的逐步工作流,涉及对话框、消息提示、列表视图定制、自定义页面、日历、看板、实时更新与扫码等场景。
主要能力与用法:
- 对话框:用 frappe.ui.Dialog 创建简单、表格、多步对话框,primary_action 中通过 frappe.call 异步提交,须在回调内调用 d.hide();表格子字段需设 in_list_view: 1。
- 消息提示:frappe.msgprint 用于需确认的消息,frappe.show_alert 用于非阻塞提示,frappe.throw 用于校验错误(会中断执行),frappe.confirm 做二次确认,frappe.prompt 做单字段快速输入。
- 列表视图:在 {doctype}_list.js 中配置 frappe.listview_settings,如 add_fields、get_indicator(必须返回 [标签, 颜色, 过滤串] 三元数组)、formatters、button、onload、refresh、filters。
- 自定义页面:在 hooks.py 注册 page_js,用 frappe.ui.make_app_page 创建页面,支持主/次操作按钮、菜单项、工具栏字段与状态指示。
- 日历与看板:在 {doctype}_calendar.js 中配置 field_map(start/end 必须映射到日期字段);看板依赖 Select 字段,无需代码。
- 实时更新:服务端用 frappe.publish_realtime / frappe.publish_progress,客户端用 frappe.realtime.on/off;文档事件中发布须加 after_commit=True。
- 扫码:frappe.ui.Scanner 支持单次(multiple: false)与连续扫描。
限制:资料未提供安装命令、价格与平台支持信息;部分功能依赖 DocType 字段类型(如看板需 Select 字段,日历需日期字段);示例代码中的 API 名称与参数须保持原样。