简介：《Smartbi报表设置文档》面向使用Smartbi制作电子表格报表的初级至中级用户，聚焦从模板引用到预览发布的完整设置流程，帮助解决报表样式不统一、列宽难调整、参数校验与排版不规范等常见问题。压缩包仅含1个docx文件，约1.05MB，篇幅集中，便于随查随用。文档依次讲解模板引用、页面设置与冻结行、隔行不同颜色、列宽自适应、参数设置、参数排版和预览发布，并给出列宽自适应宏、结束日期不早于开始日期且间隔不超过90天等参数校验代码示例，兼顾操作步骤与关键知识点说明。已有1304人学习；文档中的宏代码与参数校验示例可直接参照，读者可据此梳理设置顺序、理解宏脚本作用并减少重复调试，适合需要快速上手Smartbi报表设置或规范报表样式的用户参考。

1. Smartbi 报表设置文档落地：先看清这套 Excel 插件环境的版本坑

「Smartbi 报表设置」这件事，真正让人卡住的往往不是报表逻辑，而是第一天的环境：Excel 里那个 Smartbi 页签到底怎么出来、插件和服务端版本差了一截、宏明明保存了却一点反应没有。我见过最典型的一次，某开发者拿着整理好的报表设置文档照着做，模板引不出来，隔行变色设了等于没设，列宽自适应代码贴进去报错，折腾一下午才发现是插件跟服务端主版本没对上。这份文档把七个环节——引用模板、页面设置、隔行变色、列宽自适应、日期参数校验、参数排版、预览发布——按落地顺序串起来。适合刚接手报表开发、手里只有一台装了 Excel 的办公机和一套内网 Smartbi 的开发者，照着走完能跑通一张带参数校验的报表。

2. 环境准备与模板引用：把可编辑的报表底稿拿到手

2.1 客户端环境清单：Excel 位数和服务端主版本要先对上

装之前先别急着双击安装包，把环境逐项对一遍，能省掉后面八成的返工。这套东西的耦合点比一般插件多：Excel 是宿主，插件是加载项，宏跑在插件的运行时里，报表资源又存在服务端，任何一头版本错位，表现出来都是「功能没了」而不是「报错」。

先确认 Excel 是桌面版而不是网页版或第三方表格工具。Smartbi 的报表设计入口是挂在 Excel 里的一个页签，本质是个 COM 加载项，第三方表格软件没有对应的加载项机制，装完找不到入口是必然的。推荐 Excel 2016 及以后的零售版或订阅版桌面客户端，位数（32 位 / 64 位）必须和插件安装包一致，这点最容易被忽略——64 位 Excel 装 32 位插件，页签会静默消失，连个提示都没有。

插件安装包不要从别处拷贝，从自己服务端的首页下载入口取，这是最稳的做法。服务端和客户端插件必须是同一主版本，跨主版本装上去，页签能出来、模板也能打开，但宏 API 会悄悄少几个方法，等你写到列宽自适应那一步才发现autoFitColumns不存在，前面配的东西全得推倒重来。

注意：安装插件前把 Excel 全部关掉，包括后台残留的 EXCEL.EXE 进程，否则安装程序写注册表加载项时会失败，但界面照样提示完成。

2.2 装插件与登录：三步确认页签真的挂上了

第一步查位数。不想翻菜单的话，用一条 PowerShell 命令就能读出来，比在界面里点更准：

# 读取 ClickToRun 安装方式下 Office 的版本与位数 Get-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Office\ClickToRun\Configuration" ` -ErrorAction SilentlyContinue | Select-Object ClientVersionToReport, Platform, CDNBaseUrl

ClientVersionToReport是实际版本号，Platform返回x64或x86，直接决定你该装哪个安装包。如果这条命令什么都没返回，说明 Office 是 MSI 方式安装的，改从「文件 → 账户 → 关于 Excel」看版本行末尾的位数标识，效果一样。

第二步装插件。关掉 Excel，右键安装包以管理员身份运行，安装路径保持默认，装完重启 Excel。这时候看功能区有没有多出 Smartbi 页签。没出来的话，去「文件 → 选项 → 加载项」，底部管理下拉选「COM 加载项」点转到，看列表里对应项有没有被勾上；被勾上但页签还是没有，多半是位数不匹配或者加载项被安全策略禁用，去「禁用项目」里找找有没有它。

第三步登录。点页签里的登录按钮，填服务端地址（带协议和端口，不要带多余的路径）、账号、密码。登录成功后页签里的模板、宏管理、预览这些按钮才会从灰变亮。这一步失败最常见的原因不是密码错，而是地址写成了外网域名或者少了端口，内网环境直接写 IP 加端口最省事。

提示：登录时勾选记住地址，但不要在公用机器上勾记住密码，报表资源是按账号权限隔离的，串号登录能看到不该看的目录。

2.3 引用模板：先另存，再动手改

登录之后点「模板」，会拉出服务端的模板库，按业务分类排好。选一个结构最接近需求的打开，Excel 里就会出现一份带格式、带样式、可能还带示例宏的底稿。这一步是整个报表设置的地基，模板决定了列宽基准、字体、边框、打印区域这些默认值，后面所有调整都是在这上面做增量。

关键动作是「先另存，再动手」。模板是公共资源，很多时候是只读的，就算能编辑，你改完保存回去也会影响下一个引用它的人。正确顺序是：打开模板 → 立刻另存为一份新报表，放到自己有写权限的目录下，命名带上业务名和日期，比如「某业务明细_日期区间版」→ 之后所有改动都在新报表上做。这份文档我一般当模板素材用，另存的时候顺手把里面用不到的示例区块删掉，只留下页面设置、隔行色、列宽宏这三块骨架，下次开新报表直接复制这份骨架更快。

另存的时候有个细节要注意：电子表格报表的资源本身是存在服务端的，宏也跟着报表资源走，不是跟着本地文件走。所以本地另存一份.xlsm只当作样式备份和回滚用，真正生效的宏必须在页签的宏管理里维护。备份的价值在于，万一宏改崩了导致报表打不开，还能拿本地这份把版式重新贴回去，不至于从零再排一遍。

模板打开后如果发现列宽、行高全是乱的，先别怀疑模板坏了，检查一下 Excel 的显示比例和默认字体。模板是按特定字体排的，本机缺字体时会用替代字体渲染，列宽看起来就会「胀」出去，打印预览里更明显。装一下模板说明里要求的字体，或者把显示比例调回 100%，问题基本就消失了。

3. 页面设置与样式落地：冻结行、隔行变色、列宽自适应

3.1 页面设置：为什么冻结的偏偏是 1 到 5 行

页面设置这一块看着简单，实际是最容易做出「在自己机器上好看、发出去就变形」的地方。先说要冻结几行这件事。文档里给的口径是冻结 1 到 5 行，原因很实在：报表第一行是空白行，用来撑开顶部留白、放标题或者给筛选控件留位置，真正的表头从第二行开始，到第五行结束（多行表头，包含分组列名）。所以冻结 1 到 5 行，滚动数据区的时候表头始终贴在顶上，第一行那块空白也跟着固定，视觉上不会突兀地空出一条。

操作上是把光标点到 A6 单元格，然后「视图 → 冻结窗格 → 冻结拆分窗格」。冻结的逻辑是「冻结选中单元格上方的所有行、左侧的所有列」，点 A6 就是冻结前 5 行、不冻结任何列。如果点到了 B6，那 A 列也会被冻结，横向滚动时第一列不动——有些报表确实需要这个效果，但对绝大多数明细表来说，冻错列比不冻更难受。

页面设置里其余几项我一般这么定：

打印标题行这一项特别值得强调。冻结窗格只影响屏幕，打印是另一套逻辑，两个地方要分别设，而且行号口径要统一成 1 到 5。我踩过一次坑：屏幕上冻结的是 1 到 5 行，打印标题设成了 2 到 5 行，结果导出的 PDF 第一页有顶部空白、第二页开始没了，客户拿着文件问「为什么每页长得不一样」。

3.2 隔行不同颜色：条件格式和宏刷色怎么选

隔行变色是为了让横向读一行数据时不串行，尤其是列数超过十个的明细表。主流做法有两种，选哪种取决于你的报表要不要导出、要不要打印。

第一种是条件格式，配置成本最低。选中数据区（比如$A$6:$H$200），「开始 → 条件格式 → 新建规则 → 使用公式确定要设置格式的单元格」，填入公式：

=MOD(ROW(),2)=0

ROW()取当前行号，MOD(ROW(),2)=0表示偶数行命中，然后给命中的行设一个浅底色。起始行写$A$6是因为前 5 行是表头，从第 6 行开始才是数据；范围结束行写死 200 是因为条件格式需要一个确定的区域，行数会增长的报表要留足余量，或者干脆应用到整列$A:$H（代价是文件体积变大、滚动变卡）。公式里的行号用相对引用（不带$），列号用绝对引用，这样格式会按行扩散而不是按单元格扩散。

第二种是在宏里刷底色，可控性更强：

function main(spreadsheetReport) { var sheet = spreadsheetReport.workbook.worksheets.get(0); if (sheet === "" || sheet === null) { return; } var rows = sheet.cells.maxDisplayRange.rowCount; // 已用区域总行数 var cols = sheet.cells.maxDisplayRange.columnCount; // 已用区域总列数 for (var r = 5; r < rows; r++) { // 前 5 行是表头，从索引 5（第 6 行）开始 if (r % 2 === 0) { sheet.getRange(r, 0, 1, cols).backColor("F2F6FC"); // 偶数行刷浅蓝底 } } }

maxDisplayRange拿到的是实际有内容的区域，行数列数都从这里取，比写死范围稳。循环从r = 5开始跳过表头（索引从 0 计），r % 2 === 0判断偶数行，getRange(r, 0, 1, cols)表示从第 r 行第 0 列起、取 1 行 cols 列，最后backColor传十六进制色值。不同版本里这个 API 的名字可能有差异，写之前先在宏管理的 API 提示里确认一下方法名，别硬套。

选型建议很直接：报表只在浏览器里看，条件格式够用而且改起来快；报表要导出 Excel 给别人继续加工、或者要打印成 PDF，用宏刷色更保险，因为条件格式在导出和打印环节被丢掉的情况不算罕见。这段代码属于通用件，任何一张需要隔行底色的报表都能原样搬过去，唯一要改的是起始行号和色值。

3.3 列宽自适应：把 main 函数拆到每一行

列宽是最烦人的一项。手工拖列宽，数据一刷新长度变了又得重拖，几十列的表根本拖不过来。文档里给的方案是一段通用宏，全局生效，调试阶段也可以临时改成只对某一列生效：

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 开始；如果报表有多个 sheet，得改成对应索引。紧接着的空值判断别省，某些场景下（比如报表刚打开、渲染没完成）拿到的sheet是空字符串或 null，不判空直接往下走就是一个红叉报错。

maxDisplayRange.columnCount是当前已用区域的总列数，这个值会随数据变化，比写死数字靠谱。autoFitColumns(0, counts)的语义是「从第 0 列到第 counts 列做自适应」，第一个参数是起始列索引，第二个是结束列，注意列索引从 0 开始，所以counts作为结束参数刚好覆盖到最后一列。如果只想调某一列，把那行注释掉，换成下面那句autoFitColumn(3)，参数就是单个列索引，3 代表第四列。

调试期我一般两种都用：先全局自适应看整体效果，发现某一列（比如备注列或者名称列）被内容撑得过宽，就把全局那句注释掉，单独对几列做自适应，剩下的列手工定宽。全自适应最大的副作用是长文本列会把整张表撑到一屏放不下，而表格类报表恰恰需要「一屏能看到关键列」。

还有一个顺序问题值得记一笔：列宽自适应要放在隔行刷色之后执行。反过来的话，刷色时用的是旧列宽，自适应后区域变了，底色可能只覆盖到一半。宏的执行顺序就是代码里的书写顺序，多个宏在一个入口里按先后写就行。

4. 日期参数校验宏：doRefresh 重写的参数与边界

4.1 参数定义：名字里那个空格和「2」都不能省

参数校验的前提是参数先定义对。文档里的场景是有开始日期和结束日期两个参数，要求结束日期不早于开始日期、且两者相差不超过 90 天。这两条约束里，第一条是逻辑正确性，第二条是性能保护——跨度过大的查询会把后端拖垮。

先看参数定义这一步。参数名称、参数类型、控件类型三样要对齐：名称按报表实际用的写（示例里是带「2」后缀的开始日期 2、结束日期 2），类型选日期，控件选日期选择器。带后缀这件事不是随便加的，同一张报表里如果存在多个数据集或者多个查询块，参数名重复会互相覆盖，加后缀是为了区分。麻烦的地方在于，宏里取值用的是字符串精确匹配，多一个空格、大小写差一点，取到的就是空值，而空值参与new Date()会得到Invalid Date，后面的比较全部失效，界面上表现为「校验不生效、怎么选都能刷新」。

参数定义完还有一步是绑定，把参数挂到数据集的查询条件上，否则界面上能选、点刷新没反应。绑定关系在数据集那边配，报表这边只负责收集值。

4.2 宏管理挂载：为什么不用刷新后事件，而要重写 doRefresh

新建宏的入口在 Excel 的 Smartbi 页签下的宏管理里，点新建，起个能看懂的名字（比如「日期区间校验」），把代码贴进去，保存。保存后宏是存在报表资源里的，跟着报表走，换台机器打开同一张报表，宏还在。

function main(spreadsheetReport) { if (!spreadsheetReport._jhy_doRefresh) { // 把原始 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); // 校验通过，调用原始刷新 }; }

这段的核心是「劫持刷新」。doRefresh是报表刷新时框架调用的方法，重写它等于在刷新动作前面插一道闸门。第一段用_jhy_doRefresh这个自定义属性把原始方法存下来，存之前先判断有没有存过——这个判断很关键，宏在某些情况下会被重复执行，不判断的话第二次执行会把「已经被重写的方法」再存一遍，形成自我递归，点一次刷新能卡死浏览器。最后一行this._jhy_doRefresh(fromButton, delayMask)是校验通过后放行，参数原样透传，保证刷新行为跟原来完全一致。

main在这里的职责只是「安装拦截器」，真正干活的是被重写后的doRefresh。所以这段代码的特点是：main执行一次，拦截器长期有效；不要指望在main里直接读参数值，那个时机参数可能还没初始化完。

4.3 90 天差值：时间戳、时区和那个 replace 的作用

日期比较这一段有三个技术点，随便错一个都会翻车。

第一个是replace(/\-/g, "/")。参数返回的日期字符串格式通常是2024-01-01这种带短横线的形式，而部分浏览器内核对new Date("2024-01-01")的解析行为和new Date("2024/01/01")不一样，前者容易被当成 UTC 时间，后者才按本地时区解析，两者差出 8 小时，边界日期上就会莫名其妙地差一天。全局替换成正斜杠是最省事的兼容做法，一行正则搞定。

第二个是差值计算。getTime()拿到的是毫秒时间戳，1000 * 3600 * 24 * 90依次是「秒 → 毫秒」「分钟 → 秒」「小时 → 分钟」「天 → 小时」，最后乘 90 天。算下来是 7776000000 毫秒。这里要注意方向：endtime.getTime() - starttime.getTime()是结束减开始，结果为正说明结束在后，符合预期；如果写成开始减结束，那所有正常的时间段都会被判成超限。边界值上，正好 90 天不拦截（用的是>不是>=），要不要卡这个边界看业务口径，很多场景下 90 天整应该是允许的。

第三个是那个setTimeout(..., 100)。看上去像是随手加的延时，其实有实际作用：刷新动作会拉起遮罩层，如果同步弹alert，弹窗容易被遮罩盖住或者被后续的 DOM 操作挤掉，用户只看到界面卡住没有提示。延后 100 毫秒让遮罩先渲染完，弹窗才能正常显示在顶层。return必须跟在后面，它的作用是中断当前函数，不执行最后的放行调用——少了这个return，弹窗弹出来了但报表照样刷新，校验等于没做，这是这段代码里最容易漏的一行。

改这段代码的时候有个通用原则：两个if里的提示文案要写清楚是哪条规则被违反了，别都写「参数错误」。用户看到「两个参数的差不能超过 90 天」才知道该改哪个日期，看到「参数错误」只能来问你。

5. 参数排版与预览发布：五类常见问题排查

5.1 参数排版：一行不超过 6 个，两行至少留 2 个

参数排版的规则文档里写得很克制：筛选项居左，每行尽量美观的基础上平均分配，一行不超过 6 个，如果排成两行，第二行至少要保留 2 个。这几条不是审美偏好，是交互约束。

一行不超过 6 个，是因为参数控件（日期选择器、下拉框、文本框）本身有最小宽度，超过 6 个之后每个控件会被压到看不清标签，用户点日期选择器的时候容易点错旁边的下拉框。第二行至少留 2 个，是因为只有 1 个参数孤零零挂在第二行左侧，视觉上会显得第一行塞爆了、第二行空荡荡，而且参数区高度被撑成两行，数据区又被往下推一截。真遇到 7 个参数的情况，宁可拆成 4 + 3 或者 5 + 2，也别做成 6 + 1。

具体操作是在报表的参数面板里拖动排序，把同类的放一起：日期类挨着日期类，维度筛选挨着维度筛选，别把「开始日期」和「部门」混在一行。居左对齐是默认要求，因为参数区通常只占报表上方一小条，居左能让视线起点固定，用户每次进来扫一眼就知道从哪开始选。

5.2 五条踩坑记录：现象、原因、解决

其一：Excel 里根本没有 Smartbi 页签

现象是装完插件、重启 Excel，功能区干干净净，找不到任何入口，重装两遍也没用。原因有两个方向，一是插件位数和 Excel 位数不一致，64 位 Excel 装了 32 位加载项，加载项注册表项写进去了但被宿主直接忽略；二是加载项被 Excel 的安全策略列进了禁用清单，通常发生在插件崩溃过一次之后，Excel 会自动把它拉黑。解决顺序是先按 2.2 那条 PowerShell 确认位数，位数一致的话去「文件 → 选项 → 加载项 → 管理：禁用项目 → 转到」，把里面的相关项启用，再重启 Excel。两个方向都排除了还不行，检查安装时 Excel 是否真的完全退出——任务管理器里如果有残留进程，注册表写入会失败但界面提示成功。

其二：宏保存了，点刷新一点反应都没有

现象是宏管理里能看到刚写的宏，代码也没报错，但点刷新该弹的提示不弹，该拦截的不拦。原因多半是宏没有绑定到当前报表资源，或者宏的名字被改过——入口函数必须叫main，改成main2、checkDate都不会被调用。另一个高频原因是main里写了逻辑，但校验逻辑本该放在被重写的doRefresh里，main只在报表初始化时跑一次，那个时机参数还是空的，取到的值是 null，所有比较都返回 false，于是静默通过。解决方法是确认函数名是main，确认参数读取写在重写后的doRefresh内，再在代码里临时加一行console.log或者alert打印取到的参数值，看是不是空。

其三：列宽自适应把表头撑爆，或者整张表没变化

现象是加了自适应宏之后，某些列突然变得极宽，一屏只能看到三列；或者相反，跑完宏列宽纹丝不动。撑爆的原因是自适应把长文本列（比如备注、详细描述）按内容长度算进去了，这类列不该参与自适应。没变化的原因是maxDisplayRange.columnCount取到的值是 0 或者异常小的数，通常发生在宏执行时机太早、数据还没渲染完，或者在错误的 sheet 索引上操作。解决办法是把全局自适应改成按列指定，长文本列单独定宽；时机问题上，确认宏挂在报表渲染完成后的钩子上，而不是页面一打开就跑。

其四：日期校验的弹窗一直弹，点掉之后还是不让刷新

现象是选了个完全合法的日期区间，弹窗照样跳出来，点确定还是刷不了。原因是日期字符串解析失败，new Date(...)得到Invalid Date，Invalid Date参与任何比较都返回 false，endtime < starttime是 false、差值比较也走不通，代码逻辑上就乱了套。解析失败的根源是参数名对不上，getParameterValue("结束日期 2")里的空格或者后缀跟参数定义不一致，取到空字符串。解决方法是把参数定义页里的名称复制出来直接粘进代码，别手敲；同时在解析后加一句有效性判断，取不到值就直接放行或者给出明确提示，不要让Invalid Date往后走。

其五：隔行变色在预览里好好的，导出或者打印全白了

现象是浏览器里看报表，隔行底色清清楚楚，导出成 Excel 或者打印成 PDF，色带全丢。原因是条件格式依赖的公式在导出环节被重新求值，而导出后的文件里行号基准变了（比如表头被合并、空行被裁掉），MOD(ROW(),2)算出来的奇偶跟屏幕上对不上；另一种情况是导出模块本身不搬运条件格式。解决办法是改用宏直接刷底色，底色是单元格属性，导出时跟着走；如果坚持用条件格式，导出后抽一页核对，别等发给业务方了才发现。

6. 验证跑通：拿三张报表过一遍才算装完

环境装完、宏写完，别急着说搞定。我一般会造三张最小的验证报表，每张只验一件事，全过了才算这套环境真的能用。

第一张验列宽。随便拉十列数据，其中一列故意放长文本，跑一遍自适应宏，看那列长文本是不是被撑爆；撑爆了就说明该改成按列指定，然后把长文本列手工定宽再跑一次。第二张验日期。参数区只放开始日期 2和结束日期 2两个控件，依次测四种输入：结束早于开始、跨度正好 90 天、跨度 91 天、两个日期相同。预期结果是第一种弹窗、第二种放行、第三种弹窗、第四种放行。四种全对，说明字符串解析、时区、边界这三关都过了。第三张验样式。设好隔行色之后导出一次 Excel、打印一次 PDF，两处都要能看到色带，看不到就换成宏刷色再验一遍。

验证清单可以直接照着下面这张表走，每项打勾：

这三张验完，再把它们删掉，回到真实报表上做最后一轮：改一次参数、刷新一次、导出一次、打印一次。四步都顺，就可以交付了。

血泪经验是：以前我总觉得宏写完、点两下没报错就是好了，结果交付当天业务方选了个跨半年的区间，报表转了十几秒才出来，回头查才发现 90 天那条校验的return被我删掉了，弹窗弹了但刷新照跑。从那以后我每次配完参数校验，都强制走一遍那四种输入的组合测试，一个都不跳。这份报表设置文档我按这个顺序整理成了一份可以打印的册子，装环境的时候摊在旁边对着勾，比来回翻屏幕省事。希望帮到你。

本文还有配套的精品资源，点击获取