39 lines
2.8 KiB
Markdown
39 lines
2.8 KiB
Markdown
|
# Luckysheet 全屏首次加载异常（问题清单与修复 Checklist）
|
|||
|
|
|
|||
|
|
## 现象（用户反馈）
|
|||
|
|
- 全屏打开在线表格时，前 1～2 次渲染不完整：Luckysheet 工具栏/公式栏缺失或布局异常；刷新后再打开才恢复正常。
|
|||
|
|
- DevTools 的 Sources/页面树里看不到预期的 `/luckysheet/*` 静态资源（怀疑资源未加载或加载顺序异常）。
|
|||
|
|
|
|||
|
|
## 目标
|
|||
|
|
- 全屏首次打开就稳定显示完整 Luckysheet UI（工具栏、公式栏、sheetbar 等）。
|
|||
|
|
- 资源加载可观测（能确认 JS/CSS 确实加载完成）。
|
|||
|
|
- 不破坏现有 Convex 数据读写链路（`/api/tables/*` -> Convex query/mutation）。
|
|||
|
|
|
|||
|
|
## Checklist（按优先级）
|
|||
|
|
### A. 资源加载与初始化时序（高优先级）
|
|||
|
|
- [ ] 确认 Luckysheet CSS 与 JS 都已加载完成，再允许 `create()`（避免“JS ready 但 CSS 未 ready”导致的高度/布局计算错误）。
|
|||
|
|
- [ ] 首次创建后触发一次 `resize`（部分情况下 Luckysheet 需要通过 resize 重新计算 UI 布局）。
|
|||
|
|
- [ ] 记录/暴露资源清单（仅 dev）：便于确认当前页面是否完成注入与版本号是否一致。
|
|||
|
|
|
|||
|
|
### B. 全屏容器可见性与布局（高优先级）
|
|||
|
|
- [ ] Luckysheet `create()` 时容器必须“已占位且可计算尺寸”（不要在 `display:none` 的容器里初始化）。
|
|||
|
|
- [ ] Loading/Error 采用绝对定位遮罩，避免通过隐藏容器实现 loading（防止尺寸为 0 导致布局计算异常）。
|
|||
|
|
|
|||
|
|
### C. 与 Convex 数据链路的时序（中优先级）
|
|||
|
|
- [ ] 表格数据（snapshot/schema/title）获取完成后再创建实例，避免多次 create/destroy 抖动。
|
|||
|
|
- [ ] 保存/同步触发频率可控（debounce），避免高频 mutation 导致卡顿（尤其在外网高延迟场景）。
|
|||
|
|
|
|||
|
|
### D. 观测与回归（中优先级）
|
|||
|
|
- [ ] 在控制台输出关键阶段日志（仅 dev）：`资源加载完成` / `create` / `destroy` / `resize`。
|
|||
|
|
- [ ] 复现用例：首次全屏打开（冷启动）、关闭后再开、刷新后再开、嵌入 iframe 与全屏互不影响。
|
|||
|
|
|
|||
|
|
## 已实施修复（对应 A/B）
|
|||
|
|
- `wolai-frontend/src/components/online-table/useLuckysheetLoader.ts`：CSS 注入改为等待 `onload`，并与 JS 一起作为 ready 条件；dev 下暴露 `window.__wolaiLuckysheetResources` 便于排查。
|
|||
|
|
- `wolai-frontend/src/components/online-table/FullScreenTableEditor.tsx`：容器始终占位 + overlay 遮罩；`create()` 后触发 `resize`（含兜底调用 `luckysheet.resize?.()`）。
|
|||
|
|
|
|||
|
|
## 验证步骤（建议）
|
|||
|
|
1. 冷启动后打开含在线表格的文档，点击“全屏编辑”，观察工具栏/公式栏是否一次成功显示。
|
|||
|
|
2. 打开 DevTools -> Network / Sources，确认首次打开会请求 `/luckysheet/*`，且 CSS/JS 不报错。
|
|||
|
|
3. 控制台查看 `window.__wolaiLuckysheetResources`（dev 模式）是否存在，以及资源路径版本号是否一致。
|
|||
|
|
|