用途:在 Frappe v14-v16 项目中使用 frappe.utils.* 工具函数,处理日期时间、数字与货币、字符串、校验以及文件路径等常见操作,避免直接使用 Python 标准库带来的时区、空值、舍入或多租户问题。
主要能力:日期时间方面提供 nowdate()、today()、now_datetime()、getdate()、get_datetime()、add_days()、add_months()、date_diff()、format_date()、pretty_date() 等;数字与货币方面提供 flt()、cint()、cstr()、sbool()、safe_div()、fmt_money()、money_in_words()、rounded() 等;字符串方面提供 strip_html()、comma_and()、to_markdown()、mask_string() 等;校验方面提供 validate_email_address()、validate_url()、validate_phone_number()、validate_json_string()、validate_iban() 等;文件路径方面提供 get_files_path()、get_site_path()、get_bench_path()、get_file_size() 等。另含 JavaScript 端 frappe.utils 速查与 v14/v15/v16 版本差异表。
使用方式:在控制器或白名单方法中通过 from frappe.utils import nowdate, flt, ... 导入;在 Server Scripts 中不允许导入,需直接调用 frappe.utils.nowdate()、frappe.utils.flt() 等。
适用场景:需要按用户时区与本地化格式显示日期、货币与相对时间,安全转换数值或 JSON,处理 HTML 与列表拼接,做邮箱、URL、电话等输入校验,或跨多租户环境构造站点与文件路径时。
限制:仅在资料覆盖的 Frappe v14-v16 范围内适用;部分函数有版本要求,如 safe_div() 自 v15 起,mask_string()、validate_iban()、validate_name()、safe_json_loads()、groupby_metric() 自 v16 起;Server Scripts 中禁止 import。其余细节暂未提供。