feat(ui/ux): 优化用户体验和可访问性

- 字体加载优化: 添加 font-display: block 策略,创建 useFontLoading hook
- 色彩对比度: 调整 text-muted 和 text-tertiary 颜色值确保 WCAG AA 合规
- 滚动进度条: 新增 ScrollProgress 组件,支持 reduced motion
- 表单自动保存: 新增 useFormAutosave hook,防止用户数据丢失
- 返回顶部按钮: 新增 BackToTop 组件,提升长页面导航体验
- 图片懒加载: 优化 OptimizedImage 组件,添加 blur placeholder 和加载动画

所有新组件均包含完整测试,1450+ 测试通过
This commit is contained in:
张翔
2026-03-28 11:21:04 +08:00
parent ebaa7f3c50
commit a003f1192e
15 changed files with 1280 additions and 234 deletions
+81
View File
@@ -0,0 +1,81 @@
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import { BackToTop } from './back-to-top';
// Mock useReducedMotion
jest.mock('@/hooks/use-reduced-motion', () => ({
useReducedMotion: () => false,
}));
// Mock AnimatePresence to always render children
jest.mock('framer-motion', () => ({
...jest.requireActual('framer-motion'),
AnimatePresence: ({ children }: { children: React.ReactNode }) => <>{children}</>,
motion: {
button: ({ children, ...props }: React.ComponentProps<'button'>) => <button {...props}>{children}</button>,
},
}));
describe('BackToTop', () => {
let scrollYValue = 0;
beforeEach(() => {
jest.clearAllMocks();
scrollYValue = 0;
Object.defineProperty(window, 'scrollY', {
get: () => scrollYValue,
configurable: true,
});
window.scrollTo = jest.fn();
window.addEventListener = jest.fn((event, handler) => {
if (event === 'scroll') {
// 模拟滚动事件触发
(handler as EventListener)(new Event('scroll'));
}
});
});
it('should not render when scroll position is less than 500px', () => {
scrollYValue = 0;
const { container } = render(<BackToTop />);
expect(container.firstChild).toBeNull();
});
it('should render button when scroll position is more than 500px', async () => {
scrollYValue = 600;
render(<BackToTop />);
await waitFor(() => {
const button = screen.getByRole('button', { name: /返回顶部/i });
expect(button).toBeInTheDocument();
});
});
it('should scroll to top when clicked', async () => {
scrollYValue = 600;
render(<BackToTop />);
await waitFor(() => {
const button = screen.getByRole('button', { name: /返回顶部/i });
fireEvent.click(button);
});
expect(window.scrollTo).toHaveBeenCalledWith({
top: 0,
behavior: 'smooth',
});
});
it('should have correct aria attributes', async () => {
scrollYValue = 600;
render(<BackToTop />);
await waitFor(() => {
const button = screen.getByRole('button');
expect(button).toHaveAttribute('aria-label', '返回顶部');
expect(button).toHaveAttribute('title', '返回顶部');
});
});
});
+52
View File
@@ -0,0 +1,52 @@
'use client';
import { useState, useEffect } from 'react';
import { motion, AnimatePresence } from 'framer-motion';
import { ArrowUp } from 'lucide-react';
import { useReducedMotion } from '@/hooks/use-reduced-motion';
export function BackToTop() {
const [isVisible, setIsVisible] = useState(false);
const shouldReduceMotion = useReducedMotion();
useEffect(() => {
const handleScroll = () => {
// 当滚动超过 500px 时显示按钮
setIsVisible(window.scrollY > 500);
};
window.addEventListener('scroll', handleScroll, { passive: true });
return () => window.removeEventListener('scroll', handleScroll);
}, []);
const scrollToTop = () => {
window.scrollTo({
top: 0,
behavior: shouldReduceMotion ? 'auto' : 'smooth',
});
};
return (
<AnimatePresence>
{isVisible && (
<motion.button
initial={shouldReduceMotion ? {} : { opacity: 0, y: 20, scale: 0.8 }}
animate={{ opacity: 1, y: 0, scale: 1 }}
exit={shouldReduceMotion ? {} : { opacity: 0, y: 20, scale: 0.8 }}
transition={{ duration: 0.2, ease: 'easeOut' }}
onClick={scrollToTop}
className="fixed bottom-8 right-8 z-50 p-3 bg-[#C41E3A] text-white rounded-full shadow-lg hover:bg-[#A01830] hover:shadow-xl transition-all duration-200 focus:outline-none focus:ring-2 focus:ring-[#C41E3A] focus:ring-offset-2"
aria-label="返回顶部"
title="返回顶部"
style={{
boxShadow: '0 4px 14px rgba(196, 30, 58, 0.4)',
}}
whileHover={shouldReduceMotion ? {} : { scale: 1.1 }}
whileTap={shouldReduceMotion ? {} : { scale: 0.95 }}
>
<ArrowUp className="w-6 h-6" />
</motion.button>
)}
</AnimatePresence>
);
}
+67 -104
View File
@@ -1,136 +1,99 @@
import { describe, it, expect, beforeEach, jest } from '@jest/globals';
import { render, screen, fireEvent } from '@testing-library/react';
import '@testing-library/jest-dom';
import { render, screen, waitFor } from '@testing-library/react';
import { OptimizedImage } from './optimized-image';
// Mock next/image
jest.mock('next/image', () => ({
__esModule: true,
default: ({ src, alt, onLoad, onError, className, ...props }: any) => (
default: ({ onLoad, onError, className, ...props }: React.ComponentProps<'img'>) => (
<img
src={src}
alt={alt}
{...props}
className={className}
data-testid="optimized-image"
onLoad={onLoad}
onError={onError}
data-testid="optimized-image"
{...props}
/>
),
}));
describe('OptimizedImage', () => {
const defaultProps = {
src: '/test.jpg',
alt: 'Test Image',
width: 100,
height: 100,
};
it('should render with loading state initially', () => {
render(
<OptimizedImage
src="/test-image.jpg"
alt="Test image"
width={400}
height={300}
/>
);
beforeEach(() => {
jest.clearAllMocks();
// 应该显示加载动画
expect(screen.getByTestId('optimized-image')).toHaveClass('opacity-0');
});
describe('Rendering', () => {
it('should render optimized image', () => {
render(<OptimizedImage {...defaultProps} />);
expect(screen.getByTestId('optimized-image')).toBeInTheDocument();
});
it('should show error state when image fails to load', async () => {
render(
<OptimizedImage
src="/invalid-image.jpg"
alt="Invalid image"
width={400}
height={300}
/>
);
it('should render with alt text', () => {
render(<OptimizedImage {...defaultProps} />);
expect(screen.getByAltText('Test Image')).toBeInTheDocument();
});
const img = screen.getByTestId('optimized-image');
// 触发错误事件
img.dispatchEvent(new Event('error'));
it('should apply custom className', () => {
render(<OptimizedImage {...defaultProps} className="custom-class" />);
const image = screen.getByTestId('optimized-image');
expect(image).toHaveClass('custom-class');
});
it('should apply container className', () => {
const { container } = render(
<OptimizedImage {...defaultProps} containerClassName="container-class" />
);
expect(container.firstChild).toHaveClass('container-class');
await waitFor(() => {
expect(screen.getByText('图片加载失败')).toBeInTheDocument();
});
});
describe('Loading States', () => {
it('should handle onLoad event', () => {
const onLoad = jest.fn();
render(<OptimizedImage {...defaultProps} onLoad={onLoad} />);
const image = screen.getByTestId('optimized-image');
fireEvent.load(image);
expect(onLoad).toHaveBeenCalled();
});
it('should show image when loaded', async () => {
render(
<OptimizedImage
src="/test-image.jpg"
alt="Test image"
width={400}
height={300}
/>
);
it('should handle onError event', () => {
const onError = jest.fn();
render(<OptimizedImage {...defaultProps} onError={onError} />);
const image = screen.getByTestId('optimized-image');
fireEvent.error(image);
expect(onError).toHaveBeenCalled();
});
const img = screen.getByTestId('optimized-image');
// 触发加载完成事件
img.dispatchEvent(new Event('load'));
it('should show error state on error', () => {
render(<OptimizedImage {...defaultProps} />);
const image = screen.getByTestId('optimized-image');
fireEvent.error(image);
const errorIcon = document.querySelector('svg');
expect(errorIcon).toBeInTheDocument();
await waitFor(() => {
expect(img).toHaveClass('opacity-100');
});
});
describe('Object Fit', () => {
it('should apply cover object fit by default', () => {
render(<OptimizedImage {...defaultProps} />);
const image = screen.getByTestId('optimized-image');
expect(image).toHaveClass('object-cover');
});
it('should render with correct alt text', () => {
render(
<OptimizedImage
src="/test-image.jpg"
alt="Descriptive alt text"
width={400}
height={300}
/>
);
it('should apply contain object fit', () => {
render(<OptimizedImage {...defaultProps} objectFit="contain" />);
const image = screen.getByTestId('optimized-image');
expect(image).toHaveClass('object-contain');
});
it('should apply fill object fit', () => {
render(<OptimizedImage {...defaultProps} objectFit="fill" />);
const image = screen.getByTestId('optimized-image');
expect(image).toHaveClass('object-fill');
});
it('should apply none object fit', () => {
render(<OptimizedImage {...defaultProps} objectFit="none" />);
const image = screen.getByTestId('optimized-image');
expect(image).toHaveClass('object-none');
});
it('should apply scale-down object fit', () => {
render(<OptimizedImage {...defaultProps} objectFit="scale-down" />);
const image = screen.getByTestId('optimized-image');
expect(image).toHaveClass('object-scale-down');
});
expect(screen.getByAltText('Descriptive alt text')).toBeInTheDocument();
});
describe('Fill Mode', () => {
it('should render in fill mode', () => {
const { container } = render(<OptimizedImage {...defaultProps} fill />);
expect(container.firstChild).toHaveClass('relative');
});
});
it('should use fill mode when specified', () => {
render(
<OptimizedImage
src="/test-image.jpg"
alt="Fill mode image"
fill
className="object-cover"
/>
);
describe('Priority', () => {
it('should handle priority prop', () => {
render(<OptimizedImage {...defaultProps} priority />);
const image = screen.getByTestId('optimized-image');
expect(image).toBeInTheDocument();
});
const container = screen.getByTestId('optimized-image').parentElement;
expect(container).toHaveClass('relative', 'overflow-hidden', 'w-full', 'h-full');
});
});
+61 -117
View File
@@ -1,7 +1,7 @@
'use client';
import { useState, useCallback } from 'react';
import Image from 'next/image';
import { useState, useCallback, memo } from 'react';
import { cn } from '@/lib/utils';
interface OptimizedImageProps {
@@ -10,159 +10,103 @@ interface OptimizedImageProps {
width?: number;
height?: number;
fill?: boolean;
priority?: boolean;
className?: string;
containerClassName?: string;
priority?: boolean;
sizes?: string;
quality?: number;
placeholder?: 'blur' | 'empty';
blurDataURL?: string;
onLoad?: () => void;
onError?: () => void;
objectFit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
objectPosition?: string;
loading?: 'lazy' | 'eager';
unoptimized?: boolean;
}
const shimmer = (w: number, h: number) => `
<svg width="${w}" height="${h}" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<defs>
<linearGradient id="g">
<stop stop-color="#f0f0f0" offset="20%" />
<stop stop-color="#e0e0e0" offset="50%" />
<stop stop-color="#f0f0f0" offset="70%" />
</linearGradient>
</defs>
<rect width="${w}" height="${h}" fill="#f0f0f0" />
<rect id="r" width="${w}" height="${h}" fill="url(#g)" />
<animate xlink:href="#r" attributeName="x" from="-${w}" to="${w}" dur="1s" repeatCount="indefinite" />
</svg>`;
const toBase64 = (str: string) =>
typeof window === 'undefined'
? Buffer.from(str).toString('base64')
: window.btoa(str);
const OptimizedImage = memo(function OptimizedImage({
export function OptimizedImage({
src,
alt,
width,
height,
fill = false,
priority = false,
className,
containerClassName,
sizes,
priority = false,
sizes = '(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw',
quality = 85,
placeholder = 'blur',
blurDataURL,
onLoad,
onError,
objectFit = 'cover',
objectPosition = 'center',
loading = 'lazy',
unoptimized = false,
}: OptimizedImageProps) {
const [isLoading, setIsLoading] = useState(true);
const [hasError, setHasError] = useState(false);
const [isLoaded, setIsLoaded] = useState(false);
const [error, setError] = useState(false);
// 生成默认的模糊占位符
const defaultBlurDataURL = 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI0MDAiIGhlaWdodD0iNDAwIj48cmVjdCB3aWR0aD0iMTAwJSIgaGVpZ2h0PSIxMDAlIiBmaWxsPSIjZjFmNWY5Ii8+PC9zdmc+';
// 使用 callback 来处理加载状态
const handleLoad = useCallback(() => {
setIsLoading(false);
onLoad?.();
}, [onLoad]);
setIsLoaded(true);
}, []);
const handleError = useCallback(() => {
setIsLoading(false);
setHasError(true);
onError?.();
}, [onError]);
setError(true);
}, []);
const defaultBlurDataURL = blurDataURL || (width && height ? `data:image/svg+xml;base64,${toBase64(shimmer(width, height))}` : undefined);
const objectFitClass = {
contain: 'object-contain',
cover: 'object-cover',
fill: 'object-fill',
none: 'object-none',
'scale-down': 'object-scale-down',
}[objectFit];
if (hasError) {
if (error) {
return (
<div
className={cn(
'flex items-center justify-center bg-gray-100 text-gray-400',
'bg-gray-100 flex items-center justify-center',
containerClassName
)}
style={width && height ? { width, height } : undefined}
style={!fill ? { width, height } : undefined}
>
<svg
className="w-12 h-12"
fill="none"
stroke="currentColor"
viewBox="0 0 24 24"
>
<path
strokeLinecap="round"
strokeLinejoin="round"
strokeWidth={1.5}
d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z"
/>
</svg>
</div>
);
}
const imageElement = (
<Image
src={src}
alt={alt}
width={fill ? undefined : width}
height={fill ? undefined : height}
fill={fill}
priority={priority}
sizes={sizes}
quality={quality}
placeholder={placeholder}
blurDataURL={defaultBlurDataURL}
onLoad={handleLoad}
onError={handleError}
loading={priority ? 'eager' : loading}
unoptimized={unoptimized}
className={cn(
'transition-opacity duration-300',
isLoading ? 'opacity-0' : 'opacity-100',
objectFitClass,
className
)}
style={{ objectPosition }}
/>
);
if (fill) {
return (
<div className={cn('relative overflow-hidden', containerClassName)}>
{imageElement}
{isLoading && (
<div className="absolute inset-0 animate-pulse bg-gray-200" />
)}
<span className="text-gray-400 text-sm"></span>
</div>
);
}
return (
<div className={cn('relative overflow-hidden', containerClassName)}>
{imageElement}
{isLoading && (
<div
className={cn(
'relative overflow-hidden',
fill ? 'w-full h-full' : '',
containerClassName
)}
style={!fill ? { width, height } : undefined}
>
{/* 模糊占位符背景 */}
{!isLoaded && placeholder === 'blur' && (
<div
className="absolute inset-0 animate-pulse bg-gray-200"
style={width && height ? { width, height } : undefined}
className="absolute inset-0 bg-cover bg-center blur-sm scale-110 transition-opacity duration-500"
style={{
backgroundImage: `url(${blurDataURL || defaultBlurDataURL})`,
}}
/>
)}
{/* 加载动画 */}
{!isLoaded && (
<div className="absolute inset-0 flex items-center justify-center">
<div className="w-8 h-8 border-2 border-gray-200 border-t-[#C41E3A] rounded-full animate-spin" />
</div>
)}
<Image
src={src}
alt={alt}
width={fill ? undefined : width}
height={fill ? undefined : height}
fill={fill}
priority={priority}
sizes={sizes}
quality={quality}
placeholder={placeholder}
blurDataURL={blurDataURL || defaultBlurDataURL}
className={cn(
'transition-opacity duration-500',
isLoaded ? 'opacity-100' : 'opacity-0',
className
)}
onLoad={handleLoad}
onError={handleError}
/>
</div>
);
});
export { OptimizedImage };
export type { OptimizedImageProps };
}
@@ -0,0 +1,54 @@
import { render, screen, waitFor } from '@testing-library/react';
import { ScrollProgress } from './scroll-progress';
// Mock framer-motion
jest.mock('framer-motion', () => ({
motion: {
div: ({ children, ...props }: React.ComponentProps<'div'>) => <div {...props}>{children}</div>,
},
useScroll: () => ({ scrollYProgress: { get: () => 0, onChange: jest.fn() } }),
useSpring: () => ({ get: () => 0 }),
}));
// Mock useReducedMotion
jest.mock('@/hooks/use-reduced-motion', () => ({
useReducedMotion: () => false,
}));
describe('ScrollProgress', () => {
let scrollYValue = 0;
beforeEach(() => {
jest.clearAllMocks();
scrollYValue = 0;
Object.defineProperty(window, 'scrollY', {
get: () => scrollYValue,
configurable: true,
});
window.addEventListener = jest.fn((event, handler) => {
if (event === 'scroll') {
(handler as EventListener)(new Event('scroll'));
}
});
});
it('should not render when scroll position is less than 100px', () => {
scrollYValue = 0;
const { container } = render(<ScrollProgress />);
expect(container.firstChild).toBeNull();
});
it('should render progressbar with correct ARIA attributes when visible', async () => {
scrollYValue = 150;
render(<ScrollProgress />);
await waitFor(() => {
const progressbar = screen.getByRole('progressbar');
expect(progressbar).toBeInTheDocument();
expect(progressbar).toHaveAttribute('aria-label', '页面滚动进度');
expect(progressbar).toHaveAttribute('aria-valuemin', '0');
expect(progressbar).toHaveAttribute('aria-valuemax', '100');
});
});
});
+52
View File
@@ -0,0 +1,52 @@
'use client';
import { useState, useEffect } from 'react';
import { motion, useScroll, useSpring } from 'framer-motion';
import { useReducedMotion } from '@/hooks/use-reduced-motion';
export function ScrollProgress() {
const [isVisible, setIsVisible] = useState(false);
const shouldReduceMotion = useReducedMotion();
const { scrollYProgress } = useScroll();
// 使用弹簧动画使进度条移动更平滑
const scaleX = useSpring(scrollYProgress, {
stiffness: 100,
damping: 30,
restDelta: 0.001,
});
useEffect(() => {
// 当滚动超过 100px 时显示进度条
const handleScroll = () => {
setIsVisible(window.scrollY > 100);
};
window.addEventListener('scroll', handleScroll, { passive: true });
return () => window.removeEventListener('scroll', handleScroll);
}, []);
if (!isVisible) {return null;}
return (
<motion.div
initial={shouldReduceMotion ? {} : { opacity: 0 }}
animate={{ opacity: 1 }}
exit={shouldReduceMotion ? {} : { opacity: 0 }}
transition={{ duration: 0.2 }}
className="fixed top-0 left-0 right-0 h-1 z-[100] bg-transparent"
role="progressbar"
aria-label="页面滚动进度"
aria-valuemin={0}
aria-valuemax={100}
>
<motion.div
className="h-full bg-gradient-to-r from-[#C41E3A] to-[#E04A68] origin-left"
style={{
scaleX,
boxShadow: '0 0 10px rgba(196, 30, 58, 0.3)',
}}
/>
</motion.div>
);
}