★ FEATURED ARTICLE 简介面向使用 Smartbi 制作电子表格报表的报表开发与数据分析人员这份《Smartbi报表设置文档》围绕报表从建样式到发布的完整设置流程展开适合需要快速上手或规范报表排版、参数逻辑的初中级使用者。资源包仅含1个docx文档大小约1.05MB内容按引用模板、页面设置、隔行不同颜色、列宽自适应、参数设置、参数排版、预览发布等模块组织并给出宏脚本示例便于对照实现列宽自适应、起止日期先后与90天跨度校验等常见需求。文档还说明冻结行范围、筛选项居左与每行参数数量控制等排版细节可作为报表模板搭建和细节调优时的查阅材料。目前已有1305人学习下载适合希望减少重复调试、补齐 Smartbi 报表设置操作细节的读者参考。1. 照着 Smartbi 报表设置文档一步步点模板开了、颜色刷了预览时列宽还是挤成一团照着《Smartbi 报表设置文档》一步步点模板打开了、颜色也刷上了预览的时候却一片空白宏里那段列宽自适应的代码像是没长眼睛——这种现场我遇到过不止一次。问题基本不在步骤本身而在装之前没人核对过 Excel 是 32 位还是 64 位、插件包跟服务器是不是同一套、宏安全级别有没有把脚本拦在门外。电子表格报表这套东西在企业里太常见了财务日报、运营周报、生产看板一大半固定格式报表都靠它出。装不顺的代价很直接样式在本地调得漂漂亮亮发布上去排版错位参数校验形同虚设用户能把结束日期选到开始日期前一年。下面按我实际装过的一套流程走先对齐环境再装插件、引模板然后一层层把样式、宏、参数配上去最后给出验证和救急的办法。第一次上手这套插件的人能照着走通被叫去帮别人装的人也能看到几个容易忽略的取舍。2. Excel 插件安装与登录把客户端接到报表服务器上这一章的目标很单一让 Excel 的 Smartbi 页签正常出现、能登录、能拉到模板列表。三件事任何一件没成后面所有样式和宏都是白搭。我一般把这一章拆成三轮做——环境核对、安装登录、引模板每一轮都有可以逐条打勾的检查点不靠感觉。2.1 装之前先对齐的四项环境插件装不上或者装上不生效九成是环境项没对齐。最常见的四种翻车Excel 位数跟安装包位数不一致Smartbi 页签直接不出现或者点了没反应机器上 .NET Framework 版本太低安装程序跑到最后一步回滚Excel 宏安全级别是默认的「禁用所有宏」宏管理里写得再对也不会执行账号对模板目录没有读权限登录是成功的但模板列表一片空白。先把这张表在纸上过一遍比装完再回头查要省事得多。环境项建议取值不满足会怎样Excel 位数与插件安装包一致同为 32 位或同为 64 位页签不出现或点按钮无响应.NET Framework4.x加载项依赖的运行库安装到最后一步回滚报运行库缺失宏安全级别启用所有宏或把模板目录加进受信任位置宏不执行参数校验完全失效服务器连通性能访问报表服务器地址与端口登录长时间转圈模板列表空白账号权限模板目录可读、宏管理可写打开模板提示无权限保存的宏丢失位数这件事不要靠猜。即点即用方式安装的 Office注册表里记着位宽传统 MSI 安装的机器读不到就靠 EXCEL.EXE 落在哪个 Program Files 目录来判断这个办法最稳。# 方法一即点即用ClickToRun安装方式会记录位宽和版本 Get-ItemProperty HKLM:\SOFTWARE\Microsoft\Office\ClickToRun\Configuration -ErrorAction SilentlyContinue | Select-Object Platform, VersionToReport # 方法二直接找 EXCEL.EXE 落盘路径 # 落在 Program Files 下是 64 位落在 Program Files (x86) 下是 32 位 Get-ChildItem C:\Program Files\Microsoft Office,C:\Program Files (x86)\Microsoft Office -Filter EXCEL.EXE -Recurse -ErrorAction SilentlyContinue | Select-Object -First 3 FullName第一条命令读的是即点即用安装方式写进注册表的Platform字段值一般是 x86 或 x64MSI 安装的机器上这个键不存在命令会静默返回空所以要有第二条兜底。第二条命令是按磁盘路径反推Program Files与Program Files (x86)的区分就是 32/64 位的分界线输出里FullName前面那段路径就是答案。-Recurse会遍历整个 Office 目录慢一点但不会漏-ErrorAction SilentlyContinue是为了在某个目录不存在时不刷一屏红字。运行库版本顺带一起看避免装到一半才发现缺东西# 查 .NET Framework 4.x 是否已安装Release 有值基本说明 4.x 在位 Get-ChildItem HKLM:\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full -ErrorAction SilentlyContinue | Get-ItemProperty -Name Release, Version | Select-Object Version, ReleaseRelease是个数值键对照版本表能看出具体是小版本几这里不展开列数字判断标准简单输出不是空、Version是 4.x 开头就说明插件需要的运行库在位。输出为空的话别硬装先把运行库补齐否则安装程序会在最后一步回滚前面点的一堆下一步全白费。还有一项容易被跳过装之前把 Excel 进程彻底清掉。任务管理器里只要还挂着EXCEL.EXE安装程序替换加载项文件时就会提示占用即便点了忽略装完打开 Excel 也可能还是旧版本。我一般直接结束所有 Excel 进程再以管理员身份运行安装包。2.2 插件安装与登录服务器安装本身没什么技术含量顺序错了才麻烦。步骤按下面这个顺序走中间不要跳步结束所有 Excel 进程任务管理器确认EXCEL.EXE列表为空。右键安装包以管理员身份运行。位数选择与上一步查到的 Excel 位数一致不要选「自动检测」图省事。装完首次启动 Excel弹出加载项安全提示时选择启用。打开 Excel确认顶部出现 Smartbi 页签按钮不是灰的。点登录填服务器地址、用户名、密码。服务器地址这一步有讲究。填的是应用访问地址一般是http://主机:端口/应用名这种形态不要直接把浏览器里打开某张报表的完整长链接粘进去。长链接里带着报表 ID 和会话参数插件解析不了表现就是点登录后转很久然后报连接失败但用浏览器打开同一个地址又是正常的很容易误判成网络问题。判断登录成功的标志不是弹窗提示而是模板列表能正常拉出来。登录成功后点「模板」列表里能看到目录树和模板条目说明账号权限、服务器连通、插件版本三样都过了。列表空白但登录提示成功基本就是账号对模板目录没有读权限找管理员开权限比在本地反复重装有效。2.3 引用模板别从空报表开始设计登录通了之后第一件事是引用模板不是新建空报表。这一步在《Smartbi 报表设置文档》里写得很靠前但很多人会跳过觉得空报表更干净。吃过一次亏就懂了模板上已经绑好了数据集、参数定义和样式约定从空报表开始参数要自己一个个重新绑绑漏一个后面getParameterValue取到的就是 undefined校验宏静默失效排查起来能耗掉半天。具体操作路径是固定的在 Excel 的 Smartbi 页签下点「模板」。在模板目录里找到目标模板双击打开。打开后立刻另存为一份新的报表文件改个能区分的名字。在新的这份上设计报表样式原始模板保持不动。改完保存到服务器对应目录。第三步的另存为不是洁癖。直接改原模板一旦样式调坏了回滚要靠服务器端的版本记录而很多环境根本没开版本管理。另存一份最差也就是删掉重来后悔药提前备好。打开模板后看到的界面跟普通 Excel 差别不大区别在于多了一层 Smartbi 的数据绑定关系单元格里显示的是数据集字段占位或者上一次刷新的缓存值。这时候直接改格式是安全的删行删列要小心——删掉的可能是绑定了字段的行刷新后数据对不上。我一般的做法是先在空白区域试排版确认行列结构没问题再往模板正式区域上套。3. 样式层配置页面设置、隔行变色与列宽自适应宏样式这一层是给人看的但坑往往是给机器挖的。页面设置影响打印和导出隔行变色影响可读性列宽自适应影响观感三者有一个共同点本地调好不等于发布后也对。这一章按「先定页面骨架、再上颜色、最后交给宏」的顺序推进每一步都给出可对照的配置值。3.1 页面设置第一行空白行和冻结 1-5 行的账模板的第一行是空白行这个设计不是随手留的。它一般用来放报表标题、统计口径说明或者生成时间也可能是给参数区预留的空间。副作用是肉眼看到的第 1 行是空的真正的表头从第 2 行开始等到要冻结窗格的时候行号账就对不上了。冻结的目标是让表头在滚动时始终可见。既然表头占的是第 2 到第 5 行冻结就要覆盖前 5 行。操作上不要一行行数直接选中第 6 行的行号再执行冻结冻结的就是它上面的 5 行。这一点跟 Excel 的冻结窗格逻辑一致冻结的是选中行之上、选中列之左的区域。页面设置的其他项按下面这张表配打印和导出的观感基本就稳了设置项建议值说明纸张A4大多数内部报表的输出尺寸方向横向列数多时纵向必然被压缩到看不清缩放调整为 1 页宽列多时自动压缩避免出现半列跨页冻结行数5对应第一行空白行 四行表头打印标题行第 1-5 行多页输出时每页都带表头缩放这一项尤其值得强调。列数一多默认设置下最右边那列会被切到第二页打印出来是一张缺角的报表而且这种问题在预览界面不一定看得明显。设成「调整为 1 页宽」之后列多的时候会自动压缩比例虽然字会变小但至少是完整的。提示第一行留空这个约定要写进模板说明里。换个人接手看到第一行是空的很可能顺手删掉或者往上顶一行冻结行数就全错了而且这种错误在滚动之前完全看不出来。3.2 隔行不同颜色条件格式的公式要跟着起始行偏移隔行变色看着简单做错的方式却不少。最省事的做法是用条件格式加公式而不是手动一行行填色——手动填色在插入或删除行之后会整体错位而且数据量一大改一次颜色要重来一遍。规则建在数据区的第一行上公式写法是MOD(ROW(),2)0。这个公式的含义是当前行号除以 2 余数为 0 时命中规则。听起来没问题但真正落到报表上经常出现「从表头就开始染色」或者「相邻两行同色」的现象原因是数据区不是从第 1 行开始的。假设数据区从第 6 行开始公式就要改成带偏移的写法MOD(ROW()-6,2)0ROW()返回当前单元格的行号减去起始行号 6 之后数据区第一行变成 0第二行变成 1奇偶就对齐了。如果起始行是第 7 行就把 6 换成 7这个数字必须跟着数据区首行改不能照抄。应用范围同样要注意不要图快直接选整列。整列刷条件格式Excel 会把一百万行都纳入计算文件体积和打开速度都会受影响导出时也会变慢。正确的范围是数据区实际的行列区间比如$A$6:$H$200行数留出余量即可。颜色选择上隔行色的对比度要低。深色交替会让整张表看起来像斑马线打印成黑白后灰度差反而干扰阅读。浅灰、浅蓝这类低饱和度的填充色是常见做法正文单元格保持白底只给数据行交替上色。3.3 列宽自适应宏宏管理里那段脚本的参数含义列宽靠手动拖一百列的表能拖到怀疑人生。Smartbi 提供的方式是在宏管理里写一段脚本让报表刷新时自动把列宽调到合适值。这段脚本是通用的换个报表基本不用改function main(spreadsheetReport) { var sheet spreadsheetReport.workbook.worksheets.get(0); if (sheet || sheet null) { return; } var counts sheet.cells.maxDisplayRange.columnCount; //获取电子表格列数 sheet.autoFitColumns(0, counts); //从 0 开始到 counts 列结束。 //sheet.autoFitColumn(3); //只对某列进行自适应第一列为 0 }逐行拆开看。main是入口函数名不能改改成别的名字框架就找不到调用点宏等于没写。spreadsheetReport.workbook.worksheets.get(0)取的是工作簿里的第一张表参数 0 是索引从 0 开始计数多页签的报表要按实际顺序取对应索引。紧接着那个判空是为了防止取到空表时后面报错虽然写法上跟空字符串比较看起来有点怪但保留着没坏处。sheet.cells.maxDisplayRange.columnCount拿的是当前显示区域的最大列数注意是显示区域不是全部列隐藏列不计入。如果报表有动态列这个值在每次刷新时可能不同所以不能写死。sheet.autoFitColumns(0, counts)是区间自适应第一个参数是起始列索引0 表示第一列第二个参数是结束列索引传counts表示一路处理到最后一列。最后那行被注释掉的sheet.autoFitColumn(3)是单列自适应的写法参数 3 表示第四列索引从 0 起。调试阶段特别有用整表自适应之后发现某一列宽得离谱可以先把全局那行注掉只对可疑列单独处理快速定位是哪一列的内容把宽度撑开了。宏新建的位置在 Excel 的 Smartbi 页签下点「宏管理」新建宏把上面这段贴进去命名保存。保存后刷新报表看效果没生效先别怀疑代码去看宏的触发对象选没选对——选成了别的事件代码再对也不会跑。注意这段宏和后面第 4 章的参数校验宏都叫main。如果两张宏分开建逻辑上不会互相覆盖但都挂在同一个报表上时执行顺序不受控。稳妥做法是把两段逻辑合并进同一个宏里用不同的内部函数拆开main里依次调用避免出现「列宽生效了、校验失效了」这种灵异现象。4. 参数层配置日期区间校验宏与参数排版样式层解决的是好看参数层解决的是不出错。报表参数一旦放开用户能选出来的组合远超设计时的假设结束日期早于开始日期是最常见的一种。这一章把校验宏拆成两件事讲先把参数名对齐再讲重写刷新方法的写法最后落到参数区的排版规则。4.1 参数名必须先对齐再谈校验校验宏里取值靠的是参数名名字差一个空格都会导致取到 undefined。看这段代码里的写法getParameterValue(结束日期 2)注意参数名里那个空格和末尾的数字 2这是报表里参数的原始名称不是随手编的。所以配宏之前先做一件事打开报表的参数面板把开始日期、结束日期两个参数的名称原样抄下来包括空格、括号、编号。抄完之后跟代码里的字符串逐字比对。中文参数名里还容易混进全角空格肉眼看不出来取值为空的时候优先怀疑这个。另外getParameterValue返回的可能是字符串也可能因为参数类型是下拉框、区间而返回数组。稳妥写法是套一层字符串转换避免拿到 undefined 之后replace直接抛错。原始代码没做这层保护参数没选值时会有报错风险可以按需补。4.2 重写 doRefresh为什么先存一个原函数校验的关键在于「拦在刷新之前」。参数改完之后用户点刷新报表去拉数据如果参数非法应该在这一步就弹提示并中断而不是等数据出来之后再提示。实现方式就是重写doRefreshfunction main(spreadsheetReport) { if (!spreadsheetReport._jhy_doRefresh) { spreadsheetReport._jhy_doRefresh spreadsheetReport.doRefresh; } spreadsheetReport.doRefresh function(fromButton, delayMask) { //根据参数名称获取参数值 //结束日期不早于开始日期 var endtime new Date(spreadsheetReport.getParameterValue(结束日期 2).replace(/\-/g, /)); var starttime new Date(spreadsheetReport.getParameterValue(开始日期 2).replace(/\-/g, /)); if (endtime starttime) { setTimeout(function() { alert(结束时间不能早于起始时间); }, 100); return; } //结束日期不大于开始日期 90 天 if (endtime.getTime() - starttime.getTime() 1000 * 3600 * 24 * 90) { setTimeout(function() { alert(两个参数的差不能超过 90 天); }, 100); return; } this._jhy_doRefresh(fromButton, delayMask); }; }开头那三行是整段代码的核心。_jhy_doRefresh是个自定义属性用来暂存原始的doRefresh函数引用。为什么要存因为下面把spreadsheetReport.doRefresh整个替换掉了替换之后原函数就丢了最后一行调用this._jhy_doRefresh(...)时如果没有前面这层保存就会变成自己调自己无限递归页面直接卡死。前面加的if (!spreadsheetReport._jhy_doRefresh)判断是为了防止宏被重复执行时把已保存的原函数覆盖成包装后的版本那样同样会递归。new Date(...replace(/\-/g, /))这层替换不是多余的。日期字符串形如2024-01-01在部分 JS 引擎里new Date解析这种带连字符的格式会返回 Invalid Date换成2024/01/01就稳定了。正则/\-/g里的g表示全局替换把所有的连字符都换掉只换第一个的话后面的连字符还在照样解析失败。第一条判断endtime starttime直接比较两个 Date 对象JS 会隐式转成时间戳比较写起来最简洁。第二条判断用的是毫秒差1000 * 3600 * 24 * 90即 1000 毫秒 × 3600 秒 × 24 小时 × 90 天。这个公式在跨夏令时的地区会有一小时误差国内环境不用考虑但如果是跨国部署建议改成按日期归一到零点再算天数差。setTimeout(..., 100)包一层的原因值得说清楚。刷新动作触发时通常有一层遮罩或者加载提示alert如果在遮罩还没铺开时同步弹出有的环境下会被遮罩盖住用户看到的是页面卡住而不是弹窗。延后 100 毫秒等遮罩稳定了再弹提示才看得见。return的作用是中断后续流程不再调用原刷新函数等于这次刷新被拦下来了。最后this._jhy_doRefresh(fromButton, delayMask)把原始参数原样透传保证参数合法时刷新行为和没装宏之前完全一致。4.3 参数排版一行不超过 6 个的落位规则参数区是用户接触报表的第一屏排版乱不乱直接影响使用体验。规则不复杂但每条都要落到具体数字上一行最多放 6 个筛选项超过就换行。如果排成两行第二行至少要保留 2 个不能只剩孤零零一个挂在末尾。筛选项整体居左对齐不要居中也不要右对齐。标签和输入框的宽度统一不要一个宽一个窄。参数较多时优先压缩间距而不是缩小字号。一行 6 个的上限是经验值。超过 6 个每个筛选项分到的宽度就不够显示完整日期用户看到的是被截断的2024-01-...得点开才知道选没选对。第二行至少保留 2 个是为了视觉平衡——第一行 6 个、第二行孤零零 1 个看起来像排版事故用户会怀疑是不是少加载了什么。实际操作时先数参数总数7 个就排成 5 2 或者 4 38 个就 4 4 或 5 3不要机械地第一行塞满。日期区间类的参数开始日期、结束日期要挨着放中间不要插别的筛选项否则用户选完开始日期还要跳着找结束日期。5. 避坑排查装完不生效的五类现场这一章记的是我实际遇到过、并且能复现的问题。每一条按「现象 → 原因 → 解决」写遇到对得上的直接照着处理比从头重装快得多。现象一Excel 顶部压根没有 Smartbi 页签。原因通常是插件位数跟 Excel 位数不匹配或者加载项被 Excel 的安全策略禁用了。先按 2.1 的命令确认位数位数一致的话去 Excel 的选项里看「加载项」和「禁用的应用程序加载项」把被禁用的项重新启用重启 Excel。还有一种情况是安装时 Excel 没关干净文件被占用导致加载项注册失败卸载重装一次装之前确保任务管理器里没有EXCEL.EXE。现象二宏写好了刷新时一点反应都没有。原因有三个层次宏安全级别是「禁用所有宏」宏的触发对象选错宏没保存到服务器上本地改了但刷新加载的是服务器版本。排查顺序从上往下先看 Excel 宏设置再看宏管理里触发事件配置最后关掉本地文件重新从服务器打开一次确认保存动作真的生效。第三条最隐蔽本地改了直接点预览能看到效果一发布就回到原样因为发布走的是服务器上的宏。现象三参数校验弹窗没出现非法的日期组合照样刷出数据。八成是参数名对不上。getParameterValue(结束日期 2)里的字符串跟报表参数名差一个空格、差一个全角字符取到的就是空值new Date(空值)得到 Invalid Date比较运算永远为 false两条校验全部放行表面看就是「宏没生效」。把参数名复制出来跟代码里的字符串做逐字符比对这类问题基本一次就定位。现象四列宽自适应在本地预览正常发布后列还是挤在一起。检查宏是不是只建在了本地文件的宏管理里没有随报表一起保存到服务器另一个常见原因是自适应跑在数据加载之前拿到的是空表columnCount算出来偏小只处理了前几列。解决方式是把自适应放在刷新完成之后执行或者刷新后手动触发一次观察宽度是否变化——变了就说明时机问题没变就说明宏根本没跑。现象五冻结窗格之后滚动时表头错位一行或者多冻结了一行。第一行空白行是罪魁祸首。有人看到第一行是空的顺手删掉往上提冻结行数还是按 5 配的结果多冻了一行数据。处理办法是冻结配置跟模板结构绑死改结构必须同步改冻结行数并且改完上下滚动一次验证不要只看首屏。注意这五条里有三条最终都指向「参数名/函数名/时机」这三个点。装这类插件报错信息往往很含糊与其猜不如把能验证的地方先验证一遍——位数对不对、宏跑没跑、参数取到没取到这三件事查完剩下的才是代码逻辑问题。6. 预览发布与验证用三组极端参数确认这套报表真跑通了预览发布是文档里的最后一步但在我看来它只是开始——点发布按钮谁都会点能证明它跑通才算数。我的习惯是发布前先做一轮参数回归专挑边界值和非法值因为正常范围内的组合几乎不会出问题出问题的永远是边界。回归就用三组参数覆盖两个校验分支和一条正常路径组别开始日期结束日期预期结果第 1 组当天当天减 1 天弹「结束时间不能早于起始时间」刷新被拦截第 2 组当天当天加 91 天弹「两个参数的差不能超过 90 天」刷新被拦截第 3 组当天当天加 90 天正常刷新数据出得来第 3 组是很多人漏掉的一组。只测非法值不测临界合法值很容易把判断写成导致刚好 90 天也被拦用户反馈「差 90 天明明符合要求却报错」回头改又得重新发布一轮。把 90 天和 91 天各测一次边界就钉死了。参数回归过了接着看样式层的三件事顺序别乱向下滚动到数据区中部确认表头还在冻结生效且没有多冻一行。横向滚动到最右列确认列宽没有挤成一团也没有某一列宽到需要拖滚动条才能看到内容。隔行变色从数据区第一行开始表头没有被染色相邻两行颜色不同。第三件事容易被忽略因为隔行色错位在屏幕上看不出大问题但打印出来会很明显表头一行灰、数据第一行白整个节奏乱掉看起来像是数据少了一行。最后一步是导出和打印的验证很多人到这一步才发现问题。在预览界面导出一次 PDF 或者直接打印预览重点看两处右边有没有列被切到第二页每页顶部有没有重复表头。前者是缩放没设成「1 页宽」后者是打印标题行没配。这两项在屏幕预览里都看不出来非得走一次导出才暴露。我踩过最深的一次坑是把所有验证都做在本地文件上样式、宏、参数全对发布之后一切照旧。后来才想明白本地验证的是本地那份文件服务器上跑的是上一次保存的版本。从那以后我每次发完都强制走一遍「关掉本地文件 → 从服务器重新打开 → 再跑一遍三组参数」多花五分钟省掉的是用户那边的一轮返工。这套流程不复杂复杂的是每一步都有人觉得可以跳过。环境核对、宏的保存位置、参数名逐字比对、临界值测试四件事做完一份 Smartbi 报表基本就能稳定交付了。希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
