2026-04-18-19-23-31 - 追加经验记录32：视频空白修复与占位符自适应

工程分析/经验记录.md

@@ -971,3 +971,33 @@ if ((settings.autoInsertDelay || 0) > 0) {
 - 当为 `image-placeholder` 修改填充后的样式行为时，必须同步检索所有填充入口（`fillPlaceholderSrc`、`fillPlaceholder`、自动帧插入、拖拽填充等），并同步到 `TemplateManage.tsx`。
 - 右侧表单字段容器样式如果统一（如高亮背景），应在所有字段类型的渲染分支中同步添加，避免某些类型遗漏。
 - 默认模板修改后应通过「新建报告 → 检查 DOM 结构」快速验证。
+
+---
+
+## 记录 32：视频分析模块空白修复与图片占位符自适应逻辑重构
+
+**A. 具体问题**
+1. 上一轮优化中将「上传视频」按钮移入了 `videos.length > 0` 条件渲染内部，导致无视频时整个「视频分析」面板空白，用户无法上传第一个视频。
+2. 图片占位符填充后仅将 `height` 设为 `auto`，但宽度仍保持预设值（如 200px），导致图片周围有大量空白，用户希望占位符能紧缩包围图片。
+
+**B. 产生问题原因**
+1. **视频按钮位置错误**：重构视频面板时，将上传按钮和缩略图列表全部包裹在 `{videos.length > 0 && (...)}` 中，未意识到上传按钮必须始终可见。
+2. **占位符尺寸逻辑不完整**：此前仅将 `height` 改为 `auto`，未同步处理 `width`，也未利用 `max-width`/`max-height` 作为硬限制来实现等比例缩放。
+
+**C. 解决问题方案**
+1. **修复视频面板**：将上传按钮和缩略图列表移出 `videos.length > 0` 条件，使其始终渲染；仅保留视频播放器和关键帧网格在 `{currentVideoIndex !== -1 && videos.length > 0 && (...)}` 中条件渲染。注意：移出后需同步删除对应的 `</div>)}` 关闭标签，否则会导致 JSX 结构不匹配（esbuild 报错「Unexpected closing tag」）。
+2. **重构占位符尺寸逻辑**：
+   - **插入时**：在 `placeholderModal` 确认插入的 `styleStr` 中，为 inline-block 占位符追加 `max-width:${w}px;max-height:${h}px;`（表格内占位符原本就有）。
+   - **填充时**：在 `fillPlaceholderSrc`、`fillPlaceholder`、`autoCaptureFrames`（ReportEditor）和 `fillPlaceholderSrc`（TemplateManage）中统一执行以下步骤：
+     - 读取 `placeholder.style.maxWidth || placeholder.style.width` 和 `placeholder.style.maxHeight || placeholder.style.height` 作为硬限制值 `mw` / `mh`
+     - 将 `<img>` 的 style 设为 `max-width:${mw};max-height:${mh};display:block;object-fit:contain;object-position:left top;`
+     - 将占位符外壳设为 `width:auto;height:auto;line-height:normal;max-width:${mw};max-height:${mh};text-align:left;vertical-align:top;justify-content:flex-start;align-items:flex-start;`
+   - 这样，小图片会 shrink-wrap 到实际尺寸，大图片会等比例缩小到限制范围内，且靠左上方放置。
+
+**D. 后续如何避免问题**
+- 重构条件渲染的 JSX 结构时，必须仔细核对打开和关闭标签的数量和层级。建议使用编辑器格式化或 build 工具（如 esbuild）立即验证。
+- `image-placeholder` 的尺寸逻辑涉及「创建时预设」和「填充后自适应」两个阶段，修改时必须同时考虑：
+  - 创建时是否写入了 `max-width`/`max-height`
+  - 填充时是否正确读取并应用这些限制值
+  - 所有填充入口（本地上传、签名插入、系统素材、自动帧插入、拖拽填充）是否同步更新
+- 默认模板中的占位符如果没有 `max-width`/`max-height`，回退逻辑 `|| placeholder.style.width` 仍能正确获取限制值，但后续修改默认模板时应注意统一添加 `max-width`/`max-height` 以显式声明意图。