简介：《Smartbi报表设置文档》面向使用Smartbi制作电子表格报表的初中级人员，也可作为模板素材供日常报表美化与规范化参考。内容覆盖模板引用、页面设置、隔行不同颜色、列宽自适应、参数校验、参数排版和预览发布等设置环节，并结合知识点说明各环节的作用与注意事项；其中列宽自适应、起止日期范围校验等宏代码片段具有直接借鉴价值，便于读者理解报表结构、参数逻辑与版面细节。资源包共1个文件，为单个docx文档，约1.05MB，篇幅集中、查阅方便，适合按章节检索。已有1305人学习下载，可作为报表设置与问题排查的参考素材，帮助读者把握关键设置项并用于实际报表制作。
1. 从 Excel 里找不到 Smartbi 页签说起
第一次把这份 Smartbi 报表设置文档交给同事照着做，对方在 Excel 里翻了半天，功能区就是没有 Smartbi 页签，最后发现装的是 32 位插件、Office 却是 64 位。这类问题跟报表逻辑无关，全卡在环境上。Smartbi 的电子表格报表并不以独立客户端的形式存在，它依附在 Excel 里：先装插件、登录服务端、引用模板，再谈页面设置、隔行变色、列宽自适应和参数校验。这份设置文档更像一套可以直接复用的模板素材，适合已经拿到账号、需要在 Excel 里做中国式报表的人；环境不对，后面每一步都会变形，预览和发布也容易出问题。
2. 装前把环境列清：Excel 插件与服务端版本的对齐清单
2.1 这套环境到底由哪几层组成
Smartbi 电子表格报表的运行环境可以拆成四层，任何一层错配，表现都像“报表坏了”，实际是环境没对齐。第一层是 Excel 客户端，负责承载工作簿和界面；第二层是 Smartbi Excel 插件，负责在功能区挂出 Smartbi 页签、打通登录和模板读取；第三层是 Smartbi 服务端，负责账号、模板库、参数和发布；第四层是报表文件本身，包括单元格样式、条件格式、宏代码和参数定义。
我一般先让环境对照表落地，再动手装。下面这张表是交付前必须确认的内容，缺一项后面都可能返工。
| 层级 | 装什么 | 判断标准 | 常见错配 |
|---|---|---|---|
| Excel | 与本机 Office 位数一致的客户端 | 文件→账户→关于 Excel，确认 32 位或 64 位 | 64 位 Office 装 32 位插件，页签不出现 |
| 插件 | 与服务端同代的 Excel 插件 | Excel 的 Smartbi→关于，看插件版本 | 插件比服务端新或旧，登录报协议不匹配 |
| 服务端 | 已开通账号和报表模板权限 | 浏览器能登录，能看到“模板”目录 | 账号只有查看权限，打不开模板 |
| 报表文件 | 启用宏的工作簿 | 文件后缀是.xlsm，不是.xlsx | 存成.xlsx，宏全部丢失 |
这张表里最容易被忽略的是报表文件格式。Excel 的.xlsx从设计上就不保存 VBA 宏，而这份设置文档里的参数校验、列宽自适应都依赖宏。很多人调试时一切正常，关掉再打开就发现宏没了，以为是插件不稳定，实际是保存格式选错。常见做法是：只要这个报表需要宏，第一次另存为就选“Excel 启用宏的工作簿（.xlsm）”，后面所有修改都在这个文件上做。
2.2 版本选择与下载来源的判断
版本选择不要追求“最新”，先追求“同代”。插件和服务端之间通常有协议约定，插件过新可能调用服务端没有的接口，插件过旧可能读不到新模板属性。判断方法不复杂：浏览器登录服务端，在登录后的关于页面或帮助菜单里看服务端版本；Excel 里点 Smartbi 页签的“关于”，看插件版本；两边主版本保持一致，小版本差一截一般还能用，但不要跨大代。
下载来源也要克制。插件安装包我一般只从两个地方拿：服务端登录页提供的客户端下载入口，或者内部统一放的软件目录。不去第三方下载站抓安装包，原因是这类插件要注册 Excel 加载项，来路不明的包很容易带旧版运行库，装完页签能出来，登录却一直转圈。还有一个细节：安装前把 Excel 完全退出，任务管理器里确认EXCEL.EXE没有残留。Excel 只要还有一个后台进程，插件文件就可能被占用，安装程序提示成功，实际只写了一半。
安装步骤可以按下面这个顺序走，每一步都有明确的通过标准：
- 关闭所有 Excel 窗口，任务管理器结束残留的
EXCEL.EXE。 - 右键插件安装包，选择“以管理员身份运行”，避免注册表写入被拦。
- 安装类型选与 Office 位数一致的那一项，不要两个都勾。
- 打开 Excel，看功能区是否出现 Smartbi 页签。
- 点“登录”，填服务端地址、账号、密码，地址不要带多余路径。
- 登录后点“关于”，核对插件版本和服务端是否同代。
第 3 步是最容易图省事的地方。有人觉得“两个都装总有一个能用”，实际两个位数的加载项同时注册，Excel 启动时会先加载错的那个，表现是页签闪一下消失，或者点登录直接报“加载项初始化失败”。真遇到这种情况，不要去改注册表，先到控制面板卸载插件，重新只装匹配位数的那一个，比手工清残留稳。
2.3 安装 Excel 插件与登录验证
装完插件只是第一步，登录验证要看到三样东西才算通过：Smartbi 页签稳定存在、登录后能列出模板目录、打开模板后单元格右键能看到 Smartbi 相关菜单。三样缺任何一样，都不要继续往下做页面设置，否则后面调宏会把环境问题误判成代码问题。
登录环节常见的坑是地址写法。服务端地址一般写到应用根路径，不要带/smartbi/后面的具体页面，也不要在末尾多加斜杠。地址写错时，插件不一定报“地址错误”，而是转圈很久然后提示登录失败，看起来像账号问题。我一般的排查顺序是：先用浏览器在同一台机器上打开这个地址，确认能出登录页；再把地址原样粘贴到插件登录框；最后才怀疑账号权限。这个顺序能排掉大半“玄学”问题。
登录成功之后，不要急着新建报表。先点“模板”，看能不能打开一个现成模板。模板目录能打开，说明账号有模板读取权限，服务端和插件的通信链路是通的；如果模板目录是空的，或者点开提示无权限，先找管理员加权限，不要在工作簿里反复重装插件。装环境最怕的就是把权限问题当成安装问题，来回卸装三遍，最后发现只是账号没挂到报表角色上。
3. 从模板到页面设置：把报表骨架一次装对
3.1 引用模板：Smartbi 页签下的正确打开方式
引用模板是整份设置文档的第一步，也是最值得慢下来的一步。操作路径不复杂：在 Excel 里点 Smartbi 页签，登录，点“模板”，在模板列表里选中目标模板打开。打开后不要直接在设计器里改，先另存一份本地副本，命名带日期和用途，比如“某报表-参数版-日期”。这样做不是形式主义，模板是多人复用的素材，直接改原模板，别人再引用时拿到的就是半成品。
打开模板后先确认三件事：工作表名称是不是预期的、冻结窗格位置对不对、参数面板是否已经带出来。工作表名称看着无关紧要，但后面的宏里如果按名称取 sheet，名称被改过就会取不到；冻结窗格决定预览时表头是否跟着滚动；参数面板决定后面参数校验能不能拿到值。这三件事确认完，再开始设计新报表样式。
设计样式时，我一般把“数据区”和“装饰区”分开看。数据区放字段、指标和扩展格，装饰区放标题、说明、单位、更新时间。分开的好处是后面设置隔行颜色和列宽自适应时，不会把标题行也卷进去。比如列宽自适应如果从第 0 列扫到最大列，标题行里有合并单元格，自动列宽就会把整表拉得很奇怪。常见做法是先把数据区做出来，再补标题和说明，最后统一调样式。
模板引用还有一个容易忽略的点：模板里可能已经带了宏。打开模板后先到 Smartbi 页签下的“宏管理”看一眼，如果已有宏，不要直接覆盖，先记下宏名和作用对象，再决定是新建还是改旧宏。覆盖别人的宏，轻则参数校验失效，重则整个模板刷新逻辑被改坏，这种返工在多人环境里很常见。
3.2 页面设置：冻结 1-5 行与第一行空白行
这份设置文档里明确写了：第一行是空白行，所以报表冻结的是 1-5 行。这个细节看起来小，实际影响预览和打印。第一行留空，通常是为了给标题、筛选说明或页面留白，冻结 1-5 行则是为了让表头在滚动时始终可见。冻结位置写在A6，意思是第 1 到第 5 行固定，第 6 行开始滚动。
页面设置我一般按下面这张参数表走，具体值按报表宽度微调，但顺序不要乱：
| 设置项 | 建议值 | 说明 |
|---|---|---|
| 纸张 | A4 横向 | 列数多的报表竖向放不下 |
| 缩放 | 85% 左右 | 先保证一页宽，再调高度 |
| 打印标题 | $1:$5 | 与冻结行保持一致 |
| 冻结窗格 | A6 | 第 6 行以上固定 |
| 第一行 | 留空 | 给标题和说明留位置 |
| 页边距 | 窄 | 给列宽留空间 |
设置顺序建议是：先冻结，再调列宽，最后设打印缩放。反过来先缩放到 85%，再调列宽，列宽一变缩放又不够，来回改很折腾。冻结窗格在 Excel 里是视图属性，在 Smartbi 预览里不一定原样保留，所以打印标题要单独设，不能只靠冻结。这个区别在后面发布环节还会提到。
第一行空白行还有一个实际作用：给参数面板留位置。有些报表参数比较多，参数区会占一两行，如果第一行直接是表头，参数一展开就把表头往下顶，冻结区域也跟着乱。留一行空白，参数区有地方放，表头位置也稳定。这个做法不算严格规范，但在实际交付里很省事。
3.3 隔行不同颜色与列宽自适应
隔行不同颜色用 Excel 的条件格式做，不要手工填色。手工填色在插入行、删除行、排序之后会错位，条件格式不会。选中数据区，新建规则，用公式判断行号奇偶：
=MOD(ROW(),2)=0这个公式的意思是当前行号除以 2 余数为 0 时命中规则，也就是偶数行填色。ROW()不带参数返回当前行号，MOD取余。应用区域要选数据区，不要把标题行和合计行卷进去；如果合计行也要区分，单独给它加一条规则，不要和隔行色混在同一个区域。填充色建议用浅灰或浅蓝，饱和度低一点，打印时不至于把字盖住。
列宽自适应用 Smartbi 的宏来做，这份设置文档给了一段通用代码，可以直接抄：
function main(spreadsheetReport) { // 取当前工作簿的第 1 个工作表；多 sheet 场景要按名称取 var sheet = spreadsheetReport.workbook.worksheets.get(0); if (sheet === "" || sheet === null) { return; } // maxDisplayRange.columnCount 取有内容区域的最大显示列数 var counts = sheet.cells.maxDisplayRange.columnCount; // 从第 0 列到 counts 列做自适应；结束列按实际接口边界传 sheet.autoFitColumns(0, counts); // 调试单列时改用下面这行，第 4 列索引是 3 // sheet.autoFitColumn(3); }这段代码的逻辑分三步：先取工作表，再取最大显示列数，最后整段自适应。get(0)取的是第一个工作表，如果模板里有多个 sheet，而数据不在第一个，就要改成按名称取，否则sheet可能取到说明页，列宽自适应作用在空白页上，看起来像没生效。判空那两行不要省，空工作簿或模板还没加载完时，sheet可能是空字符串或null，不判空会直接抛错。
maxDisplayRange.columnCount取的是有内容区域的最大列数，不是整张表的 16384 列。这个区别很重要：用它做结束列，不会把空白列也拉宽；但如果数据区后面还有说明文字，说明文字也会被算进去，列宽就会偏。调试时我一般先用单列模式autoFitColumn(3)确认第 4 列能正常自适应，再放开到整段。整段设置适合交付前跑一次，单独设置适合调样式时用，两种方式不冲突。
还有一个边界要注意：autoFitColumns(0, counts)的结束列如果传成counts，而接口按闭区间处理，最后一列会多算一列；如果按开区间处理，最后一列可能没算进去。不同版本插件对这个边界的处理不完全一致，所以交付前要肉眼检查最后一列，别只看前几列。列宽自适应不是越宽越好，指标列拉得太宽，打印时会被迫缩小，字反而看不清。我一般把文本列放宽、数字列收窄，自适应跑完再手工微调两列，比纯自动更稳。
4. 宏与参数校验：结束日期不早于开始日期、跨度不超 90 天
4.1 宏管理入口与新建宏
参数校验要挂在宏上，入口在 Excel 的 Smartbi 页签下，点“宏管理”，新建宏。新建时先起一个能看懂的名字，比如“日期区间校验”，不要用“宏1”“test”这种名字，后面报表多了根本分不清。宏建好后，把代码粘进去，保存，再回到报表点预览或刷新，看是否生效。
宏管理里最容易出错的是作用对象。宏要挂在当前报表上，不是挂在模板库上；有些环境里宏管理会列出多个报表，选错报表，代码保存成功但刷新不触发。我一般的确认方法是：保存宏后，在报表里改一个参数值，点刷新，看有没有弹出校验提示；没有提示就先检查宏管理里当前选中的是不是这个报表，再检查宏有没有被禁用。Excel 的信任中心如果禁用宏，代码保存得再对也不会跑，表现是“什么都不发生”，这种静默失败最容易被误判成代码写错。
新建宏之后不要马上写复杂逻辑，先写一个最小验证宏，比如弹出一句“宏已加载”，确认链路通了，再替换成正式代码。这个习惯能省很多时间：链路不通时，你改十遍日期逻辑都没用；链路通了，再调参数名和边界。
4.2 重写 doRefresh 的参数校验逻辑
这份设置文档要求：结束日期不早于开始日期，且结束日期不大于开始日期 90 天。实现方式是重写doRefresh，在真正刷新前先校验参数，不通过就拦下来。代码如下，注释是我补的：
function main(spreadsheetReport) { // 先保存原始的 doRefresh，避免重写后丢失原逻辑 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先把原始方法存起来，后面校验通过再调回去；不存直接重写，刷新逻辑就丢了，表现是点刷新没反应。第二，getParameterValue里的参数名必须和参数面板里的名称完全一致，包括空格和后缀。文档里写的是“结束日期 2”“开始日期 2”，说明参数面板里确实带“2”后缀，如果写成“结束日期”，取到的是undefined，new Date(undefined)得到无效日期，比较结果永远为false，校验看起来像没生效。第三，replace(/\-/g, "/")是把2024-01-01转成2024/01/01，部分环境下new Date对短横线格式解析不稳定，转成斜杠更稳。
setTimeout(..., 100)不是为了炫技，而是把alert挪出当前刷新调用栈。直接alert在某些版本里会阻塞刷新线程，弹窗关闭后页面状态不对；延后 100 毫秒再弹，体验更稳。return的位置也很重要：它在alert外面，校验不通过就直接结束，不再调用原始刷新；如果只弹窗不return，提示弹了但报表还是刷新了，等于没拦。
90 天的计算用毫秒：1000 * 3600 * 24 * 90，即 90 天的毫秒数。这里没有算时区和夏令时，因为比较的是两个日期参数的差值，不是跨时区时间点，按天算足够。如果业务要求“含头含尾”，边界要单独确认：正好 90 天算不算超？代码里用的是>，等于 90 天放行，超过才拦。这个边界最好在交付前跟需求方确认一句，避免上线后为“第 90 天”扯皮。
4.3 参数排版：一行不超过 6 个的分配规则
参数排版不是纯审美问题，它影响预览时的可读性和打印效果。这份设置文档给的规则很具体：筛选项居左，每行尽可能平均分配，一行不超过 6 个，如果是两行，第二行至少保留 2 个。我一般按下面这个思路排：
| 行 | 放什么 | 数量控制 |
|---|---|---|
| 第一行 | 日期区间、机构、报表类型 | 不超过 6 个 |
| 第二行 | 客户等级、是否含税等次要筛选 | 至少 2 个 |
| 操作区 | 查询、重置 | 单独放右侧或下一行 |
一行超过 6 个，参数标签会挤成两行，输入框变窄，日期选择器弹出来还会挡住相邻参数。两行排版时第二行只剩 1 个，视觉上会显得头重脚轻，所以规则要求至少保留 2 个。这个规则不是硬性技术限制，是排版经验，目的是让筛选区看起来平衡。
参数名也要统一。文档里的参数带“2”后缀，说明面板里可能有多套日期参数，排版时要把标签写清楚，比如“开始日期”“结束日期”，不要让用户看到“开始日期 2”这种内部名称。标签是给人看的，参数名是给宏取的，两者可以分开设置；如果环境不支持单独设标签，就在参数前面加说明文字，别把内部后缀暴露到界面上。
排版完成后，把参数区冻结在表头附近，预览时滚动数据，筛选区仍然可见。参数多的报表，我一般把常用筛选放第一行，低频筛选收进第二行，查询按钮放最右侧，符合从左到右的阅读习惯。排完不要只看设计器，一定点预览看实际渲染，设计器里对齐的控件，预览时可能因为浏览器字体差异挤在一起。
5. 避坑与排查：Excel 插件、宏、参数联调里最常见的 5 个坑
5.1 Smartbi 页签不出现，登录按钮是灰的
现象：Excel 打开后功能区没有 Smartbi 页签，或者页签在但登录按钮灰色，点不动。
原因通常有三个：插件位数和 Office 位数不匹配；安装时 Excel 没退干净，加载项只注册了一半；Excel 的“禁用项目”里把插件拦了。位数问题最常见，64 位 Office 装 32 位插件，页签可能短暂出现然后消失；安装残留则是页签在，但点登录提示初始化失败。
解决顺序：先到文件→选项→加载项→管理“禁用项目”，看列表里有没有 Smartbi 相关项，有就启用；再确认 Office 位数和插件位数；最后卸载重装，装之前任务管理器结束所有EXCEL.EXE。不要一上来改注册表，先走这三步，大部分情况能解决。重装后还是灰的，检查账号是否有插件登录权限，有些环境会按角色控制客户端登录。
5.2 宏保存后重新打开就没了
现象：宏管理里写好的代码，保存、关闭、重新打开工作簿，宏列表空了，或者代码还在但不执行。
原因：工作簿存成了.xlsx。这个格式不保存 VBA 宏，保存时 Excel 可能只弹一句“某些功能会丢失”，点快了就过去了。另一个原因是文件从外部拷进来时被 Windows 标记为“来自其他位置”，Excel 信任中心会禁用宏。
解决：第一次另存为就选“Excel 启用宏的工作簿（.xlsm）”；已经存错的，打开后重新另存为.xlsm，再把宏补回去。文件属性里如果有“解除锁定”，勾上再打开。信任中心可以把存放报表的目录加进受信任位置，减少每次弹提示。交付时把.xlsm和说明一起给，别只给.xlsx，否则接收方一打开就是无宏状态。
5.3 列宽自适应报“对象为空”或整表列宽被拉到异常
现象：执行自适应宏时提示对象为空，或者执行成功但某一列被拉得特别宽，打印时整表缩小。
原因：worksheets.get(0)取到的不是数据页；模板还没加载完就执行宏，sheet为空；maxDisplayRange把说明文字或合并单元格算进去了；结束列边界传错，多算了一列空白列。
解决：先判空，再用工作表名称取 sheet；调试时改用autoFitColumn(3)单列执行，确认目标列；把数据区后面的说明文字挪到单独区域，避免被算进最大列；结束列传参前打印一下counts的值，看是否符合预期。整表拉宽后不要反复执行自适应，先手工把异常列调回来，再单列跑。合并单元格多的表，自适应本身就不稳，这类表建议固定列宽，不跑全表自适应。
5.4 参数校验不触发，点查询直接刷新
现象：日期填反了，点查询没有提示，报表照常刷新；或者提示弹了，但数据还是刷新了。
原因：宏没挂在当前报表上；doRefresh重写顺序不对，原始方法没保存；参数名写错，getParameterValue取到undefined；alert后面没return，弹窗归弹窗，刷新继续走。
解决：先在宏管理里确认当前报表和宏的绑定关系；在getParameterValue后面加一行console.log或临时alert，把取到的值打出来，确认参数名和值都对；检查_jhy_doRefresh是否在最前面保存；检查每个校验分支是否有return。参数名带空格或后缀的，复制参数面板里的名称，不要手敲。校验逻辑改完后，至少测三种情况：结束早于开始、跨度正好 90 天、跨度超过 90 天，三种都符合预期才算通过。
5.5 预览正常，发布后冻结和隔行色丢失
现象：本地预览时冻结窗格和隔行颜色都正常，发布到服务端后，冻结没了，隔行色只显示一部分。
原因：冻结窗格是 Excel 的视图属性，服务端渲染成网页后不一定保留；隔行色如果用条件格式，发布时可能只带上了部分区域；分页后每页的表头重复设置和本地不一致。
解决：不要只依赖冻结，打印标题和表头重复要单独设；隔行色的条件格式应用区域要覆盖完整数据区，发布前在预览里翻到第二页看颜色是否连续；发布后不要只看第一屏，滚动到中间和最后一页各看一次。冻结丢失不算故障，但表头重复没设就是交付问题。我一般发布后做一次“翻页检查”：第一页、中间页、最后一页各截一张图，对比表头和隔行色，确认没有跳变。
6. 装完怎么验证跑通：三张检查表和一次全流程回放
装完不要急着交付，先按三张检查表走一遍。第一张是环境表：Excel 位数、插件位数、插件与服务端代际、工作簿后缀，四项全对才算环境通过。第二张是宏表：宏管理里能看到宏、保存后重新打开还在、点刷新能触发、校验不通过能拦住，四项全过才算宏链路通。第三张是样式表：冻结位置、打印标题、隔行色覆盖区域、列宽自适应最后一列，四项都肉眼确认过才算样式通过。
| 检查表 | 检查项 | 通过标准 |
|---|---|---|
| 环境 | Excel/插件位数、版本代际、.xlsm | 四项一致，无禁用项 |
| 宏 | 宏存在、可保存、可触发、可拦截 | 三种日期场景都符合预期 |
| 样式 | 冻结、打印标题、隔行色、列宽 | 预览翻页无跳变 |
最后做一次全流程回放：新建空白工作簿→登录→引用模板→另存为.xlsm→页面设置→隔行色→列宽自适应→新建日期校验宏→参数排版→预览→发布→翻页检查。回放时不要跳步，尤其不要先写宏再改模板，顺序反了很容易把宏挂到旧报表上。回放通过后，把工作簿、参数说明和检查结果放在同一个目录，下次复用直接拿这一份，比重新配一遍稳。
从那以后我每次交付前都强制走一遍这个回放，宁可多花十分钟，也不让同事在 Excel 里猜。希望帮到你。
本文还有配套的精品资源，点击获取
