Skip to content

[ISSUE] xlsx 预览白屏:公式单元格的 numFmtId 落在 luckyexcel 内置 numFmtDefault 缺失区间(如 31)时,luckysheet 格式化器抛 TypeError: Cannot read properties of undefined (reading 'slice'),导致 loading 遮罩永不消失 #801

Open

Description

@hinlokchan

Issue Type / 问题类型

Bug / 缺陷

kkFileView Version / kkFileView 版本

5.2.0

Deployment Mode / 部署方式

jar

Environment / 环境信息

项 值
kkFileView 5.0.2(Spring Boot 3.5.6 / JDK 21)
OS Rocky Linux 10.2, x86_64
关键配置 office.type.web = web(xlsx 走纯浏览器端 luckysheet 预览,服务端不做转换)
相关资源 BOOT-INF/classes/static/xlsx/luckyexcel.umd.js(356146 B)、BOOT-INF/classes/static/xlsx/luckysheet.umd.js(3405107 B)
浏览器 Chrome,控制台报错见下

Steps to Reproduce / 复现步骤

打开某些 xlsx 时页面永久白屏:既不出表格,也不出错误提示,连"跳转 HTML 预览"按钮都不出现。文件大小无关(239 KB 即触发),换浏览器/清缓存无效。

luckysheet.umd.js:3261 Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'slice')
at Object.le [as format] (luckysheet.umd.js:3261:77048)
at vt (luckysheet.umd.js:3261:50114)
at Ct (luckysheet.umd.js:3261:83213)
at Object.buildGridData (luckysheet.umd.js:4066:75180)
at Object.loadOtherFile (luckysheet.umd.js:4066:82554)
...

luckysheet.umd.js:4278 Merge info is null -1 -1
luckysheet.umd.js:4336 Uncaught TypeError: Cannot read properties of undefined (reading '0') ← 点击未渲染的 canvas 引发的次生错误

Expected Result / 期望结果

Luckysheet渲染的表格页面

Actual Result / 实际结果

白屏

Logs & Screenshots / 日志与截图

根因:六步因果链
1. luckyexcel 的内置数字格式表 numFmtDefault 覆盖不全

luckyexcel.umd.js 中 numFmtDefault 常量实际只含这些 id:

code.txt
0,1,2,3,4,9,10,11,12,13,14,15,16,17,18,19,20,21,22,37,38,39,40,45,46,47,48,49
Excel 内置的 23–36、41–44、50+ 全部缺失。 其中 31 是内置的中文日期格式 yyyy"年"m"月"。

numfmts 表的构建在 luckyexcel.umd.js:3381-3392:

code.js
var numfmts = _this.readXml.getElementsByTagName("numFmt/numFmt", constant_1.stylesFile);
var numFmtDefaultC = JSON.parse(JSON.stringify(constant_1.numFmtDefault));
for (var i = 0; i < numfmts.length; i++) {
  var attrList = numfmts[i].attributeList;
  var numfmtid = method_1.getXmlAttibute(attrList, "numFmtId", "49");
  var formatcode = method_1.getXmlAttibute(attrList, "formatCode", "@");
  if (!(numfmtid in constant_1.numFmtDefault)) {
    numFmtDefaultC[numfmtid] = constant_1.numFmtDefaultMap[formatcode] || formatcode;
  }
}
_this.styles["numfmts"] = numFmtDefaultC;
即:工作簿 <numFmts> 里显式声明过的 id 会被补进表里;没声明、又不在 numFmtDefault 里的 id,就是 undefined。

2. 触发文件的 cellXf 解析出 numFmtId="31",而 <numFmts> 没有声明它

复现文件中 <numFmts count="26"> 声明的是 id 41–44 和 176–197,不含 31。有 9 个单元格使用该 xf,其中 3 个带公式:

code.xml
<!-- xl/worksheets/sheet10.xml(sheet11/12 同样) -->
<c r="E3" s="…"><f>项目信息及各类修正编辑表!D2</f><v>45455</v></c>
(45455 = Excel 序列日期 2024-06-08)

3. fa 被写成 undefined —— luckyexcel.umd.js:2735-2742

code.js
if (numFmtId != undefined) {
  var numf = numfmts[parseInt(numFmtId)];      // numfmts[31] === undefined
  var cellFormat = new LuckyBase_1.LuckySheetCellFormat();
  cellFormat.fa = method_1.escapeCharacter(numf);
  cellFormat.t = t || 'd';
  cellValue.ct = cellFormat;                    // ct = { fa: undefined, t: 'd' }
}
escapeCharacter 原样透传 undefined(luckyexcel.umd.js:6655):

code.js
function escapeCharacter(str) {
  if (str == null || str.length == 0) { return str; }   // ← 直接 return undefined
  return str.replace(/&amp;/g,"&")…;
}
结果:ct 对象存在,但 ct.fa === undefined。

4. luckysheet Ct() 的兜底判断覆盖不到这种情况 —— luckysheet.umd.js:3261 列 83212 附近

code.js
else if (a.f != null && z(o) && !/^\d{6}(18|19|20)?\d{2}(0[1-9]|1[12])(0[1-9]|[12]\d|3[01])\d{3}(\d|X)$/i.test(o))
  if (a.v = parseFloat(o), a.ct == null && (a.ct = {fa:"General", t:"n"}), a.v == Infinity || a.v == -Infinity) a.m = a.v.toString();
  else if (a.v.toString().indexOf("e") > -1) { … }
  else {
    let d = Math.round(a.v * 1e9) / 1e9;
    if (a.ct == null) { let f = ut(d); a.m = f[0].toString() }
    else { let f = vt(a.ct.fa, d); a.m = f.toString() }   // ← 列 83212,传入 undefined
  }
兜底只判 a.ct == null,不判 a.ct.fa == null。而同一函数稍后(列 83465)的兄弟调用点却是有防护的:

code.js
a.ct != null && a.ct.fa != null && a.ct.fa != "General"
——说明防护写法项目里本来就有,只是这一处漏了。

进入这个分支需要两个条件同时成立:单元格有公式(a.f != null) 且 缓存值是数字(z(o))。这解释了"为什么有的文件有公式也不崩"。

5. le() 开头没有 null 防护 —— luckysheet.umd.js:3261 列 76378

code.js
function le(V, U, te) {
  if (V === "拾元") { … }
  if (V.slice(0,1) === "^") return U == null ? null : U + V.slice(1, V.length);   // ← 列 77046/77048,V 为 undefined 直接抛
  te == null && (te = {});
  var me = "";
  switch (typeof V) { case "string": … case "number": … }
}
vt 只是转发(列 50114):function vt(e,n){ return bl.format(e,n) }。

→ TypeError: Cannot read properties of undefined (reading 'slice'),行列号与栈完全对应(3261:77048 ← le,3261:50114 ← vt,3261:83213 ← Ct)。

6. 异步抛出 ⇒ Promise 永不 settle ⇒ 遮罩永不撤 ⇒ 白屏

buildGridData(luckysheet.umd.js:4066 列 75180)由 loadOtherFile 调用,整条链在 luckysheet 的异步流程里。而 officeweb.ftl 的 createLuckysheet() 返回的 Promise 只有两种结局:workbookCreateAfter 钩子里 resolve,或同步 throw 时 reject。这里是不久后的异步 throw,两者都不触发:

Promise 永远 pending → hideLoading() 永远不执行
全屏 #loading-overlay(position:fixed; background:rgba(255,255,255,0.95); z-index:9999)一直盖着
#button-area(内含"跳转 HTML 预览"逃生按钮)保持 display:none
所以是纯白、无提示、无降级入口的死屏。

最小复现
任一 xlsx,满足:

xl/styles.xml 中某个 cellXfs/xf 的生效 numFmtId 是内置 id 且不在 numFmtDefault 里(例如 31),可以直接写在 xf 上,或经 xfId 从 cellStyleXfs 继承(继承路径见 luckyexcel.umd.js:2637-2650,applyNumberFormat == "0" 时走继承;2688-2701 无条件覆写);
该 <numFmts> 里没有声明这个 id;
使用该 xf 的某个单元格同时有 <f> 和数字型 <v>。
code.xml
<c r="E3" s="…"><f>Sheet2!D2</f><v>45455</v></c>
只满足 1+2 而无 3(无公式,或缓存值非数字)→ 不崩。

一行验证修复:在该工作簿 xl/styles.xml 的 <numFmts> 里补上声明(count 同步 +1):

code.xml
<numFmt numFmtId="31" formatCode="yyyy&quot;年&quot;m&quot;月&quot;"/>
补上后同一文件渲染完全正常(已实测确认)。这从反面证明了根因就是格式表查不到。

对照组证据
文件	公式	缺失的内置 id	结果
复现文件(239 KB,22 sheet / 2147 个 <f> / 196 个错误单元格 / 37 个 externalLink)	有	31,9 个单元格使用,其中 3 个带公式	白屏
对照 A(311 KB,3 sheet / 1426 个公式 / 24 个共享公式主单元)	有	57,4 个单元格使用,0 个带公式	正常
对照 B(340 KB)	0 个公式	无(只用 id 0 和 14,都在表内)	正常
对照 A 是决定性的:它有大量公式却正常,说明"有公式就崩"不成立,真正的条件是"公式 + 缓存数字值 + 查不到的 numFmtId"三者同时成立。

已排除的干扰假设(均为逐一实验/静态验证后否证)
为避免其他人重走弯路,以下都不是原因:

#REF! 公式、1143 个 definedName 中 994 个含 #REF! → 删除后仍白屏
共享公式孤儿(mainFunc.cellValue 空引用)→ 全文件扫描 0 个孤儿
共享公式从属单元缺 <v> → 0 个
37 个共享主单元缺 <v> → 全部 has_v=True
负偏移共享公式 → fromulaRef.error 有定义(luckyexcel.umd.js:6955,r:"#REF!"),updateparam 在 row<0||col<0 时优雅返回 #REF!(6823-6825),不抛
数组公式 / SUMPRODUCT / FIND / ISERROR / OR / ROW / TEXT / TODAY → 分别删除后全部仍白屏;且 SUMPRODUCT 实际有实现(luckysheet.umd.js:4348,大写方法名)并整体被 try/catch 包住,抛不出来
隐藏 sheet、错误单元格(t="e")、合并单元格、数据验证、externalLink、文件体积
"numFmt/numFmt" 路径拼写导致 numfmts 表为空 → 表其实是好的:getElementsByOneTag 的正则含标签名后的字面空格,二级匹配时每个 <numFmt .../> 字符串会与自身再匹配一次,实测 level1=26 / level2=26,与 <numFmts count> 一致
建议修复
上游(推荐,两处互补)
(a) luckysheet —— 给 le() 加 null 防护(治崩溃)

luckysheet.umd.js 的 format(栈中 Object.le [as format])开头:

code.js
if (V == null) return U == null ? "" : String(U);
(b) luckysheet —— 给 Ct() 列 83212 的调用点补上 fa 判空(对齐列 83465 已有写法)

code.js
else if (a.ct == null || a.ct.fa == null) { let f = ut(d); a.m = f[0].toString() }
else { let f = vt(a.ct.fa, d); a.m = f.toString() }
(c) luckyexcel —— 把 numFmtDefault 补全到 Excel 内置 0–58 全量(治根源)

至少补上 23–36、41–44、50–58;其中 31 = yyyy"年"m"月"、32 = h"时"mm"分"、33 = h"时"mm"分"ss"秒"、57/58 为中文日期变体。

(d) 兜底 —— escapeCharacter 不要把 undefined 透传成 fa

luckyexcel.umd.js:2736 处 numf == null 时应回落到 "General",而不是生成 {fa: undefined}。

另外:白屏本身应该有降级
即便渲染抛错,officeweb.ftl 的 Promise 也永不 settle,用户拿不到任何提示、也拿不到"跳转 HTML 预览"按钮。建议给 createLuckysheet() 加超时/window.onerror + unhandledrejection 兜底,失败时撤掉 #loading-overlay 并显示 #button-area。这一条独立于上面的格式表 bug,任何渲染期异步异常都会导致同样的死屏。

使用者侧临时规避(不改代码)
在源工作簿 styles.xml 的 <numFmts> 中显式声明所用格式(即最小复现里的一行);或把该单元格格式改成"常规"/表内已声明的格式;
或改 office.type.web = image(服务端出图,绕开 luckysheet,但影响所有 xlsx 且失去交互);
或预览 URL 上加 &officePreviewType=html,走服务端 HTML 转换。

Sample File / 样例文件(可选)

No response

Checklist / 提交前检查

  • I have searched existing issues and did not find a duplicate. / 我已搜索现有 issue,未发现重复问题
  • I can reproduce this issue on the stated version/environment. / 我可在上述版本与环境复现该问题
  • I have masked sensitive information in logs/screenshots. / 我已对日志与截图中的敏感信息做脱敏处理

Activity

  1. github-actions commented on Oct 12, 2026

    @github-actions

    @Copilot 请自动分诊并直接给出可执行建议(无需人工先介入):

    • 先判断类型:Bug / Performance / Security / Question / Feature
    • 检查 Issue 信息是否完整(版本、部署方式、复现步骤、日志)
    • 若信息不完整:请直接按模板列出缺失项并引导补充
    • 若信息较完整:请给出下一步排查建议与最小复现建议
    • 若判断为已知问题或已修复:请给出对应版本/修复方向

    Issue #801
    标题:[ISSUE] xlsx 预览白屏:公式单元格的 numFmtId 落在 luckyexcel 内置 numFmtDefault 缺失区间(如 31)时,luckysheet 格式化器抛 TypeError: Cannot read properties of undefined (reading 'slice'),导致 loading 遮罩永不消失
    链接:#801


    补充说明 / Support Notice:

    • GitHub Issues 会持续跟进处理 / We will continue to follow up through GitHub Issues.
    • 如为线上紧急问题,可通过知识星球渠道加速处理 / For urgent production issues, you can use our Knowledge Planet channel for faster processing:
      https://wx.zsxq.com/group/48844125114258
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    status/needs-infoWaiting for reporter feedback or reproduction details

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions