smartbi之宏代码

1、报表宏简介

报表宏是 Smartbi 里面的一项特殊功能，顾名思义，就是基于报表的扩展，目的是为了让用户对报表进行自定义的改造，实现特定的功能。报表宏是 JavaScript 的代码集合体，我们也称之为“宏模块”。

 

1.1、报表宏的作用

Smartbi的报表拥有基本固定的报表展现样式及可视化的操作按钮，可以满足大多数的最终用户查看及分析数据的需求。而总会有少数用户，希望针对部分报表进行特殊化的调整，比如调整展现样式，增加功能按钮等，而这时就可以发挥报表宏的作用，对特定报表进行自定义处理。

 

1.2、报表宏的特点

报表宏具有以下特点：

• 报表宏以资源（报表资源、资源包）为应用载体，类似于 Excel 宏是以 Excel 文件为载体。（即报表宏存在且作用于具体某个报表或者资源包里）
• 报表宏使用 JavaScript 语言开发；
• 报表宏是按照事件进行触发（如报表加载事件、报表刷新事件、参数改变事件、点击事件等）；
• 在同一载体里面的报表宏可以相互引用。

 

1.3、报表宏的类型

• 客户端宏：宏的事件由浏览器端触发，模块里面的宏代码由浏览器端进行处理。客户端宏主要影响浏览器端的展现效果，除了图形（直接加在图形对象上的部分宏功能可以对导出生效），其他报表的客户端宏都不会对导出有效果。
• 服务端宏：宏的事件由服务端触发，模块里面的宏代码由服务端进行处理。服务端宏因为在服务器上运行，对浏览器端展现和导出报表都是生效的。

 

2、报表宏调试

• 客户端宏调试

基本调试步骤：

1）在报表宏的代码中加debugger；

2）然后在浏览器中按F12打开调试界面（开发者工具）；

3）运行报表，代码即会在debugger处暂停。

Smartbi服务器默认会对返回到客户端的JavaScript代码进行压缩，同时对HTTP Request、Response信息进行加密，为了便于调试，可以在debug模式下访问Smartbi，即在URL中添加debug=true参数，如：http://IP:PORT/smartbi/vision/index.jsp?debug=true。

 

• 服务端宏调试

"服务端模块"的报表宏可在宏控制台中进行调试，即在宏脚本中通过"logger"对象打印出服务端的日志信息。

 

可参考：https://wiki.smartbi.com.cn/pages/viewpage.action?smt_poid=43&pageId=69731794

 

3、报表宏创建方式

Smartbi中报表宏的创建方式分为：报表资源宏编辑、宏资源包、宏代码库。

• 报表资源宏编辑：在单独的报表资源上右键进入，只对所选报表生效，适用于对某张特定报表实现特定功能
• 宏资源包：对同一类报表生效，可以指定多张生效的报表，适用于多张报表使用宏实现同一个功能
• 宏代码库：主要用来定义一些公共的宏方法，将一些使用频率较高的方法定义为公共的方法，便于代码重用

“宏编辑”界面主要分为以下几个区域：

• 模块区：该区用于通过新建模块，在模块上定制宏。包含服务端模块、客户端模块和跳转规则向导。
• 帮助区：该区用于为当前模块根据不同的对象和类型显示系统中定义的对象和方法。
• 属性区：该区用于显示当前模块的相关属性。
• 编辑区：该区用于为当前模块进行宏的编辑，宏代码遵循JavaScript语法规范。
• 操作区：该区用于显示对当前模块宏代码的功能按钮。其中“禁用”表示该宏代码是否禁用，默认不勾选。

 

4、客户端宏

1. 客户端宏主要影响浏览器端的展现效果，除了图形（直接加在图形对象上的部分宏功能可以对导出生效），其他报表的客户端宏都不会对导出有效果。
2. 客户端宏是在浏览器端运行，所以语法是JavaScript的语法，需要有前端开发的经验才可能灵活编写，调试也是使用浏览器前端调试即可。

 

4.1、客户端宏原理

Smartbi的报表从打开到完整展现的过程，会经历一系列的步骤（事件），比如打开报表，刷新报表，参数改变等。在进行这些步骤的前后，通过加入扩展的入口，使得程序在执行这些步骤前后可以加载对应事件的自定义宏代码，以达到在对应事件中方便、准确地修改报表的目的。

如下图所示，报表打开后会触发宏代码，刷新数据后会触发宏代码，参数变更后同样会触发宏代码。

4.2、客户端宏接口说明

在Smartbi中，为不同类型的报表【电子表格】、【透视分析】、【即席查询】等提供了客户端处理的事件。

按照Smartbi报表类型，客户端报表宏分为电子表格，即席查询，透视分析等，其中，application、event 和 chartView 为多种不同报表类型客户端宏的共有对象，部分对象成员的出现是有前置条件的，具体介绍如下：

 

以下接口关系图展现的包含关系，表示被包含的对象为包含的对象的成员变量。例如chartView包含chart，表示chart为chartView的成员变量。

4.2.1、电子表格宏代码全局对象

电子表格报表宏中，各对象之间的包含关系如下图：

电子表格报表宏下部分对象成员详细介绍如下表：

 

4.2.2、即席查询宏代码全局对象

即席查询报表宏中，各对象之间的包含关系如下图：

即席查询报表宏下部分对象成员详细介绍如下表：

 

4.2.3、透视分析宏代码全局对象

透视分析报表宏中，各对象之间的包含关系如下图：

透视分析报表宏下部分对象成员详细介绍如下表：

 

5、服务端宏

Smartbi提供服务端宏功能，服务端宏表示宏的事件在服务端（应用服务器）进行处理，所以可以实现客户端宏不能实现的效果（如报表导出生效等）。在Smartbi中，只为【多维分析】【电子表格】【透视分析】提供了服务端处理的事件。

服务端宏底层原理和自定义计划任务脚本一样的，都是使用了 Rhino 工具包，语法遵循Javascript 语法规范，能够引用 Java 类并创建 Java 对象来使用。

注意：服务端宏因为在服务器上运行，对浏览器端展现和导出报表都是生效的。

 

5.1、 服务端宏对象

要根据“帮助”栏提供的API使用宏对象。以电子表格服务端宏为例：

• HO_Application下的为全局对象，可直接在服务端宏中使用
• logger对象用于打印日志，方便调试，其对应HO_Logger
• spreadsheetReport对象为电子表格服务端宏对象，其对应HO_SpreadsheetReport
• HO_SpreadsheetReport的sheets属性对HO_Spreadsheet数组
• HO_Spreadsheet的getCell()方法可以获取HO_SpreadsheetReportCell