简介：《Smartbi报表设置文档》面向使用 Smartbi 制作电子表格报表的开发、实施与数据分析人员，聚焦报表从模板引用到预览发布的完整设置流程，帮助解决版式不统一、列宽难调、参数校验缺失等常见问题。包内为 1 个 docx 文档，压缩包约 1.05MB，内容以操作说明配代码片段为主，便于按章节查阅与复用。文档围绕引用模板、页面设置、隔行不同颜色、列宽自适应、参数设置与排版、预览发布展开，并给出 autoFitColumns 自适应列宽、开始/结束日期先后及 90 天跨度校验等宏示例，同时提示冻结行、筛选项居左、每行参数数量控制等排版细节。读者可据此完成模板样式搭建、页面布局调整、条件格式隔行着色、列宽自动适配、参数联动校验与最终预览发布，减少反复试错。已有 1305 人学习，适合需要快速掌握 Smartbi 报表设置规范、对照调试脚本、沉淀模板素材或查漏补缺的初中级用户参考。
1. 拿到一份 Smartbi 报表设置文档，先别急着打开 Excel
报表交上去那天，业务在浏览器里点开一看：标题被截掉半个字，日期列挤成一串井号，开始日期能选得比结束日期还晚，往下滚两屏表头就找不着了。回头翻这份 Smartbi 报表设置文档，七步一步没落，问题全出在“做了”和“做对”之间。这份文档记的是 Smartbi 电子表格报表在 Excel 插件端的完整设置链路：引用模板、页面设置、隔行变色、列宽自适应宏、日期参数校验宏、参数排版、预览发布。它适合刚接手电子表格报表的实施人员、要把模板移交给同事的开发者，以及被列宽和日期参数反复折腾过的熟手。下面按我实际复现的顺序拆，代码可以直接抄，参数怎么改、哪里会翻车，一并说清。
2. 模板引用与页面设置：把报表骨架钉死的四个动作
2.1 从 Smartbi 页签引用模板，而不是本地新建工作簿
最容易省事也最容易翻车的一步，就是本地新建一个 xlsx，画好样式再传上去。这样做出来的表在本地看着挺齐整，一发布就露馅：数据集绑定没了、参数定义丢了、扩展属性对不上，最后变成一张静态表格，点查询毫无反应。模板文件本身承载的不只是单元格样式，还有数据集字段映射、参数对象、单元格扩展方向这些元数据，本地新建的工作簿拿不到这些信息。
正确路径是从插件侧走：Excel 打开后切到 Smartbi 页签，先登录，再点模板，在目录树里选中目标模板打开，然后在这份已经绑定好数据集的模板上改样式。操作顺序不能反——先登录后打开模板，中途登录态过期再点模板，经常出现打开的是只读副本或者干脆空白页。我一般会在打开模板后先做一次轻量刷新，确认数据集能取到数、参数面板能渲染出来，再动样式。这一步多花两分钟，能省掉后面半小时的“为什么预览没数据”。
还有一种情况是多人协作。模板被别人占用时打开的是只读版本，这时候改样式保存不了，界面上不一定有很明显的提示。判断办法很简单：改一个单元格底色，按保存，如果没有任何反馈或者提示无权限，就是只读状态，先让对方释放，别硬改。
2.2 页面设置：冻结 1-5 行背后的行号账
这份文档里特意标了一句“第一行是空白行，所以上面报表冻结的是 1-5 行”。这句话看着像备注，其实是整张表最容易算错的地方。冻结行数是从工作表第一行开始数，不是从数据区第一行开始数。你在第 1 行留了空白做标题占位，那这行空白也计入冻结范围，数据表头实际落在第 5 行，冻结就得填 5，填 4 就会把表头最后一行甩到滚动区外面去。
冻结是在页面设置里配的，不是在 Excel 里点“冻结窗格”。本地冻结窗格只影响你在 Excel 里看，浏览器预览时完全不认，很多人就是在这里对不上。改完冻结行数必须走一次预览，滚动到第二屏看一眼表头还在不在，这是唯一可靠的验证方式。
首行留白这件事还有连带影响。空白行参与冻结，就意味着它的行高会一直占着顶部空间，行高设成默认值，浏览器里顶部会空出一大条；设得太小，标题又贴边。常见做法是把这一行行高调到 20 到 30 之间，标题放在合并单元格里居中，视觉上刚好。另外打印区域和缩放比例也要在这一步一起定，页面设置里的缩放填了 80%，浏览器端不生效但导出打印生效，两边不一致的时候人很容易懵。
2.3 隔行不同颜色：用条件格式，别手刷底色
给数据区做斑马线，最原始的做法是一行一行刷底色，或者刷两行再用格式刷拖。这个做法在模板阶段看不出问题，一旦报表有动态扩展行、有分组小计、有人中途插行，底色立刻错位，变成“隔一行变色、隔三行又变色”的花表。更麻烦的是导出，手刷的底色跟着单元格走，不会跟着数据行走。
常规做法是用条件格式配公式。数据区从第 6 行开始时，选中整个数据区，新建规则，选“使用公式确定要设置格式的单元格”，填入：
=MOD(ROW()-6,2)=0这个公式的意思是：当前行号减 6（数据区起始行偏移），对 2 取余为 0 的行填底色。减 6 是为了让第一条数据落在“有底色”还是“无底色”上符合预期，偏移量填错，斑马线就从表头开始错。如果表头也被一起选中了，偏移量还要再调。
用条件格式有两个实际好处：扩展出来的新行会自动继承规则，导出时按行号重新计算，不会出现底色错行。需要注意的边界是合并单元格和分组小计行，条件格式对合并区域只按左上角单元格的行号判断，小计行如果被合并了，底色可能整段连成一片。遇到这种情况，我会把数据区和合计区拆成两个条件格式规则，各自独立管理，别指望一条规则管到底。
2.4 骨架定稿前的自检项
样式改完不要直接进下一步，先过一遍下面这张表。这几项错了，后面列宽和参数做得再好也救不回来。
| 检查项 | 判定标准 | 出错后果 |
|---|---|---|
| 模板来源 | 从 Smartbi 页签打开，非本地新建 | 数据集和参数丢失，报表变静态 |
| 首行留白 | 行高 20-30，标题居中 | 顶部空一大条或标题贴边 |
| 冻结行数 | 与表头最后一行行号一致 | 滚动后表头错位或消失 |
| 隔行变色 | 条件格式公式，偏移量正确 | 扩展行后底色错乱 |
| 打印区域 | 覆盖数据区，不含空白行 | 导出多页空白 |
| 参数面板 | 已能正常渲染 | 后续宏取不到参数值 |
这张表我一般会贴在模板备注里，交接的时候对方照着过一遍，比口头讲十分钟管用。
3. 列宽自适应：main 宏的两种粒度和调用时机
3.1 autoFitColumns 和 autoFitColumn：粒度选错，效果全废
电子表格报表最难看的不是数据错，是列宽。字段名短、内容长，默认列宽一律按表头撑，结果金额列显示成“####”，备注列又空出一大片。Smartbi 提供的自适应接口有两个粒度：一个按列区间批量自适应，一个只对单列生效。
什么时候用批量：列数固定、字段长短差异大、整张表都要跟着内容走，比如明细表、宽表。什么时候用单列：表里有几列必须固定宽度不能动，比如序号列、操作列、勾选框列，这些列一旦被内容撑开，版面立刻散架。常见误用是全程只调单列，一列一列写十几行autoFitColumn(0)、autoFitColumn(1)，列数一变就得改代码，维护成本极高。
参数上要记住一个点：列索引从 0 开始，第一列是 0 不是 1。这个偏移在 JavaScript 里很常见，但配置类工具用惯了的同学容易顺手写成 1，结果就是第一列永远不自适应。批量方法的两个参数是起始列和结束列，结束列传的是最大显示区域的列数，而不是“最后一列的索引”，两者差 1，实际表现上末列可能没被撑开，遇到这种情况把结束值加 1 再试一次，多试一次比对着文档抠定义快。
3.2 通用宏代码与逐行说明
这份文档给的是一段通用宏，挂在报表的宏管理里，刷新时执行：
function main(spreadsheetReport) { // 取第一张工作表，电子表格报表默认只有一张 var sheet = spreadsheetReport.workbook.worksheets.get(0); // 空表直接返回，避免后续取属性报错 if (sheet === "" || sheet === null) { return; } // 最大显示区域的列数，随数据扩展动态变化 var counts = sheet.cells.maxDisplayRange.columnCount; // 从第 0 列到 counts 列整段自适应 sheet.autoFitColumns(0, counts); // 调试单列时启用下面这行，只对第 4 列生效（第一列为 0） // sheet.autoFitColumn(3); }逐段说清楚。第一行拿工作表对象，get(0)是下标写法，报表里如果做过 sheet 切换，这里取到的可能不是你以为的那张。第二行的空值判断别删，某些场景下报表初次加载时工作表还没就绪，直接往下走会抛异常，而这个异常在浏览器控制台里不一定显眼，表现就是“宏写了但没生效”。
第三行是关键。maxDisplayRange取的是当前最大显示区域，不是整张 sheet 的固定列数，所以数据扩展列数变多时counts会自动变大，自适应范围跟着变。这也意味着它依赖数据已经完成扩展，如果宏在数据展开之前就跑完了，counts拿到的是旧值，自适应范围偏小。第五行的批量调用是上线版本，第六行注释掉的单列调用是调试版本，两者切换靠注释，是这份文档里最实用的一个“土办法”。
3.3 全局设置和单列调试怎么来回切
文档里那句“下面列宽自适应可以全局设置，但是调试的时候可以单独设置”，翻译成操作就是：平时跑批量，改样式时切单列。
调试场景很具体。整张表自适应之后，某一列被撑得特别宽，把版面挤变形，你想知道是不是这列内容太长导致的。这时候把批量那行注释掉，放开对应的autoFitColumn(n)，跑一次预览，看这列单独撑开多宽。定位到是内容问题，就去改数据集里的字段截断或者换行；定位到不是这列，就换下一列。一列一列试虽然笨，但比对着整张表猜快得多。
调试完一定要切回批量版本再发布。这个动作我见过太多人忘，结果上线后只有某一列宽度正常，其余列全是默认宽度，看起来像“自适应没做”。习惯做法是在宏文件顶部加一行注释，写清当前是调试态还是发布态，交接时一眼能看出来。
3.4 自适应失效时的三个排查方向
第一个方向是宏根本没挂上。宏管理里新建了宏，但没保存，或者保存了没关联到当前报表，刷新时压根不执行。判断方式是在宏里临时加一行alert("run")，预览时弹不出来就是没挂上。
第二个方向是扩展时机。maxDisplayRange在数据未铺开时返回值偏小，自适应只处理了表头几列。解决办法是把自适应逻辑放在刷新完成后的回调里，或者干脆重跑一次刷新看结果是否正常。这个属于时序问题，光看代码看不出来，得实际操作复现。
第三个方向是单元格本身的问题。单元格里有硬回车、有合并单元格、有隐藏列，自适应结果都会异常：硬回车会把行高撑开而不是列宽，合并单元格的宽度归属有歧义，隐藏列不参与计算。排查时先把这几类单元格清掉，看是否恢复正常，再决定是改数据还是改版面。
4. 日期参数校验：重写 doRefresh 挡住跨 90 天的查询
4.1 校验位置：为什么必须挂在 doRefresh 上
需求很具体：结束日期不能早于开始日期，且两个日期的差值不能超过 90 天。文档里写的是“可选”，取决于报表参数里有没有开始日期和结束日期；有的话就加。
第一反应通常是给参数控件加事件，选完日期就校验。这条路走不通，因为用户完全可以直接点查询按钮，不触发控件事件；也有的场景是参数联动带出来的值，事件根本不会走。真正统一的入口只有一个：刷新。点查询、回车、参数联动、定时刷新，最终都收敛到doRefresh，把校验挂在这里，等于把所有入口都堵上了。
实现方式是重写，不是新增。先把原生的doRefresh存到一个自定义属性上，再用一个新函数替换它，校验通过后再调用存下来的原函数。这是典型的装饰器思路，好处是不侵入原有刷新逻辑，坏处是写错一行就会导致刷新彻底失效，所以下面每一行的作用都得弄清楚。
4.2 宏代码逐段拆解
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); }; }前三行的防重包装是整个宏里最不能省的部分。main在某些流程里会被执行多次，如果每次都无条件把当前doRefresh存进_jhy_doRefresh，第二次存进去的就是上一次包装过的函数，调用链越叠越长，表现是点一次查询转好几圈，或者直接栈溢出。加个存在性判断，保证原始函数只被捕获一次。
参数取值用了getParameterValue("参数名")，参数名必须和参数面板里显示的完全一致。文档里的写法带空格和后缀数字，这种命名在实际项目里很常见，手抄时少一个空格、少一个数字，取到的就是 null，replace直接抛异常，而这个异常往往被框架吞掉，用户侧表现是“校验没生效”。
4.3 日期格式、参数名和那个 100 毫秒
replace(/\-/g, "/")这一行不是可有可无的。不同运行环境对new Date("2024-01-01")的解析行为不一致，有的按 UTC 解析，有的直接返回 Invalid Date，换成斜杠形式兼容性更好。这一步不做，两个日期比较时可能得到NaN，而NaN参与任何比较都是 false，两条校验规则全部失效，且不会有任何报错。
100 毫秒的延迟是给遮罩留的时间。刷新被拦截时，页面上可能已经有加载遮罩在转，直接弹alert会被遮罩盖住或者阻塞渲染，用户看不到提示，以为点了没反应。放到定时器里，等遮罩这轮渲染过去再弹，提示能正常显示。这个值不用调大，100 够用，调到 500 反而有明显的迟滞感。
还有一个细节是规则二的计算式：1000 * 3600 * 24 * 90，毫秒乘以天数。这里用的是严格大于，等于 90 天是放行的，需求如果要“不超过 90 天”，边界值的处理要提前和业务确认清楚，差一天在月末报表里就是一行数据的差别。
4.4 校验通过后别把原刷新吞掉
最后一行this._jhy_doRefresh(fromButton, delayMask)是整段代码的收口。两个参数必须原样透传：fromButton标识这次刷新是不是按钮触发的，丢了它，某些按钮上的状态样式会不对；delayMask控制延迟遮罩，丢了它，刷新过程中的交互反馈会变。我见过为了图省事写成this._jhy_doRefresh()的，结果查询按钮上的 loading 状态永远不消失。
this的指向也要留意。这里是作为spreadsheetReport的方法被调用的，this指向报表对象，所以能取到_jhy_doRefresh。如果哪天把这段逻辑抽成独立函数再用普通函数调用，this就变成全局对象，直接报未定义。要抽就抽成箭头函数或者显式绑定，别留这个隐患。
5. 避坑与排查：五条翻车记录
5.1 现象：宏编辑器里点执行有反应，预览时毫无动静
现象：宏管理里写完代码，点执行能看到效果，一进浏览器预览，列宽还是原样，日期也能随便选。
原因：宏管理里的执行是本地调试态，只对当前打开的模板实例生效；预览走的是服务端发布后的报表，两边不是同一个执行环境。宏没保存、保存了没关联到报表、或者保存后模板没重新加载，都会出现“本地好、线上空”。
解决：改完宏先保存，再关掉模板重新打开一次，确认宏列表里能看到并且是启用状态，然后走预览。还是不生效，就在main第一行加一句alert("run")，预览时能弹出来说明宏挂上了，问题在逻辑里；弹不出来说明没挂上，回头查关联。
5.2 现象：列宽自适应之后，整张表被撑出横向滚动条
现象：本来一屏能看完的表，自适应后多出一条横向滚动条，得左右拖。
原因：批量自适应的范围包含了不该撑开的列，比如备注列里有一段长文本，自适应把它撑到几百像素，整表宽度超屏。也可能是结束列参数多传了一列，把右侧空白列一起算进去了。
解决：先切单列调试，逐列看哪一列被撑得最狠。定位到长文本列，改数据侧做截断或者固定列宽，不要让它参与自适应。结束列参数多传的情况，把范围收一位再试。
5.3 现象：日期校验第一次拦住了，改完参数再点就不拦了
现象：第一次选了个跨 100 天的区间，弹窗拦住了；第二次改成跨 120 天，直接放行，查询照跑。
原因：绝大多数是参数名对不上，getParameterValue返回 null，replace抛异常，异常被框架捕获后没有中断刷新流程。第一次能拦住，可能是当时参数值恰好有缓存。
解决：在取值前加判空，取不到值直接alert出参数名，先把名字对齐。参数面板里显示的“结束日期 2”中间那个空格，代码里一个字符都不能少。改完名之后同步改代码，别只改一边。
5.4 现象：点一次查询，页面刷新了两遍，加载圈转两圈
现象：加了校验宏之后，每次查询都能看到两次刷新动作，慢的时候很明显。
原因：包装逻辑被执行了多次，_jhy_doRefresh里存的已经不是原始函数，而是上一次包装后的函数，调用链叠了一层。常见触发场景是模板重载或者宏被重复注册。
解决：确保保存原始函数那段有存在性判断，只捕获一次。已经写错的，清掉宏重写一遍，别在旧代码上改，越改越乱。
5.5 现象：改了冻结行数，本地看着对，浏览器里还是错位
现象：页面设置里把冻结行数从 4 改成 5，Excel 里滚动正常，预览时表头还是被切掉一半。
原因：Excel 里的冻结窗格是本地视图设置，和报表的页面设置是两套东西。改了页面设置但没重新预览，或者改的是本地窗格而不是报表属性，都会出现这个现象。首行行高变化也会连带影响，行高改了没重新发布，冻结区的视觉高度对不上。
解决：只信页面设置里的值，改完必须重新预览并滚动验证。首行行高调整后同步再看一次，两处都对齐了才算完成。
6. 参数排版与发布验收：交付前我必走的三遍
6.1 参数排版：一行不超过六个，两行至少留两个
参数面板的排版原则文档里写得很克制：筛选项居左，一行不超过 6 个，如果排成两行，第二行至少保留 2 个。这三条背后是视觉密度问题。一行塞七八个参数，控件被压得很窄，日期选择器弹出来会盖住相邻控件；两行排布时第二行只剩一个孤零零的控件，左边一大片空白，看起来像少加载了什么。
我的做法是先按重要性分组，时间区间、组织维度、业务分类各成一组，组内按使用频率排。参数少于 6 个就单行排完，6 到 10 个拆两行，前一行放 5 到 6 个，后一行保底 3 个。超过 12 个就该考虑折叠或者分级了，硬排下去再好看也不好用。排完在浏览器里把窗口缩到 1280 宽度看一遍，这个宽度是很多办公场景的实际显示宽度，在这里不换行，基本就稳了。
6.2 发布前的验收清单
发布不是点一下按钮就完事，下面这几项我每次都会过一遍，顺序不乱：
| 验收项 | 操作 | 通过标准 |
|---|---|---|
| 模板来源 | 确认从 Smartbi 页签打开 | 数据集、参数齐全 |
| 冻结与表头 | 预览后滚动两屏 | 表头始终可见且不错行 |
| 列宽自适应 | 造一批长短差异大的数据 | 无横向滚动条，无井号 |
| 日期校验 | 故意选反、故意跨 100 天 | 两次都被拦，提示清晰 |
| 正常刷新 | 选合法区间点查询 | 只刷一次，数据正确 |
| 参数排版 | 1280 宽度下查看 | 不换行、不遮挡 |
| 导出打印 | 导出 Excel 和 PDF 各一份 | 底色不错行、无多余空白页 |
表格里最容易漏的是“正常刷新”这一项。校验宏写完，大家都在测拦截，没人测放行，结果透传参数写错，合法查询反而刷不出来。这一项必须单独测一次。
6.3 一个具体技巧：给宏加一行版本标记
宏代码里我习惯在第一行留一句注释，写清当前是发布态还是调试态、最近一次改动是什么：
// 发布态：批量自适应 + 日期校验 v2，改动需同步预览验证 function main(spreadsheetReport) { // ... }这行注释不影响执行，但交接的时候能救命。有一次同事拿到模板，看到注释掉的单列自适应，以为是被废弃的代码直接删了，结果发布后整表列宽全乱——那行是调试开关，删了批量那行也在注释状态。从那以后我每次改宏都强制走一遍“注释标记 + 保存 + 重开模板 + 预览滚动验证”的流程，一步不跳，宁可慢五分钟，也不要半夜被叫起来查报表。希望帮到你。
本文还有配套的精品资源，点击获取
