关于 frappe-core-utils
供 Frappe 开发者查找 Python 与 JavaScript 常用工具函数的参考资料，按任务整理日期、数值、字符串和验证等 API，并指出版本差异与常见反模式。
主要功能
- 01按用途索引 Python 工具函数
- 02整理日期与时间处理 API
- 03提供数值、货币和字符串函数
- 04列出 JavaScript 工具函数
- 05对照 v14、v15、v16 函数差异
- 06说明标准库替代方案与反模式
适用场景
- 01查找日期或金额格式化函数
- 02处理输入转换与数据验证
- 03编写 Server Script 时选择可用函数
- 04检查代码是否误用标准库函数
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/frappe-core-utils确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
references/anti-patterns.mddate-time-functions.mdjavascript-utilities.mdnumber-money-functions.mdstring-validation-functions.md详细介绍
Frappe 实用函数
快速参考：Python
| 需求 | 函数 | 返回值 |
|---|---|---|
| 当前日期 | nowdate() / today() | datetime.date |
| 当前日期时间 | now_datetime() | datetime.datetime |
| 解析日期字符串 | getdate(str) | datetime.date |
| 解析日期时间字符串 | get_datetime(str) | datetime.datetime |
| 增加天数 | add_days(date, n) | datetime.date |
| 增加月数 | add_months(date, n) | datetime.date |
| 日期差 | date_diff(end, start) | int（天数） |
| 格式化为用户格式 | format_date(dt) | str（用户区域设置） |
| 相对时间 | pretty_date(dt) | str（“2 小时前”） |
| 安全浮点数转换 | flt(val, precision) | float |
| 安全整数转换 | cint(val) | int |
| 安全字符串转换 | cstr(val) | str |
| 安全布尔值转换 | sbool(val) | bool |
| 安全除法 | safe_div(a, b) | float [v15+] |
| 货币格式 | fmt_money(amt, currency) | str |
| 金额大写 | money_in_words(amt, cur) | str |
| 去除 HTML | strip_html(text) | str |
| 列表转为文本 | comma_and(items) | str（“a、b 和 c”） |
| 验证邮箱 | validate_email_address(e) | str 或 "" |
| 验证 URL | validate_url(url) | bool |
| 解析 JSON | parse_json(s) | Any |
| 文件路径 | get_files_path(is_private) | str |
| 站点路径 | get_site_path(*parts) | str |
| 唯一列表 | unique(seq) | list |
| 哈希 | generate_hash(s, length) | str |
所有导入：在控制器/白名单方法中使用
from frappe.utils import nowdate, flt, ...。 在 Server Scripts 中：直接使用frappe.utils.nowdate()—— 不允许使用导入语句。
决策树：“该使用哪个函数？”
Need a date/time value?
├─ Current date → nowdate() or today()
├─ Current datetime → now_datetime()
├─ Parse a string → getdate() or get_datetime()
├─ Add/subtract time → add_days(), add_months(), add_to_date()
├─ Difference → date_diff() (days), month_diff(), time_diff_in_seconds()
├─ Period boundary → get_first_day(), get_last_day(), get_quarter_start()
└─ Display to user → format_date(), format_datetime(), pretty_date()
Need a number?
├─ Convert safely → flt(), cint(), cstr(), sbool()
├─ Round → rounded() (banker's rounding)
├─ Safe divide → safe_div(a, b, default=0) [v15+]
├─ Format money → fmt_money(amount, currency)
└─ Money to words → money_in_words(amount, currency)
Need string processing?
├─ HTML → strip_html(), escape_html(), is_html()
├─ Join list → comma_and(), comma_or(), comma_sep()
├─ Markdown ↔ HTML → to_markdown(), md_to_html()
└─ Mask sensitive → mask_string(input, show_first=4) [v16+]
Need validation?
├─ Email → validate_email_address(email, throw=False)
├─ URL → validate_url(url, valid_schemes=["https"])
├─ Phone → validate_phone_number(phone, throw=False)
├─ JSON → validate_json_string(s)
└─ IBAN → validate_iban(iban) [v16+]
Need file/path?
├─ Public files → get_files_path()
├─ Private files → get_files_path(is_private=True)
├─ Site directory → get_site_path("private", "backups")
├─ Bench root → get_bench_path()
└─ File size → get_file_size(path, format=True)
重要反模式
frappe.utils 中存在对应函数时，绝不要使用 Python 标准库
| 绝不要（标准库） | 始终使用（frappe.utils） | 原因 |
|---|---|---|
datetime.datetime.now() | now_datetime() | 忽略系统时区 |
datetime.date.today() | nowdate() | 忽略系统时区 |
float(val) | flt(val, precision) | 遇到 None/空值时会崩溃 |
int(val) | cint(val) | 遇到 None/空值时会崩溃 |
round(val, 2) | rounded(val, 2) | 舍入结果不一致 |
val1 / val2 | safe_div(val1, val2) | ZeroDivisionError [v15+] |
json.loads(s) | parse_json(s) | 遇到 None/空值时会崩溃 |
json.dumps(obj) | frappe.as_json(obj) | 序列化结果不一致 |
"{:,.2f}".format(a) | fmt_money(a, currency) | 忽略区域设置/货币 |
os.path.join(...) | get_site_path(...) | 会破坏多租户 |
", ".join(items) | comma_and(items) | “and” 不会本地化 |
dt.strftime(fmt) | format_date(dt) | 忽略用户偏好 |
re.sub(r'<.*?>', '', h) | strip_html(h) | 无法处理边界情况 |
Server Script 沙箱
# ❌ NEVER in Server Scripts
from frappe.utils import nowdate, flt
import json
# ✅ ALWAYS in Server Scripts (no imports allowed)
today = frappe.utils.nowdate()
amount = frappe.utils.flt(doc.amount, 2)
data = frappe.parse_json(doc.json_field)
JavaScript 快速参考
| 需求 | 函数 |
|---|---|
| 转义 HTML | frappe.utils.escape_html(txt) |
| HTML 转文本 | frappe.utils.html2text(html) |
| 检查是否为 HTML | frappe.utils.is_html(txt) |
| 解析 JSON | frappe.utils.parse_json(str) |
| 验证 URL | frappe.utils.is_url(txt) |
| 标题式大小写 | frappe.utils.to_title_case(str) |
| 用“and”连接 | frappe.utils.comma_and(list) |
| 唯一数组 | frappe.utils.unique(list) |
| 复制到剪贴板 | frappe.utils.copy_to_clipboard(txt) |
| 滚动到元素 | frappe.utils.scroll_to(el) |
| 是否为移动设备 | frappe.utils.is_mobile() |
| 节流 | frappe.utils.throttle(fn, delay) |
| 防抖 | frappe.utils.debounce(fn, delay) |
| 格式化值 | frappe.format(value, df, options, doc) |
| 时长显示 | frappe.utils.get_formatted_duration(secs) |
版本差异
| 功能 | v14 | v15 | v16 |
|---|---|---|---|
safe_div() | -- | 已添加 | 是 |
duration_to_seconds() | -- | 已添加 | 是 |
guess_date_format() | -- | 已添加 | 是 |
validate_duration_format() | -- | 已添加 | 是 |
mask_string() | -- | -- | 已添加 |
validate_iban() | -- | -- | 已添加 |
validate_name() | -- | -- | 已添加 |
safe_json_loads() | -- | -- | 已添加 |
groupby_metric() | -- | -- | 已添加 |
| 核心函数 | 是 | 是 | 是 |
参考文件
- 日期/时间函数 — 完整的日期/时间 API 及签名
- 数字与金额函数 — flt、fmt_money、舍入
- 字符串与验证函数 — HTML、join、validate
- JavaScript 工具 — 客户端 frappe.utils.*
- 反模式 — 标准库与 frappe.utils 对比
评论
支持 Markdown