frappe-syntax-reports

报表：查询、脚本与报表构建器

快速参考

报表类型一览

类型	是否需要代码	使用场景	权限
报表构建器	无	按筛选条件和分组对单一 DocType 进行简单列表查询	任何用户
查询报表	仅 SQL	直接执行 SQL 查询，采用旧版列格式	系统管理员
脚本报表（标准）	Python + JS	复杂逻辑、图表、摘要、树形结构	管理员 + 开发者模式
脚本报表（自定义）	UI 中的 Python	无需部署应用即可快速创建自定义报表	系统管理员

脚本报表 execute() 的返回值

def execute(filters=None):
    columns = [...]   # List of dicts
    data = [...]      # List of dicts or lists
    message = "..."   # Optional: HTML message above report
    chart = {...}     # Optional: chart configuration
    report_summary = [...]  # Optional: summary cards
    skip_total_row = False  # Optional: suppress auto-total
    return columns, data, message, chart, report_summary, skip_total_row

列定义（字典格式）

columns = [
    {
        "fieldname": "customer",
        "label": _("Customer"),
        "fieldtype": "Link",
        "options": "Customer",
        "width": 200
    },
    {
        "fieldname": "amount",
        "label": _("Amount"),
        "fieldtype": "Currency",
        "options": "currency",  # field in row holding currency code
        "width": 120
    }
]

查询报表列格式（旧版字符串）

SELECT
  name as "Sales Order:Link/Sales Order:200",
  customer as "Customer:Link/Customer:180",
  grand_total as "Total:Currency:120",
  transaction_date as "Date:Date:100"
FROM `tabSales Order`
WHERE docstatus = 1

格式："Label:Fieldtype/Options:Width" — 仅 Link、Dynamic Link 和 Currency 需要 Options。

筛选器定义（JS）

frappe.query_reports["My Report"] = {
    filters: [
        {
            fieldname: "company",
            label: __("Company"),
            fieldtype: "Link",
            options: "Company",
            default: frappe.defaults.get_user_default("company"),
            reqd: 1
        },
        {
            fieldname: "from_date",
            label: __("From Date"),
            fieldtype: "Date",
            default: frappe.datetime.add_months(frappe.datetime.get_today(), -1)
        },
        {
            fieldname: "status",
            label: __("Status"),
            fieldtype: "Select",
            options: "\nDraft\nSubmitted\nCancelled"
        }
    ]
};

决策树：选择哪种报表类型？

Need a report?
├─ Simple list/group of one DocType → Report Builder
│   (no code, UI-only, supports Group By with Count/Sum/Avg)
├─ Direct SQL query, no Python logic needed → Query Report
│   (SQL in Report doc, column format in aliases)
├─ Complex logic, calculations, charts → Script Report (Standard)
│   (Python .py + JS .js files, requires Developer Mode)
└─ Quick one-off with Python but no app deploy → Script Report (Custom)
    (Python in Report doc UI, System Manager can create)

Script Report returns what?
├─ Just data → return columns, data
├─ Data + chart → return columns, data, None, chart
├─ Data + summary → return columns, data, None, None, report_summary
├─ Data + message → return columns, data, message
└─ Everything → return columns, data, message, chart, report_summary, skip_total_row

支持的列字段类型

字段类型	是否需要 Options	说明
Data	否	纯文本
Link	DocType 名称	可点击并跳转到文档的链接
Dynamic Link	保存 DocType 的字段名	与包含 DocType 的列搭配使用
Currency	货币字段或代码	行中保存货币的字段名
Float	否	小数
Int	否	整数
Percent	否	显示百分比条
Date	否	日期显示
Datetime	否	日期和时间
Check	否	布尔复选框
Select	否	下拉选项值
Text	否	长文本
HTML	否	原始 HTML 渲染

支持的筛选器字段类型

字段类型	Options	行为
Link	DocType 名称	从 DocType 自动补全
Select	以换行符分隔的值	显示固定选项的下拉菜单
Date	—	日期选择器
DateRange	—	返回 [from_date, to_date] 列表
Check	—	布尔开关
Dynamic Link	Link 筛选器的字段名	取决于另一个筛选器的值
Data	—	自由文本输入
Int	—	数字输入
MultiSelectList	DocType 名称	多值选择

图表数据格式

chart = {
    "data": {
        "labels": ["Jan", "Feb", "Mar", "Apr"],
        "datasets": [
            {"name": _("Revenue"), "values": [100, 200, 150, 300]},
            {"name": _("Expense"), "values": [80, 150, 120, 250]}
        ]
    },
    "type": "bar",        # bar, line, pie, donut, percentage
    "fieldtype": "Currency",
    "options": "currency",
    "currency": "USD",
    "colors": ["#5e64ff", "#ffa00a"]  # Optional custom colors
}

报表摘要格式

report_summary = [
    {
        "value": total_revenue,
        "label": _("Total Revenue"),
        "datatype": "Currency",
        "currency": "USD",
        "indicator": "Green"   # Green, Blue, Orange, Red
    },
    {
        "value": total_count,
        "label": _("Total Orders"),
        "datatype": "Int",
        "indicator": "Blue"
    }
]

预生成报表

对于处理大型数据集的报表，请启用 Prepared Report，以异步运行：

1. 在 Report 文档中设置 prepared_report = 1
2. 用户点击“生成新报表”——通过 enqueue() 在后台运行
3. 结果存储在文件中；用户可在准备就绪后下载或查看
4. 对于查询超过 100k 行或耗时超过 30 秒的报表，务必使用

数字卡片

来源类型	必需字段	工作方式
文档类型	document_type、function、aggregate_function_based_on	对 DocType 执行 SQL 聚合
报表	report_name、report_field、function	从报表列中提取值
自定义方法	method	调用加入白名单的 Python 方法

自定义方法签名：

@frappe.whitelist()
def get_total_active_users(filters=None):
    return frappe.db.count("User", {"enabled": 1})

仪表板图表

来源	配置	数据格式
报表	设置 chart_type = "Report"，选择报表	使用报表的图表数据
自定义	设置 chart_type = "Custom"，定义 source	Hook 返回 {"labels": [...], "datasets": [...]}
分组依据	设置 chart_type = "Group By"，选择字段	自动按字段聚合

hooks.py 中的仪表板图表来源 Hook：

dashboard_chart_source = [
    "myapp.dashboard_chart_source.get_chart_data"
]

关键规则

• 始终将列定义为包含 fieldname、label、fieldtype 的字典列表。旧版字符串格式仅用于 Query Report SQL 别名。
• 绝不在 execute() 中为 columns 或 data 返回 None，始终返回空列表 []。
• 始终在列和 report_summary 中使用 _(...) 标记可翻译的标签。
• 绝不在 f-string 中将用户提供的筛选值直接用于 frappe.db.sql，始终将其作为参数传入：frappe.db.sql(query, filters, as_dict=True)。
• 始终在 Report 文档上设置 Reference DocType，它决定用户访问权限。
• 绝不在列定义中省略 width，缺少宽度的列渲染效果不佳。
• 始终确保图表数据中 datasets[].values 的长度与 labels 的长度一致，长度不匹配会导致图表渲染错误。

另请参阅

• references/query-report.md — 完整的 Query Report API
• references/script-report.md — Script Report JS API
• references/examples.md — 可运行的报表示例
• references/anti-patterns.md — 常见的报表错误
• references/dashboard.md — 数字卡片、仪表板图表