像素级报表

使用华炎魔方 Stimulsoft 报表插件，可以连接任意数据库，在界面上编写查询语句，然后在报表设计器中引用该查询语句，就可以轻松设计出各种创意报表，本教程将描述如何在华炎魔方中把它配置出来。

​

安装

要使用Stimulsoft报表，需要先安装对应的软件包才能使用。

请在“设置”应用中进入“应用程序→软件包”界面并点击右上角的“手动安装软件包”按钮来安装软件包：

• 软件包名称：@steedos-labs/stimulsoft-reports
• 版本号：可以输入希望具体安装哪个版本的软件包，不填写该项时表示安装最新版本。

点击提交即可把软件包安装到当前魔方项目中，安装成功后可以在软件包列表看到刚安装的软件包，如果该软件包状态显示为“已启用”则表示安装成功。

​

数据源

要使用Stimulsoft报表，首先需要确认的就是其数据来源，华炎魔方目前支持MongoDB、MySQL、SQL Server、PostgreSQL、Oracle等数据库作为数据源，所以Stimulsoft报表是可以直接连接这些类型的数据库作为数据源的。

如果使用默认数据源，您只要在新建查询时选择使用默认数据源即可，但是如果要使用第三方数据源，就需要先配置相关外部数据源了。

可以在”设置“应用的”对象设置→外部数据源“界面配置对应的外部数据源”：

• 在配置连接属性时，”连接数据库的URL“与”其他连接选项“二者选填一个即可不用都填写。
• 当勾选“Debug”属性时，该数据源下所有请求的SQL语句都将在服务端控制台输出日志用于调式。
• 配置完成后，可以在该外部数据源记录详细界面右上角点击“测试连接”按钮来测试配置的参数是否正确，当提示连接成功即表示配置生效了。

​

查询

确定Stimulsoft报表要使用的数据源后，我们就可以在华炎魔方的查询设计器中编写对应的查询语句，根据实际需求从数据源中查询出仪表盘上需要展示的数据。

不同的数据源使用的查询语句语法各不相同，比如要查询MongoDB数据库中的数据需要使用MongoDB数据库查询语句，而要查询MySQL数据库中的数据的话就需要使用SQL语句直接查询。

在“设置”应用中，进入“统计分析→查询”界面可以维护华炎魔方所有的查询记录，在查询记录详细界面右上角可以点开查询设计器。

​

报表设计

查询语句调式确认好后，我们还需要设计在报表上以什么形式展示查询语句查出的数据结果，比如是以曲线图、柱状图还是以普通表格或其他类型的图表展示数据。

可以在华炎魔方的Stimulsoft报表设计器中，根据实际需求轻松设计出各种创意报表，整个过程您只需要点击鼠标以及配置相关参数即可。

在安装好Stimulsoft报表软件包后，我们点击左上角的九宫格图标，在弹出的应用程序启动器窗口中可以看到多了一个名为“报表管理”的应用，点击它进入应用中可以看到报表列表，在该界面可以维护华炎魔方所有的Stimulsoft报表记录。

在新建好报表后，在报表记录详细界面右上角可以点击“设计”按钮来打开报表设计器：

值得提示的是，我们是可以给一个报表配置多个查询的，这点与 仪表盘 不一样，在仪表盘中一个图表只能配置一个查询与之关联。

报表设计完成后点击左上角的保存按钮保存报表，最后可以点击报表详细界面右上角的预览按钮来查看设计后的效果。

​

应用

要在应用中展示设计好的报表，需要在界面上配置按钮，并编写按钮点击事件脚本，这样用户点击按钮时即可打开设计好的报表。

在点击事件中调用全局函数 Steedos.StimulsoftReports.openReport即可打开Stimulsoft报表，该函数有两个参数：

• reportId：要打开的报表_id。
• parameters：要传给报表的参数。

比如以下代码表示打开指定_id的报表，并传入参数company_id到报表中。

Steedos.StimulsoftReports.openReport('61b43fe55d7830ddcc130b60', { my_company: 'yHh7qefFi7cXHPeZX' })

除了可以在脚本函数中调用上面提到的openReport函数来打开报表，你也可以调用另一个直连打印机来打印报表的函数Steedos.StimulsoftReports.printInDesktop，该函数有三个参数：

• reportId：要打开的报表_id。
• parameters：要传给报表的参数。
• callBack：回调函数。

比如以下代码表示打开指定_id的报表，并传入参数ids到报表中，成功打印报表后会输出日志。

Steedos.StimulsoftReports.printInDesktop('6195ba2f82276c4bf419de9d', { ids: ['619383545b2e9a72ec0558c0', '619383555b2e9a72ec0558c1'] }, function (result) {
    toastr.success("打印已完成");
})

与openReport函数不同，printInDesktop函数只支持在桌面客户端使用，所以需要先安装华炎魔方桌面客户端，下载安装和配置教程请参考 华炎魔方桌面客户端。

相比openReport，使用printInDesktop函数在客户端上直接连接打印机有以下额外功能：

• 每次打印都会自动生成打印日志。
• 限制每个报表只能打印一次。

需要注意的是上面openReport函数中传入的参数my_company以及printInDesktop函数中传入的参数ids并不是报表中配置的参数，而是要注入到报表中配置的参数值公式表达式的公式变量，下面配置过程详解中将具体说明如何在按钮脚本中把参数传入到Stimulsoft报表中。

​

配置过程详解

​

示例效果

我们下面描述下如何使用Stimulsoft报表展示合同列表，本身Stimulsoft报表是可以设计出各种类型的图形、曲线、二维表等效果的，下面我们只列出在华炎魔方配置 Stimulsoft 报表的步骤，关于如何设计Stimulsoft报表请参考其官网： https://www.stimulsoft.com/en/products/reports-js。

​

配置查询

要实现上述报表效果，我们首先要为报表配置查询语句以提供报表需要的数据源。

我们先进入“设置”应用中，然后在“统计分析→查询”界面新建一个查询：

• 数据源：这里选择默认数据源，如果需要连接其他外部数据源时可以选择其他数据源。
• 查询脚本：这里可以输入示例需求的查询脚本，不过具体的脚本是需要编码调式才能确定的，我们这里保持默认值先不改，后续在设计器中单独编码调式。

查询新建好后，我们可以在新建好的查询记录的详细界面右上角看到“打开设计器”按钮，点击它即可打开查询设计器。

在这个设计器中左侧列出的是所有可供查询的数据库表，右侧上部是查询语句编辑器，点击该编辑器右下角”Execute“按钮可在右侧下部看到编写好的查询语句的执行结果，点击其旁边的”Save“按钮即可保存编写好的查询语句。

经过编码调式，我们最终确认下来示例需求”浇捣统计-按日统计“对应的查询语句如下所示：

{
    "collection": "contracts",
    "query": {
        "company_id": "{{ company_id }}"
    },
    "projection": {
        "_id": 0,
        "name": 1,
        "amount": 1
    }
}

以上查询语句根据传入的”company_id“参数值来查询对象contracts中的数据，并输出合同的名称和金额，有关 MongoDB 的语法请参考其官网文档：https://docs.mongodb.com/v4.4/reference/operator/query/。

在上述查询语句中我们用到的参数是通过点击设计器右侧的查询编辑器左下角的{{}}按钮来设置的，接下来我们把这两个参数配置出来。

首先把鼠标光标放入查询编辑器query.company_id这个参数在冒号右侧的值内，然后点击{{}}按钮在弹出下图所示的参数设置界面中配置”company_id“参数：

• Keyword：参数的key键名，可以是中文也可以是英文，不过推荐用英文。
• Title：参数的标题，可以与Keyword不一样，只是用于界面上标识该参数，无实际意义。
• type：参数类型，这个参数的类型，我们这里只需要调用该查询时传入表示当前登录用户“所属分部”的_id值字符串，所以使用Text类型即可。

上面配置的参数填写值后可以看到下面查询结果会相应变更，我们可以输入不同的_id值然后点击右侧“Execute”按钮来查看不同参数下的数据输出。

如果需要参数默认值，可以点击设计器上的“Save”按钮来保存设置好的参数值，保存后的参数值将成为该查询的默认参数值。

​

报表设计

按上面描述配置完查询后，执行”Execute“可以在右侧下方看到输出结果默认以Table的方式展示出来了，接下来我们看看怎么在Stimulsoft报表中展示这个表格数据。

我们首先进入“报表管理”应用，然后在报表列表新建一个报表：

• Api名称：该报表的唯一识别名称。
• 名称：该报表的显示名称。
• 查询：报表关联的查询，可以选择多个，这里我们选择上一步新建好的查询。
• 参数：如果之前查询配置了参数，这里就可以对应的输入参数名和参数值来配置相关参数，其中参数名我们配置为company_id，而参数值是一个字段公式表达式，上面配置的查询要求这里输入当前登录用户所属分部_id值，我们这里输入表达式my_company。

我们这里把参数值配置为公式表达式my_company，表示后续在脚本中调用openReport函数打开报表或调用printInDesktop函数打印报表时将传入一个名为my_company的参数，脚本中传入的参数会作为公式表达式执行时注入的参数。

有关字段公式语法请查阅文档： 通过公式计算字段值，保存后我们就可以点击报表记录详细界面右上角的“设计”按钮来打开报表设计器设计报表了，我们在这里就不详细介绍如何使用报表设计器设计报表了，请到Stimulsoft官网 https://www.stimulsoft.com/en/products/reports-js 查看相关教程，也可以查阅其在线文档 https://www.stimulsoft.com/en/documentation/online/user-manual/index.html?introduction.htm。

设计完成后点击左上角的保存按钮保存报表，最后我们可以点击报表详细界面的“预览”按钮来查看设计好的报表效果。

需要注意的是，点击报表详细界面的“预览”按钮打开的报表是未传入参数的，此时参数值使用的是之前查询设计器中配置的参数值，亦即报表的默认参数值。

我们也可以把报表的参数值设置为公式表达式$user.company_id._id，而不是上面说的my_company，该公式表达式表示始终输出当前登录用户的company_id._id值，这样的话，后续按钮脚本中调用openReport或printInDesktop函数时就不用传入任何参数了。

​

应用

接下来我们介绍下怎么在华炎魔方界面上配置一个按钮，并编写该按钮点击事件脚本，这样用户就可以点击该按钮来打开我们之前设计好的报表了。

可以在”设置“应用进入”对象设置=>对象“，然后进入指定对象详细页，点击“操作按钮”子表右上角的“新建”按钮。这里我们进入“合同”对象详细页。

• 显示名称： 操作按钮的显示名称。这里我们输入“打开报表”。
• API名称：操作按钮的api名称。这里我们输入“view_report”。
• 启用： 是否启用操作按钮。这里我们勾选该复选框。
• 显示位置：操作按钮的显示位置。这里我们选择“显示在列表右上角”。
• 执行的脚本：点击操作按钮时执行脚本。

这里我们输入以下脚本作为按钮点击事件脚本：

Steedos.StimulsoftReports.openReport('61b43fe55d7830ddcc130b60', { my_compnay: 'yHh7qefFi7cXHPeZX' })。

配置完成后，我们可以在“合同”对象列表页右上角看到配置好的“打开报表”按钮了，点击即可打开上面配置好的报表。