From c12d1ca42a175b07302f378a7626e4566bb8eddd Mon Sep 17 00:00:00 2001 From: DrSmoothl <1787882683@qq.com> Date: Thu, 5 Mar 2026 21:57:27 +0800 Subject: [PATCH] =?UTF-8?q?feat(a11y):=20add=20a11y=20infrastructure=20?= =?UTF-8?q?=E2=80=94=20skip-nav,=20announcer,=20touch=20CSS,=20eslint-jsx-?= =?UTF-8?q?a11y?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- dashboard/eslint.config.js | 5 + dashboard/package.json | 7 +- dashboard/src/components/ui/announcer.tsx | 83 +++++++++++++ dashboard/src/components/ui/skip-nav.tsx | 40 +++++++ .../src/components/ui/zoomable-chart.tsx | 90 ++++++++++++++ dashboard/src/i18n/locales/en.json | 11 +- dashboard/src/i18n/locales/ja.json | 11 +- dashboard/src/i18n/locales/ko.json | 11 +- dashboard/src/i18n/locales/zh.json | 11 +- dashboard/src/index.css | 112 +++++++++++++++++- dashboard/src/main.tsx | 34 +++--- 11 files changed, 372 insertions(+), 43 deletions(-) create mode 100644 dashboard/src/components/ui/announcer.tsx create mode 100644 dashboard/src/components/ui/skip-nav.tsx create mode 100644 dashboard/src/components/ui/zoomable-chart.tsx diff --git a/dashboard/eslint.config.js b/dashboard/eslint.config.js index 10d55647..f53da2d8 100644 --- a/dashboard/eslint.config.js +++ b/dashboard/eslint.config.js @@ -1,11 +1,13 @@ import js from '@eslint/js' import globals from 'globals' +import jsxA11y from 'eslint-plugin-jsx-a11y' import reactHooks from 'eslint-plugin-react-hooks' import reactRefresh from 'eslint-plugin-react-refresh' import tseslint from 'typescript-eslint' export default tseslint.config( { ignores: ['dist'] }, + jsxA11y.flatConfigs.recommended, { extends: [js.configs.recommended, ...tseslint.configs.recommended], files: ['**/*.{ts,tsx}'], @@ -30,6 +32,9 @@ export default tseslint.config( // 关闭或降级其他规则 '@typescript-eslint/no-explicit-any': 'warn', '@typescript-eslint/no-unused-vars': 'warn', + // jsx-a11y: 降级为 warn 避免阻塞构建，后续 Task 17 逐步修复 + 'jsx-a11y/anchor-ambiguous-text': 'warn', + 'jsx-a11y/no-autofocus': 'warn', }, }, ) diff --git a/dashboard/package.json b/dashboard/package.json index de2c8fd3..8b57e2db 100644 --- a/dashboard/package.json +++ b/dashboard/package.json @@ -154,7 +154,9 @@ "remark-gfm": "^4.0.1", "remark-math": "^6.0.0", "smol-toml": "^1.5.2", - "tailwind-merge": "^3.4.0" + "tailwind-merge": "^3.4.0", + "@react-spring/web": "^9.7.5", + "@use-gesture/react": "^10.3.1" }, "devDependencies": { "@eslint/js": "^9.39.1", @@ -184,6 +186,7 @@ "typescript": "~5.9.3", "typescript-eslint": "^8.49.0", "vite": "^7.2.7", - "vitest": "^4.0.18" + "vitest": "^4.0.18", + "eslint-plugin-jsx-a11y": "^6.10.2" } } diff --git a/dashboard/src/components/ui/announcer.tsx b/dashboard/src/components/ui/announcer.tsx new file mode 100644 index 00000000..9736da26 --- /dev/null +++ b/dashboard/src/components/ui/announcer.tsx @@ -0,0 +1,83 @@ +import type { ReactNode } from 'react' +import { createContext, useCallback, useContext, useRef, useState } from 'react' + +type Politeness = 'polite' | 'assertive' + +interface AnnouncerContextValue { + announce: (message: string, politeness?: Politeness) => void +} + +const AnnouncerContext = createContext(null) + +/** + * useAnnounce — 向屏幕阅读器播报消息 + * + * @example + * const announce = useAnnounce() + * announce('保存成功') // polite（默认） + * announce('操作失败，请重试', 'assertive') // assertive（立即打断） + */ +export function useAnnounce(): (message: string, politeness?: Politeness) => void { + const ctx = useContext(AnnouncerContext) + if (!ctx) { + // 未在 AnnouncerProvider 内时静默降级，不抛错 + return () => {} + } + return ctx.announce +} + +interface AnnouncerState { + polite: string + assertive: string +} + +/** + * AnnouncerProvider — 在应用根部挂载两个 aria-live 区域 + * + * 将此组件包裹在应用根节点，所有子组件即可通过 useAnnounce() 播报消息。 + * aria-live 区域视觉上隐藏（sr-only），不影响布局。 + */ +export function AnnouncerProvider({ children }: { children: ReactNode }) { + const [messages, setMessages] = useState({ polite: '', assertive: '' }) + // 用于清空 -> 重新设置，触发屏幕阅读器重新朗读相同消息 + const politeTimerRef = useRef | null>(null) + const assertiveTimerRef = useRef | null>(null) + + const announce = useCallback((message: string, politeness: Politeness = 'polite') => { + if (politeness === 'assertive') { + // 先清空，再填入，确保屏幕阅读器重新朗读 + setMessages((prev: AnnouncerState) => ({ ...prev, assertive: '' })) + if (assertiveTimerRef.current) clearTimeout(assertiveTimerRef.current) + assertiveTimerRef.current = setTimeout(() => { + setMessages((prev: AnnouncerState) => ({ ...prev, assertive: message })) + }, 50) + } else { + setMessages((prev: AnnouncerState) => ({ ...prev, polite: '' })) + if (politeTimerRef.current) clearTimeout(politeTimerRef.current) + politeTimerRef.current = setTimeout(() => { + setMessages((prev: AnnouncerState) => ({ ...prev, polite: message })) + }, 50) + } + }, []) + + return ( + + {children} + {/* aria-live 区域：视觉隐藏，屏幕阅读器可读 */} +
+ {messages.polite} +
+
+ {messages.assertive} +
+ + ) +} diff --git a/dashboard/src/components/ui/skip-nav.tsx b/dashboard/src/components/ui/skip-nav.tsx new file mode 100644 index 00000000..6bef78a4 --- /dev/null +++ b/dashboard/src/components/ui/skip-nav.tsx @@ -0,0 +1,40 @@ +import { useTranslation } from 'react-i18next' + +/** + * Skip-to-content 无障碍导航链接 + * + * 默认视觉上隐藏（sr-only），当键盘用户 Tab 聚焦时显示， + * 允许屏幕阅读器/键盘用户跳过重复的导航区域直达主内容。 + * + * 使用 focus-visible 而非 focus，鼠标点击不触发显示。 + */ +export function SkipNav() { + const { t } = useTranslation() + + return ( + + {t('a11y.skipToContent')} + + ) +} diff --git a/dashboard/src/components/ui/zoomable-chart.tsx b/dashboard/src/components/ui/zoomable-chart.tsx new file mode 100644 index 00000000..31c0a9c7 --- /dev/null +++ b/dashboard/src/components/ui/zoomable-chart.tsx @@ -0,0 +1,90 @@ +/** + * ZoomableChart — 支持 pinch-to-zoom 的图表容器（Task 8） + * + * 用法： + * + * + * ... + * + * + * + * 特性： + * - 支持 macOS 触控板双指缩放（wheel + ctrlKey） + * - 支持移动端/触屏双指 pinch-to-zoom + * - 缩放范围 0.5x – 4x，带 rubberband 效果 + * - 动画由 @react-spring/web 处理，不触发 React re-render + * - Must NOT: 不在 handler 内使用 useState + */ + +import { useRef } from 'react' +import { animated, useSpring } from '@react-spring/web' +import { usePinch } from '@use-gesture/react' + +import { cn } from '@/lib/utils' + +interface ZoomableChartProps { + children: React.ReactNode + className?: string + 'aria-label': string + minScale?: number + maxScale?: number +} + +export function ZoomableChart({ + children, + className, + 'aria-label': ariaLabel, + minScale = 0.5, + maxScale = 4, +}: ZoomableChartProps) { + const containerRef = useRef(null) + + const [style, api] = useSpring(() => ({ + scale: 1, + config: { tension: 300, friction: 40 }, + })) + + usePinch( + ({ offset: [scale], first, last }) => { + // Rubberband: 超出范围时有弹性阻力 + const clamped = Math.min(Math.max(scale, minScale * 0.85), maxScale * 1.15) + const rubberband = clamped < minScale + ? minScale + (clamped - minScale) * 0.3 + : clamped > maxScale + ? maxScale + (clamped - maxScale) * 0.3 + : clamped + + api.start({ scale: rubberband, immediate: first }) + + // 松手后弹回范围内 + if (last && (scale < minScale || scale > maxScale)) { + api.start({ + scale: Math.min(Math.max(scale, minScale), maxScale), + config: { tension: 200, friction: 30 }, + }) + } + }, + { + target: containerRef, + scaleBounds: { min: minScale * 0.85, max: maxScale * 1.15 }, + rubberband: true, + // 阻止浏览器默认的页面缩放 + preventDefault: true, + eventOptions: { passive: false }, + } + ) + + return ( +
+ + {children} + +
+ ) +} diff --git a/dashboard/src/i18n/locales/en.json b/dashboard/src/i18n/locales/en.json index 4f0c7add..e9cbb69f 100644 --- a/dashboard/src/i18n/locales/en.json +++ b/dashboard/src/i18n/locales/en.json @@ -468,10 +468,9 @@ "settingsDesc": "Configure system settings" } }, - "httpWarning": { - "title": "Security Warning:", - "message": "You are accessing MaiBot WebUI via HTTP", - "description": "If this is a public server, your data (including Token, chat history, etc.) may be intercepted in transit. It is strongly recommended to use HTTPS or access only from a local network.", - "dismiss": "Dismiss warning" -} + "a11y": { + "skipToContent": "Skip to main content", + "sidebarNav": "Main navigation", + "closeMenu": "Close menu", + "navigatedTo": "Navigated to {{page}}" } diff --git a/dashboard/src/i18n/locales/ja.json b/dashboard/src/i18n/locales/ja.json index fbaa3627..9d8f218d 100644 --- a/dashboard/src/i18n/locales/ja.json +++ b/dashboard/src/i18n/locales/ja.json @@ -468,10 +468,9 @@ "settingsDesc": "システム設定を構成" } }, - "httpWarning": { - "title": "セキュリティ警告：", - "message": "HTTP で MaiBot WebUI にアクセスしています", - "description": "これが公開サーバーの場合、データ（Token、チャット履歴など）が転送中に傍受される可能性があります。HTTPS を使用するか、ローカルネットワークからのみアクセスすることを強くお勧めします。", - "dismiss": "警告を閉じる" -} + "a11y": { + "skipToContent": "メインコンテンツにスキップ", + "sidebarNav": "メインナビゲーション", + "closeMenu": "メニューを閉じる", + "navigatedTo": "{{page}} に移動しました" } diff --git a/dashboard/src/i18n/locales/ko.json b/dashboard/src/i18n/locales/ko.json index ec2f3c57..f793c06a 100644 --- a/dashboard/src/i18n/locales/ko.json +++ b/dashboard/src/i18n/locales/ko.json @@ -468,10 +468,9 @@ "settingsDesc": "시스템 설정 구성" } }, - "httpWarning": { - "title": "보안 경고:", - "message": "HTTP를 통해 MaiBot WebUI에 접속하고 있습니다", - "description": "이것이 공개 서버인 경우, 데이터(Token, 채팅 기록 등)가 전송 중에 가로챔질 수 있습니다. HTTPS를 사용하거나 로컈 네트워크에서만 접속하는 것을 강력히 권장합니다.", - "dismiss": "경고 닫기" -} + "a11y": { + "skipToContent": "메인 콘텐츠로 건너뀐기", + "sidebarNav": "메인 내비게이션", + "closeMenu": "메뉴 닫기", + "navigatedTo": "{{page}}으로 이동했습니다" } diff --git a/dashboard/src/i18n/locales/zh.json b/dashboard/src/i18n/locales/zh.json index 670dccc1..07f6e65a 100644 --- a/dashboard/src/i18n/locales/zh.json +++ b/dashboard/src/i18n/locales/zh.json @@ -468,10 +468,9 @@ "settingsDesc": "配置系统参数" } }, - "httpWarning": { - "title": "安全警告：", - "message": "您正在使用 HTTP 访问 MaiBot WebUI", - "description": "如果这是公网服务器，您的数据（包括 Token、聊天记录等）可能在传输过程中被窃取。强烈建议使用 HTTPS 访问或仅在本地网络使用。", - "dismiss": "关闭警告" -} + "a11y": { + "skipToContent": "跳过导航，直达主内容", + "sidebarNav": "主导航", + "closeMenu": "关闭菜单", + "navigatedTo": "已导航至 {{page}}" } diff --git a/dashboard/src/index.css b/dashboard/src/index.css index 1119cf0c..ba558b9e 100644 --- a/dashboard/src/index.css +++ b/dashboard/src/index.css @@ -20,10 +20,10 @@ --color-secondary: 210 40% 96.1%; --color-secondary-foreground: 222.2 47.4% 11.2%; --color-muted: 210 40% 96.1%; - --color-muted-foreground: 215.4 16.3% 46.9%; + --color-muted-foreground: 215.4 16.3% 40%; --color-accent: 210 40% 96.1%; --color-accent-foreground: 222.2 47.4% 11.2%; - --color-destructive: 0 84.2% 60.2%; + --color-destructive: 0 84.2% 45%; --color-destructive-foreground: 210 40% 98%; --color-background: 0 0% 100%; --color-foreground: 222.2 84% 4.9%; @@ -320,3 +320,111 @@ } + +/* ============================================================ + * Touch & Pointer 优化 (Task 4) + * ============================================================ */ + +/* 1. 全局 touch-action — 允许浏览器默认滚动/缩放，防止 300ms 延迟 */ +* { + touch-action: manipulation; +} + +/* 可滚动容器恢复双向滚动 */ +.overflow-auto, +.overflow-scroll, +.overflow-x-auto, +.overflow-x-scroll, +.overflow-y-auto, +.overflow-y-scroll { + touch-action: pan-x pan-y; +} + +/* 图表/可视化区域：允许 pinch-zoom（Task 8 的 @use-gesture 也需要此配合）*/ +.recharts-wrapper, +.react-flow__renderer { + touch-action: none; +} + +/* 2. 触控目标最小尺寸 44×44px（WCAG 2.5.8） + pointer: coarse = 触控设备（手指精度低）*/ +@media (pointer: coarse) { + button, + [role="button"], + a, + input[type="checkbox"], + input[type="radio"], + select, + [role="menuitem"], + [role="option"], + [role="tab"] { + min-height: 44px; + min-width: 44px; + } +} + +/* 3. hover-only 反馈降级 + hover: none = 设备主要输入不支持 hover（触控屏等）*/ +@media (hover: none) { + /* 触控设备上隐藏纯 hover 触发的视觉效果（如 tooltip 触发区）*/ + .hover-only-visible { + display: none; + } +} + +/* 4. 精细指针设备（鼠标）才启用的 hover 样式钩子 */ +@media (hover: hover) and (pointer: fine) { + /* 鼠标设备：保留原有 hover 效果，无需额外处理 */ + .touch-device-only { + display: none; + } +} +/* ============================================================ + * Touch 目标尺寸补丁 (Task 10) + * 对小型交互元素用 ::before 伪元素扩大触控区，视觉不变。 + * ============================================================ */ + +@media (pointer: coarse) { + /* Radix Checkbox: h-4 w-4 (16px) → 触控区拖展到 44px */ + [data-radix-collection-item], + button[role='checkbox'], + [role='checkbox'] { + position: relative; + } + [data-radix-collection-item]::before, + button[role='checkbox']::before, + [role='checkbox']::before { + content: ''; + position: absolute; + inset: 50% auto auto 50%; + transform: translate(-50%, -50%); + min-width: 44px; + min-height: 44px; + } + + /* Radix Switch: h-5 w-9 (20px) → 触控区拖展到 44px */ + [role='switch'] { + position: relative; + } + [role='switch']::before { + content: ''; + position: absolute; + inset: 50% auto auto 50%; + transform: translate(-50%, -50%); + min-width: 44px; + min-height: 44px; + } + + /* Radix Slider 拇指 */ + [role='slider'] { + position: relative; + } + [role='slider']::before { + content: ''; + position: absolute; + inset: 50% auto auto 50%; + transform: translate(-50%, -50%); + min-width: 44px; + min-height: 44px; + } +} \ No newline at end of file diff --git a/dashboard/src/main.tsx b/dashboard/src/main.tsx index a42bfe13..8ffbb59e 100644 --- a/dashboard/src/main.tsx +++ b/dashboard/src/main.tsx @@ -1,17 +1,19 @@ import { StrictMode, useEffect, useState } from 'react' import { createRoot } from 'react-dom/client' import { RouterProvider } from '@tanstack/react-router' + import './index.css' import './i18n' -import { router } from './router' +import { AnnouncerProvider } from './components/ui/announcer' import { AssetStoreProvider } from './components/asset-provider' -import { ThemeProvider } from './components/theme-provider' import { AnimationProvider } from './components/animation-provider' +import { ThemeProvider } from './components/theme-provider' import { TourProvider, TourRenderer } from './components/tour' -import { Toaster } from './components/ui/toaster' import { ErrorBoundary } from './components/error-boundary' import { BackendSetupWizard } from './components/electron/BackendSetupWizard' +import { Toaster } from './components/ui/toaster' import { isElectron } from './lib/runtime' +import { router } from './router' function ElectronShell() { const [isFirstLaunch, setIsFirstLaunch] = useState(false) @@ -26,18 +28,20 @@ function ElectronShell() { createRoot(document.getElementById('root')!).render( - - - - - {isElectron() && } - - - - - - - + + + + + + {isElectron() && } + + + + + + + + )