From c7fe531b16a243f8e59d4b9106b5eba56be9b556 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= <kvtodev@outlook.com>
Date: Sat, 12 Sep 2026 16:30:53 +0800
Subject: [PATCH] =?UTF-8?q?=E6=81=A2=E5=A4=8D=E9=A2=84=E8=A7=88=E7=99=BE?=
 =?UTF-8?q?=E5=88=86=E6=AF=94=E6=8C=89=E9=92=AE=E9=80=82=E9=85=8D=E7=94=BB?=
 =?UTF-8?q?=E5=B8=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

将缩放百分比显示改为可点击的适配画布按钮
复用工具栏按钮的鼠标焦点处理并按当前容器重新计算视口
补充预览缩放组件回归测试并同步交互设计文档
---
 .../components/preview/PreviewWorkspace.tsx   | 29 ++++++++++++++++---
 .../tests/previewWorkspaceZoom.test.tsx       | 15 ++++++++++
 ...【交互设计】预览画布缩放滑杆-2026-09-05.md |  4 +--
 3 files changed, 42 insertions(+), 6 deletions(-)

diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/PreviewWorkspace.tsx b/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/PreviewWorkspace.tsx
index 8fbc37dbb..8ec753d09 100644
--- a/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/PreviewWorkspace.tsx
+++ b/apps/ai-game-creator-shell/src/view/ui-editor/components/preview/PreviewWorkspace.tsx
@@ -141,6 +141,25 @@ export function PreviewWorkspace({
     setViewportState(next);
   }, []);
 
+  const fitToCanvas = useCallback(() => {
+    if (!logicalSize) return;
+    const element = viewportElementRef.current;
+    setViewport(
+      fitViewportToBounds({
+        bounds: {
+          x: 0,
+          y: 0,
+          width: logicalSize.width,
+          height: logicalSize.height,
+        },
+        canvasSize: {
+          width: element?.clientWidth || canvasSizeRef.current.width,
+          height: element?.clientHeight || canvasSizeRef.current.height,
+        },
+      }),
+    );
+  }, [logicalSize, setViewport]);
+
   useEffect(() => {
     if (!activeImageId || !logicalSize) return;
     const element = viewportElementRef.current;
@@ -548,12 +567,14 @@ export function PreviewWorkspace({
                 zoomToDisplayScale(Number(event.target.value) / 100)
               }
             />
-            <output
-              className="min-w-14 rounded px-1 py-1 text-center text-[10px] tabular-nums"
-              aria-label={`当前画布缩放 ${displayPercent}`}
+            <button
+              type="button"
+              className="min-w-14 rounded px-1 py-1 text-center text-[10px] tabular-nums hover:bg-black/5"
+              aria-label="适配画布"
+              onClick={fitToCanvas}
             >
               {displayPercent}
-            </output>
+            </button>
             <button
               type="button"
               className="grid size-8 place-items-center rounded hover:bg-black/5"
diff --git a/apps/ai-game-creator-shell/tests/previewWorkspaceZoom.test.tsx b/apps/ai-game-creator-shell/tests/previewWorkspaceZoom.test.tsx
index 6c5f15eb4..92abe5778 100644
--- a/apps/ai-game-creator-shell/tests/previewWorkspaceZoom.test.tsx
+++ b/apps/ai-game-creator-shell/tests/previewWorkspaceZoom.test.tsx
@@ -179,6 +179,21 @@ describe('PreviewWorkspace quick zoom', () => {
     expect(logicalViewportScale(rendered.container)).toBe(1);
   });
 
+  it('refits the preview when the zoom percentage button is clicked', () => {
+    const rendered = render(<PreviewWorkspace canvas={createCanvas()} />);
+    const fitButton = screen.getByRole('button', { name: '适配画布' });
+    const zoomInButton = screen.getByRole('button', { name: '放大画布' });
+    const initial = logicalViewportScale(rendered.container);
+
+    fireEvent.click(zoomInButton);
+    expect(logicalViewportScale(rendered.container)).toBeCloseTo(
+      initial * 1.16,
+    );
+
+    fireEvent.click(fitButton);
+    expect(logicalViewportScale(rendered.container)).toBeCloseTo(initial);
+  });
+
   it('leaves browser zoom untouched when the preview has no content', () => {
     render(
       <PreviewWorkspace
diff --git a/docs/【交互设计】预览画布缩放滑杆-2026-09-05.md b/docs/【交互设计】预览画布缩放滑杆-2026-09-05.md
index 497fb7e85..5d35bf013 100644
--- a/docs/【交互设计】预览画布缩放滑杆-2026-09-05.md
+++ b/docs/【交互设计】预览画布缩放滑杆-2026-09-05.md
@@ -10,8 +10,8 @@
 - 滑杆位于预览区右下角固定工具栏；不提供移动端或窄窗口 fallback。
 - 保留 `−` 与 `+` 按钮。点击轨道可跳转，拖动滑块实时更新画布和百分比。
 - 缩放以视口中心为中心，继续支持 Ctrl/Cmd + 滚轮缩放。
-- 滑杆支持方向键、Home、End；百分比文本可点击编辑并在失焦时限制到有效范围。
-- 百分比文本使用数字输入框呈现；输入提交后同步视口缩放，适配画布保持独立按钮，点击百分比不会触发适配。
+- 滑杆支持方向键、Home、End；百分比按钮可通过键盘聚焦和激活。
+- 百分比使用只读按钮呈现；点击百分比按钮重新适配画布，滑杆仍只负责调整当前视口缩放。
 - 缩放滑杆获得焦点时，Delete/Backspace 不触发 UI 节点快捷删除；缩放按钮鼠标点击不改变快捷键焦点。
 - Windows/Linux 使用 `Ctrl`，macOS 使用 `Cmd`；`+`、`=` 与 `NumpadAdd` 放大，`-` 与 `NumpadSubtract` 缩小，允许按键重复时连续缩放。
 - 快捷键直接复用现有 `+`/`−` 按钮动作：以视口中心为锚点，按 `×1.16`/`×0.86` 改变缩放。