1. 概述
Smartbi使用客户端宏实现特定的报表展现效果,因为仅对页面展示时生效,所以称为客户端宏(如下图,页面渲染时在参数后面添加特定按钮)。客户端宏是在浏览器端运行,所以语法是JavaScript的语法,需要有前端开发的经验才可能灵活编写,调试也是使用浏览器前端调试即可。
在进行客户端宏的学习前,建议了解:
注意:客户端宏主要影响浏览器端的展现效果,除了图形(直接加在图形对象上的部分宏功能可以对导出生效),其他报表的客户端宏都不会对导出有效果。
2. 客户端宏原理
Smartbi的报表从打开到完整展现的过程,会经历一系列的步骤(事件),比如打开报表,刷新报表,参数改变等。在进行这些步骤的前后,通过加入扩展的入口,使得程序在执行这些步骤前后可以加载对应事件的自定义宏代码,以达到在对应事件中方便、准确地修改报表的目的。
如下图所示,报表打开后会触发宏代码,刷新数据后会触发宏代码,参数变更后同样会触发宏代码。
3. 客户端宏事件
ClientSide客户端模块
spreadsheetReport (电子表格对象)
spreadsheetReport:电子表格对象。
对应事件 | 对应事件说明 |
onRenderReport | · 事件原型:function main(spreadsheetReport) {} · 事件说明:在打开电子表格报表初始化完成后触发 · 参数说明 o spreadsheetReport:电子表格报表对象 |
onRender | · 事件原型:function main(spreadsheetReport) {} · 事件说明:在电子表格报表数据刷新后触发 · 参数说明 o spreadsheetReport:电子表格报表对象 |
onParamValueChanged | · 事件原型:function main(spreadsheetReport, param) {} · 事件说明:在电子表格报表参数改变后触发 · 参数说明 o spreadsheetReport:电子表格报表对象 o param当前改变的参数对象 · 参考示例:电子表格根据参数值不同显示不同的报表 |
onLinkClick | · 事件原型:function main(spreadsheetReport, ruleName, params) {} · 事件说明:在电子表格超链接上点击后触发,这个事件需要配合服务端宏才能生效,一般不会手动新建,而是通过跳转规则自动生成(可以基于生成的再修改)。 · 参数说明 o spreadsheetReport:电子表格报表对象 o ruleName:跳转规则名称 o params: 报表参数 |
onChartClick | · 事件原型:function main(spreadsheetReport, spreadsheetReportChart) {} · 事件说明:在电子表格图形上点击后触发,这个事件需要配合服务端宏才能生效,一般不会手动新建,而是通过跳转规则自动生成(可以基于生成的再修改). · 参数说明 o spreadsheetReport:电子表格报表对象 o spreadsheetReportChart:被点击图形名称(excel设计器上指定的),对象结构,spreadsheetReportChart.name代表图形名称 |
onWriteBackInsertedRow | · 事件原型:function main(spreadsheetReport, editingCellPosition) {} · 事件说明:在可回写的电子表格的工具类上点击“插入行”后触发 · 参数说明 o spreadsheetReport:电子表格报表对象 o editingCellPosition:当前编辑单元格,对象结构{row:, column:} · 参考示例:电子表格添加新行时自动为单元格赋值 |
onWriteBackCellValueChanged | · 事件原型:function main(spreadsheetReport, editingCellPosition, oldValue, newValue, newDisplayValue){} · 事件说明:在可回写的电子表格中,修改某个单元格值的时候触发 · 参数说明 o spreadsheetReport:电子表格报表对象 o editingCellPosition:当前编辑单元格,对象结构{row:, column:} o oldValue:修改前的值 o newValue:修改后的值 o newDisplayValue:修改后的显示值 · 参考示例:电子表格回写单元格一对多联动 |
onWriteBackSavedData | · 事件原型:function main(spreadsheetReport, succeeded) {} · 事件说明:在可回写的电子表格的工具类上点击“保存”,服务器返回后触发 · 参数说明 o spreadsheetReport:电子表格报表对象 o succeeded:bool,回写是否成功 · 参考示例:电子表格回写保存时记录日志 |
simpleReport(即席查询/灵活分析对象)
simpleReport:即席查询/灵活分析对象。
对应事件 | 对应事件说明 |
onRender | · 事件原型:function main(simpleReport, simpleReportContext){} · 事件说明:在打开报表,初始化完成后触发 · 参数说明 o simpleReport:即席查询/灵活分析对象 o simpleReportContext:即席查询/灵活分析上下文对象 |
onRenderTable | · 事件原型:function main(simpleReport, simpleReportContext){} · 事件说明:报表刷新数据后触发,每次刷新数据都触发一次 · 参数说明 o simpleReport:即席查询/灵活分析对象 o simpleReportContext:即席查询/灵活分析上下文对象 |
onParamValueChanged | · 事件原型:function main(simpleReport, simpleReportContext, param) {} · 事件说明:报表参数改变后触发 · 参数说明 o simpleReport:即席查询/灵活分析对象 o simpleReportContext:即席查询/灵活分析上下文对象 o param:发生变化的参数对象 |
INSIGHT(透视分析对象)
INSIGHT:透视分析对象。
对应事件 | 对应事件说明 |
onRender | · 事件原型:function main(insight){} · 事件说明:在打开透视分析初始化完成后触发 · 参数说明 o insight:透视分析对象 |
onRenderTable | · 事件原型:function main(insight){} · 事件说明:透视分析刷新数据后触发,每次刷新数据都触发一次 · 参数说明 o insight:透视分析对象 · 参考示例:透视分析打开默认收缩 |
onParamValueChanged | · 事件原型:function main(insight, param) {} · 事件说明:透视分析参数改变后触发 · 参数说明 o insight:透视分析对象 o param:发生变化的参数对象 |
meterReport(仪表分析对象)
meterReport:仪表分析对象。
对应事件 | 对应事件说明 |
onRender | · 事件原型:function main(meterReport){} · 事件说明:在打开仪表分析初始化完成后,刷新数据前触发 · 参数说明 o meterReport:仪表分析对象 |
onParamValueChanged | · 事件原型:function main(meterReport, param) {} · 事件说明:仪表分析参数改变后触发 · 参数说明 o meterReport:仪表分析对象 |
olapQuery(多维分析报表对象)
olapQuery:多维分析报表对象。
对应事件 | 对应事件说明 |
afterRefreshTable | · 事件原型:function main(olapQuery) {} · 事件说明:在多维分析报表数据刷新后触发 · 参数说明 o olapQuery:多维分析报表对象 |
olapTable(多维分析表格对象)
olapTable:多维分析报表表格对象。
对应事件 | 对应事件说明 |
onClick | · 事件原型:function main(cell) {} · 事件说明:在单击多维分析表格中的内容时触发 · 参数说明 o cell:当前点击的单元格对象 |
onInitPopupMenu | · 事件原型:function main(popupMenu, cell) {} · 事件说明:在单击多维分析表格进行该事件处理,显示命令菜单,只有单击菜单中相关命令才会执行宏 · 参数说明 o popupMenu:子菜单对象 o cell:当前点击的单元格对象 |
4. 客户端宏API和源码
宏的开发实际离不开API(报表宏接口文档),根据API可以用报表宏快速实现多种功能。而要更加灵活开发则需要了解每个宏对象对应的源码,宏对象对应JS源文件如下(文件位于Smartbi war包中):
报表类型 | 宏对象 | 源文件 |
电子表格 | spreadsheetReport | SpreadsheetReport.js |
即席查询 | simpleReport | CombinedQV.js(继承QueryView.js) |
simpleReportContext | CombinedQVNavigator.js(继承QueryNavigator.js) | |
灵活分析 | simpleReport | QueryView.js |
simpleReportContext | QueryNavigator.js | |
透视分析 | INSIGHT | Insight.js |
仪表分析 | meterReport | Dashboard.js |
多维分析 | olapQuery | OlapQueryViewDisplay.js 或 OlapQueryView.js |
图形 | chartView | EChartsView.js 以及父类 AbstractChartView.js |
5. 客户端宏示例
客户端宏示例详见:报表宏示例。
6. 视频教学
视频教学点击下载:客户端宏原理、客户端宏事件、客户端宏对象、客户端宏实战
视频配套资源下载:客户端宏示例