# PR #27068 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[diffusion] Polish realtime WebUI waiting state
- 合并时间：2026-06-03 14:29
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/27068

---

## 执行摘要

本 PR 针对 sglang-diffusion 的 Realtime WebUI 进行了视觉优化：移除了空闲状态下的装饰性 Canvas 绘制，将等待指示器从三点脉冲动画改为旋转进度环，并对齐了工具栏状态文本。同时更新了资源缓存版本号和测试断言以确保一致性。变更简单直接，无功能逻辑改动。

## 功能与动机

PR body 指出要“remove the decorative idle placeholder drawing from the realtime preview”、“replace the waiting dots with a small circular progress indicator”以及“align preview toolbar status text”。动机是减少不必要的 Canvas 绘制、简化 UI 并改进等待反馈的视觉品质。

## 实现拆解

1. **简化空闲绘制 **（`app.js` 的 `drawIdle` 函数）：删除渐变背景、边框和三点占位的 Canvas 绘图命令，仅保留纯色背景填充，使空闲画面更加干净，且减少了重绘开销。
2. **替换等待指示器动画 **（`styles.css`）：将 `.preview-loader` 从三点脉冲动画（`previewDotPulse`）改为旋转进度环（`previewProgressSpin`），通过 `border` + `border-top-color` + `rotate` 动画实现，视觉效果更现代。
3. **对齐工具栏状态文本 **（`styles.css`）：为 `#statusText`、`#chunkText`、`.stage-stat` 等元素设置 `line-height: 1`，并调整 `.stage-stat` 的 `align-items` 从 `baseline` 为 `center`，使文本在工具栏中垂直居中。
4. **更新资源版本和测试 **（`index.html`、`test_realtime_webui.py`）：将 CSS 和 JS 的查询字符串从 `v37` 更新为 `v38`；在测试中添加了对 `previewProgressSpin` 存在的断言和 `previewDotPulse` 不存在的断言，并同步了版本号断言。

### `python/sglang/multimodal_gen/apps/realtime_webui/app.js`

核心逻辑文件：移除了 drawIdle 中的装饰性绘制（渐变、边框、三点占位），只保留纯色填充，大幅简化空闲状态渲染。

```javascript
function drawIdle() {
  const w = 1280, h = 720;
  // 确保 Canvas 尺寸为 1280x720，如果不符合则调整
  if (canvas.width !== w || canvas.height !== h) {
    canvas.width = w;
    canvas.height = h;
  }
  setPreviewState("idle");          // 更新预览状态为 idle
  renderedPreviewFrames = 0;        // 重置渲染帧计数
  ctx.fillStyle = "#11140f";        // 固定深色背景，不再绘制装饰渐变、边框和占位点
  ctx.fillRect(0, 0, w, h);
}

```

### `python/sglang/multimodal_gen/apps/realtime_webui/styles.css`

样式文件：将等待指示器从三点脉冲动画改为旋转圆环动画，并调整工具栏状态文本行高以对齐。

```css
/* 原先的三点脉冲动画已被移除，现替换为旋转进度环 */
.preview-loader {
  width: 18px;
  height: 18px;
  border-radius: 50%;
  border: 2px solid rgba(238, 241, 236, 0.22);   /* 浅色边框 */
  border-top-color: rgba(238, 241, 236, 0.82);    /* 顶部颜色较亮，造成旋转效果 */
  animation: previewProgressSpin 0.8s linear infinite;  /* 匀速旋转动画 */
}

@keyframes previewProgressSpin {
  to {
    transform: rotate(360deg);
  }
}

```
（其他辅助变更：调整 `.topbar > *`、`.preview-scale-control p`、`#statusText`、`#chunkText`、`.stage-stat` 的 `line-height: 1` 和 `align-items: center` 以改善垂直对齐。）

## 评论区精华

本 PR 无任何 review 评论，由作者直接合并。

## 风险与影响

- **风险**：极低。仅涉及前端 UI 和测试断言，无后端逻辑变更。CSS 动画替换是视觉等价，空闲绘制简化不改变功能。版本号更新确保客户端缓存刷新，但若其他地方硬编码了旧版本号则需要一并更新，测试已对此做了断言。
- **影响**：直接影响实时 WebUI 用户的视觉体验，空闲界面更简洁，等待状态反馈更直观。对系统性能无负面影响，甚至因减少绘制而略微提升。团队维护需要保持前端代码与测试断言同步，本次已做到。

## 关联脉络

相关 PR #27080 也对实时 WebUI 测试框架进行了修改（修复 LingBot 实时一致性 GT pin），与本 PR 的测试变更属于同一测试模块。本 PR 进一步巩固了前端测试覆盖，体现了团队对实时 WebUI 质量的持续关注。