跳到主要内容

ImageViewer 工具栏优化（DES-130）

版本： 0.3.1 · 类型： 🐛 缺陷修复

问题​

ImageViewer 底部工具栏存在三处可优化点：

  1. 单图仍显示导航：单图（或空列表）时，上一张 / 下一张按钮仍渲染、仅置灰禁用，对用户是无意义的占位。
  2. 禁用图标光标不对：到边界禁用时，hover 图标区域光标仍是 pointer，未变成 not-allowed。
  3. 缩放无障碍缺失：放大 / 缩小仅有 aria-label，缩放级别变化对屏幕阅读器不可感知。

根因（问题 2）​

按钮文字色 disabled:text-(--Labels-Disabled) 本身生效（经 currentColor 被图标正确继承，颜色无问题）；光标失效是因为注入的图标 SVG 自带 cursor-pointer（如 design-site IconSvg 的 ICON_BASE_CLASS），其选择器盖过了 button 的 disabled:cursor-not-allowed。已在真实浏览器验证：.btn:disabled svg { cursor: not-allowed }（特异性 0,2,1）可覆盖图标的 .cursor-pointer（0,1,0）。

改动文件​

  • packages/design/src/components/ImageViewer/ImageViewer.tsx
  • packages/design/src/components/ImageViewer/styles.ts
  • packages/design/src/components/ImageViewer/__tests__/ImageViewer.test.tsx
  • packages/design/src/components/ImageViewer/ImageViewerDesignSpec.md
  • packages/design-site/docs/components/patterns/image-viewer.mdx（中文 i18n 同步）

改动内容​

  • 单图隐藏导航：新增 showNav = total > 1 派生状态，仅在多图时渲染上一张 / 下一张及其后分隔线；单图工具栏收敛为 [缩小] [放大] | [删除]* | [导出] | [收起]。
  • 禁用图标光标：IMAGE_VIEWER_TOOLBAR_BUTTON_CLASS 追加 disabled:[&_svg]:cursor-not-allowed，禁用态显式把图标 SVG 光标改回 not-allowed，不依赖注入图标实现细节。
  • 缩放无障碍：新增 role="status" aria-live="polite" 的 visually-hidden 区域，缩放变化时播报当前百分比（Zoomed to 150%）。
  • 键盘缩放：handleKeyDown 补充 + / = 放大、- 缩小（此前只接 ← / →，键盘无法缩放），到边界由 zoomIn / zoomOut 自身收敛不越界；带 Cmd / Ctrl 的 + / - 放行不拦截，避免劫持浏览器原生页面缩放（保留低视力用户的页面缩放可达性）。
  • 补充单测：单图隐藏 / 多图显示导航、禁用按钮含 disabled:[&_svg]:cursor-not-allowed、缩放 live region 播报百分比、带 Cmd / Ctrl 的 + / - 不接管缩放。
  • DesignSpec 与文档站「单图」章节同步为「隐藏导航」，并补充缩放播报与禁用图标光标说明。

备注​

  • pnpm test:run 1151 通过
  • pnpm lint（含 tsc）通过

Linear：