脚本报表 – ERPNext中国企业实施指南

任何无法通过报表构建器或查询报表实现的功能，都可以通过脚本报表来实现。顾名思义，这些报表是用 Python 脚本构建的。由于这些报表通过 Python 脚本为您提供了不受限制的访问权限，因此只能由管理员创建。这些报表是在开发过程中编写的，并且是您应用的一部分。

要创建脚本报表，您必须启用开发者模式。

要创建脚本报表，请在快捷搜索栏中输入”new report”并按回车。

将报表类型设置为”脚本报表”
将”是否标准”设置为”是”
选择您要添加此报表的模块
在模块文件夹中（例如，如果是 ERPNext 中的 Accounts，文件夹
将是 erpnext/accounts/report/[report-name]），您会看到模板
或报表文件将被创建。
在生成的 {report-name}.py 文件中编写您的 Python 脚本。
您可以通过将筛选器添加到 {report-name}.js 来为报表添加筛选器。

脚本报表

标准报表和自定义报表

在版本 12 中添加

从版本 12 开始，您可以在 Frappe 框架中创建自定义查询报表和脚本报表。在自定义报表中，脚本可以直接添加到报表本身中，您可以使用 Frappe 框架的脚本 API 函数。

列和筛选器

在版本 13 中添加

您可以在报表文档中配置列和筛选器。在这里，您可以为列和筛选器设置标签、宽度、格式（字段类型）。

筛选器可以在查询中用作格式化变量。例如，类型为 customer 的筛选器可以在查询中用作 %(customer)s。

编写脚本

自定义报表

在自定义报表中，您可以使用脚本 API 并直接在代码部分编写脚本。

return frappe.db.get_all('User', ['first_name', 'last_name'], filters = filters)

标准报表

生成的 .py 文件附带了一个报表的样板代码。其中有一个名为 execute 的方法，它接收 filters 并返回 columns 和 data。您可以使用任何 Python 模块和 SQL 查询的组合来生成报表。execute 函数如下所示

from __future__ import unicode_literals
# import frappe

def execute(filters=None):
 columns, data = [], []
 return columns, data

execute 函数应返回默认在报表中显示的 columns 和 data。开发者可以选择性地返回一些参数，如 message、chart、report_summary、skip_total_rows。

以下是 execute 函数可以返回的参数

列

这是一个字典列表。它按顺序保存了要在数据表中显示的所有列。

注意：只有在报表中未指定列时，您才需要返回列

示例：

columns = [
 {
 'fieldname': 'account',
 'label': _('Account'),
 'fieldtype': 'Link',
 'options': 'Account'
 },
 {
 'fieldname': 'currency',
 'label': _('Currency'),
 'fieldtype': 'Link',
 'options': 'Currency'
 },
 {
 'fieldname': 'balance',
 'label': _('Balance'),
 'fieldtype': 'Currency',
 'options': 'currency'
 }
 ]

结果

这可以是一个列表的列表或字典的列表。它保存了要在报表中显示的数据

示例：

data = [
 {
 'account': 'Application of Funds (Assets)',
 'currency': 'INR',
 'balance': '15182212.738'
 },
 {
 'account': 'Current Assets - GTPL',
 'currency': 'INR',
 'balance': '17117932.738'
 },
 ...
 ]

图表

包含报表中默认显示的图表的配置。

报表摘要

这是一个字典列表，用于存储报表中的重要数值，并在界面顶部区域单独显示。

示例：

[{
 "value": profit,
 "indicator": "Green" if profit > 0 else "Red",
 "label": _("Total Profit This Year"),
 "datatype": "Currency",
 "currency": "INR"
}]

注意：这些参数需要按照以下特定顺序返回

以下是来自 ERPNext 的一个脚本报表：资产负债表

添加筛选器

要在报表中添加筛选器，请在
{report-name}.js 文件中定义字段及其字段类型。筛选器的值将在 execute
方法中以字典形式提供。

frappe.query_reports['Balance Sheet'] = {
 filters: [
 {
 fieldname: 'company',
 label: __('Company'),
 fieldtype: 'Link',
 options: 'Company',
 default: frappe.defaults.get_user_default('company')
 },
 {
 fieldname: 'periodicity',
 label: __('Periodicity'),
 fieldtype: 'Select',
 options: [
 'Monthly',
 'Quarterly',
 'Half-Yearly',
 'Yearly'
 ],
 default: 'Yearly',
 depends_on: 'eval:doc.company=="Gadget Technologies Pvt. Ltd."'
 }
 ]
}

类似于控制字段显示的 depends_on 属性，在
版本 13 中我们为脚本报表筛选器引入了 depends_on。它可以
用于根据 depends_on 中条件的值来确定筛选器是否可见。

资产负债表

专业提示：要直接导航到上述任意类型的报表，请在快捷搜索栏中输入其
名称并按回车。

快照报表

一种高级报表生成引擎。它需要手动重写报表以使用 OLAP 数据库。

在系统设置 -> 高级中启用”快照报表”。这会设置一个后台任务，将数据从 MariaDB 同步到 DuckDB
在报表主数据中勾选”快照报表”复选框
在报表模块中使用 execute_snapshot_report 方法重写报表。

def execute_snapshot_report(filters: dict | None = None):
    """Return columns and data for the report.

    This is the main entry point for snapshot report. When 'Synced
    Report' is enabled in report, framework will call this method 
    every time the report is refreshed or a filter is updated. It 
    accepts the same filters as normal execute. But a utility method - 
    get_latest_sync, is also imported.
    """

    from frappe.database.duckdb.database import get_latest_sync
    columns = get_columns()
    data = get_data()

    return columns, data