本节将详细介绍如何使用 Tailwind CSS 进行移动端适配，包括响应式设计、触摸交互优化、性能优化等方面。

基础配置

视口配置

  1. <!-- public/index.html -->
  2. <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover">
  4. <!-- 适配刘海屏 -->
  5. <meta name="apple-mobile-web-app-capable" content="yes">
  6. <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">

断点设置

  1. // tailwind.config.js
  2. module.exports = {
  3.   theme: {
  4.     screens: {
  5.       'xs': '375px',
  6.       'sm': '640px',
  7.       'md': '768px',
  8.       'lg': '1024px',
  9.       'xl': '1280px',
  10.       // 自定义断点
  11.       'mobile': '480px',
  12.       'tablet': '768px',
  13.       'laptop': '1024px',
  14.       'desktop': '1280px',
  15.     },
  16.     extend: {
  17.       spacing: {
  18.         'safe-top': 'env(safe-area-inset-top)',
  19.         'safe-bottom': 'env(safe-area-inset-bottom)',
  20.         'safe-left': 'env(safe-area-inset-left)',
  21.         'safe-right': 'env(safe-area-inset-right)',
  22.       },
  23.     },
  24.   },
  25. }

移动端导航

响应式导航组件

  1. // components/MobileNav.tsx
  2. import { useState, useEffect } from 'react';
  4. const MobileNav = () => {
  5.   const [isOpen, setIsOpen] = useState(false);
  6.   const [scrolled, setScrolled] = useState(false);
  8.   useEffect(() => {
  9.     const handleScroll = () => {
  10.       setScrolled(window.scrollY > 20);
  11.     };
  13.     window.addEventListener('scroll', handleScroll);
  14.     return () => window.removeEventListener('scroll', handleScroll);
  15.   }, []);
  17.   return (
  18.     <>
  19.       {/* 固定导航栏 */}
  20.       <nav className={`
  21.         fixed top-0 left-0 right-0 z-50
  22.         transition-colors duration-200
  23.         pt-safe-top
  24.         ${scrolled ? 'bg-white shadow-md' : 'bg-transparent'}
  25.       `}>
  26.         <div className="px-4 py-3">
  27.           <div className="flex items-center justify-between">
  28.             {/* Logo */}
  29.             <div className="flex-shrink-0">
  30.               <img
  31.                 className="h-8 w-auto"
  32.                 src="/logo.svg"
  33.                 alt="Logo"
  34.               />
  35.             </div>
  37.             {/* 菜单按钮 */}
  38.             <button
  39.               onClick={() => setIsOpen(!isOpen)}
  40.               className="inline-flex items-center justify-center p-2 rounded-md text-gray-700 hover:text-gray-900 hover:bg-gray-100 focus:outline-none focus:ring-2 focus:ring-inset focus:ring-blue-500"
  41.             >
  42.               <span className="sr-only">打开菜单</span>
  43.               <svg
  44.                 className={`${isOpen ? 'hidden' : 'block'} h-6 w-6`}
  45.                 fill="none"
  46.                 viewBox="0 0 24 24"
  47.                 stroke="currentColor"
  48.               >
  49.                 <path
  50.                   strokeLinecap="round"
  51.                   strokeLinejoin="round"
  52.                   strokeWidth={2}
  53.                   d="M4 6h16M4 12h16M4 18h16"
  54.                 />
  55.               </svg>
  56.               <svg
  57.                 className={`${isOpen ? 'block' : 'hidden'} h-6 w-6`}
  58.                 fill="none"
  59.                 viewBox="0 0 24 24"
  60.                 stroke="currentColor"
  61.               >
  62.                 <path
  63.                   strokeLinecap="round"
  64.                   strokeLinejoin="round"
  65.                   strokeWidth={2}
  66.                   d="M6 18L18 6M6 6l12 12"
  67.                 />
  68.               </svg>
  69.             </button>
  70.           </div>
  71.         </div>
  73.         {/* 移动端菜单 */}
  74.         <div
  75.           className={`
  76.             fixed inset-0 bg-gray-900 bg-opacity-50 transition-opacity duration-300
  77.             ${isOpen ? 'opacity-100' : 'opacity-0 pointer-events-none'}
  78.           `}
  79.           onClick={() => setIsOpen(false)}
  80.         >
  81.           <div
  82.             className={`
  83.               fixed inset-y-0 right-0 max-w-xs w-full bg-white shadow-xl
  84.               transform transition-transform duration-300 ease-in-out
  85.               ${isOpen ? 'translate-x-0' : 'translate-x-full'}
  86.             `}
  87.             onClick={e => e.stopPropagation()}
  88.           >
  89.             <div className="h-full flex flex-col">
  90.               {/* 菜单头部 */}
  91.               <div className="px-4 py-6 bg-gray-50">
  92.                 <div className="flex items-center justify-between">
  93.                   <h2 className="text-lg font-medium text-gray-900">菜单</h2>
  94.                   <button
  95.                     onClick={() => setIsOpen(false)}
  96.                     className="text-gray-500 hover:text-gray-700"
  97.                   >
  98.                     <span className="sr-only">关闭菜单</span>
  99.                     <svg className="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
  100.                       <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
  101.                     </svg>
  102.                   </button>
  103.                 </div>
  104.               </div>
  106.               {/* 菜单内容 */}
  107.               <div className="flex-1 overflow-y-auto">
  108.                 <nav className="px-4 py-2">
  109.                   <div className="space-y-1">
  110.                     <a
  111.                       href="#"
  112.                       className="block px-3 py-2 rounded-md text-base font-medium text-gray-900 hover:bg-gray-50"
  113.                     >
  114.                       首页
  115.                     </a>
  116.                     <a
  117.                       href="#"
  118.                       className="block px-3 py-2 rounded-md text-base font-medium text-gray-900 hover:bg-gray-50"
  119.                     >
  120.                       产品
  121.                     </a>
  122.                     <a
  123.                       href="#"
  124.                       className="block px-3 py-2 rounded-md text-base font-medium text-gray-900 hover:bg-gray-50"
  125.                     >
  126.                       关于
  127.                     </a>
  128.                   </div>
  129.                 </nav>
  130.               </div>
  131.             </div>
  132.           </div>
  133.         </div>
  134.       </nav>
  136.       {/* 占位元素，防止内容被固定导航栏遮挡 */}
  137.       <div className="h-[calc(env(safe-area-inset-top)+3.5rem)]" />
  138.     </>
  139.   );
  140. };

触摸交互优化

可触摸按钮组件

  1. // components/TouchableButton.tsx
  2. interface TouchableButtonProps {
  3.   onPress?: () => void;
  4.   className?: string;
  5.   children: React.ReactNode;
  6.   disabled?: boolean;
  7. }
  9. const TouchableButton: React.FC<TouchableButtonProps> = ({
  10.   onPress,
  11.   className = '',
  12.   children,
  13.   disabled = false
  14. }) => {
  15.   return (
  16.     <button
  17.       onClick={onPress}
  18.       disabled={disabled}
  19.       className={`
  20.         relative overflow-hidden
  21.         active:opacity-70
  22.         transition-opacity
  23.         touch-manipulation
  24.         select-none
  25.         ${disabled ? 'opacity-50 cursor-not-allowed' : ''}
  26.         ${className}
  27.       `}
  28.       style={{
  29.         WebkitTapHighlightColor: 'transparent',
  30.         WebkitTouchCallout: 'none'
  31.       }}
  32.     >
  33.       {children}
  35.       {/* 触摸反馈效果 */}
  36.       <div className="absolute inset-0 bg-black pointer-events-none opacity-0 active:opacity-10 transition-opacity" />
  37.     </button>
  38.   );
  39. };

滑动列表组件

  1. // components/SwipeableList.tsx
  2. import { useState, useRef } from 'react';
  4. interface SwipeableListProps<T> {
  5.   items: T[];
  6.   renderItem: (item: T) => React.ReactNode;
  7.   onSwipeLeft?: (item: T) => void;
  8.   onSwipeRight?: (item: T) => void;
  9. }
  11. function SwipeableList<T>({
  12.   items,
  13.   renderItem,
  14.   onSwipeLeft,
  15.   onSwipeRight
  16. }: SwipeableListProps<T>) {
  17.   const [activeIndex, setActiveIndex] = useState<number | null>(null);
  18.   const touchStartX = useRef<number>(0);
  19.   const currentOffset = useRef<number>(0);
  21.   const handleTouchStart = (e: React.TouchEvent, index: number) => {
  22.     touchStartX.current = e.touches[0].clientX;
  23.     setActiveIndex(index);
  24.   };
  26.   const handleTouchMove = (e: React.TouchEvent) => {
  27.     if (activeIndex === null) return;
  29.     const touchX = e.touches[0].clientX;
  30.     const diff = touchX - touchStartX.current;
  31.     currentOffset.current = diff;
  33.     // 更新滑动位置
  34.     const element = e.currentTarget as HTMLElement;
  35.     element.style.transform = `translateX(${diff}px)`;
  36.   };
  38.   const handleTouchEnd = (e: React.TouchEvent, item: T) => {
  39.     if (activeIndex === null) return;
  41.     const element = e.currentTarget as HTMLElement;
  42.     const offset = currentOffset.current;
  44.     // 判断滑动方向和距离
  45.     if (Math.abs(offset) > 100) {
  46.       if (offset > 0 && onSwipeRight) {
  47.         onSwipeRight(item);
  48.       } else if (offset < 0 && onSwipeLeft) {
  49.         onSwipeLeft(item);
  50.       }
  51.     }
  53.     // 重置状态
  54.     element.style.transform = '';
  55.     setActiveIndex(null);
  56.     currentOffset.current = 0;
  57.   };
  59.   return (
  60.     <div className="overflow-hidden">
  61.       {items.map((item, index) => (
  62.         <div
  63.           key={index}
  64.           className="transform transition-transform touch-pan-y"
  65.           onTouchStart={e => handleTouchStart(e, index)}
  66.           onTouchMove={handleTouchMove}
  67.           onTouchEnd={e => handleTouchEnd(e, item)}
  68.         >
  69.           {renderItem(item)}
  70.         </div>
  71.       ))}
  72.     </div>
  73.   );
  74. }

性能优化

图片优化

  1. // components/OptimizedImage.tsx
  2. interface OptimizedImageProps {
  3.   src: string;
  4.   alt: string;
  5.   sizes?: string;
  6.   className?: string;
  7. }
  9. const OptimizedImage: React.FC<OptimizedImageProps> = ({
  10.   src,
  11.   alt,
  12.   sizes = '100vw',
  13.   className = ''
  14. }) => {
  15.   return (
  16.     <picture>
  17.       <source
  18.         media="(min-width: 1024px)"
  19.         srcSet={`${src}?w=1024 1024w, ${src}?w=1280 1280w`}
  20.         sizes={sizes}
  21.       />
  22.       <source
  23.         media="(min-width: 768px)"
  24.         srcSet={`${src}?w=768 768w, ${src}?w=1024 1024w`}
  25.         sizes={sizes}
  26.       />
  27.       <img
  28.         src={`${src}?w=375`}
  29.         srcSet={`${src}?w=375 375w, ${src}?w=640 640w`}
  30.         sizes={sizes}
  31.         alt={alt}
  32.         className={`w-full h-auto ${className}`}
  33.         loading="lazy"
  34.         decoding="async"
  35.       />
  36.     </picture>
  37.   );
  38. };

虚拟列表

  1. // components/VirtualList.tsx
  2. import { useState, useEffect, useRef } from 'react';
  4. interface VirtualListProps<T> {
  5.   items: T[];
  6.   renderItem: (item: T) => React.ReactNode;
  7.   itemHeight: number;
  8.   containerHeight: number;
  9.   overscan?: number;
  10. }
  12. function VirtualList<T>({
  13.   items,
  14.   renderItem,
  15.   itemHeight,
  16.   containerHeight,
  17.   overscan = 3
  18. }: VirtualListProps<T>) {
  19.   const [scrollTop, setScrollTop] = useState(0);
  20.   const containerRef = useRef<HTMLDivElement>(null);
  22.   // 计算可见范围
  23.   const visibleCount = Math.ceil(containerHeight / itemHeight);
  24.   const totalHeight = items.length * itemHeight;
  25.   const startIndex = Math.max(0, Math.floor(scrollTop / itemHeight) - overscan);
  26.   const endIndex = Math.min(
  27.     items.length,
  28.     Math.ceil((scrollTop + containerHeight) / itemHeight) + overscan
  29.   );
  31.   // 可见项目
  32.   const visibleItems = items.slice(startIndex, endIndex);
  34.   const handleScroll = () => {
  35.     if (containerRef.current) {
  36.       setScrollTop(containerRef.current.scrollTop);
  37.     }
  38.   };
  40.   return (
  41.     <div
  42.       ref={containerRef}
  43.       className="overflow-auto"
  44.       style={{ height: containerHeight }}
  45.       onScroll={handleScroll}
  46.     >
  47.       <div style={{ height: totalHeight, position: 'relative' }}>
  48.         {visibleItems.map((item, index) => (
  49.           <div
  50.             key={startIndex + index}
  51.             style={{
  52.               position: 'absolute',
  53.               top: (startIndex + index) * itemHeight,
  54.               height: itemHeight,
  55.               width: '100%'
  56.             }}
  57.           >
  58.             {renderItem(item)}
  59.           </div>
  60.         ))}
  61.       </div>
  62.     </div>
  63.   );
  64. }

手势交互

滑动手势处理

  1. // hooks/useSwipe.ts
  2. interface SwipeOptions {
  3.   onSwipeLeft?: () => void;
  4.   onSwipeRight?: () => void;
  5.   onSwipeUp?: () => void;
  6.   onSwipeDown?: () => void;
  7.   threshold?: number;
  8. }
  10. export const useSwipe = (options: SwipeOptions = {}) => {
  11.   const {
  12.     onSwipeLeft,
  13.     onSwipeRight,
  14.     onSwipeUp,
  15.     onSwipeDown,
  16.     threshold = 50
  17.   } = options;
  19.   const touchStart = useRef({ x: 0, y: 0 });
  20.   const touchEnd = useRef({ x: 0, y: 0 });
  22.   const handleTouchStart = (e: TouchEvent) => {
  23.     touchStart.current = {
  24.       x: e.touches[0].clientX,
  25.       y: e.touches[0].clientY
  26.     };
  27.   };
  29.   const handleTouchEnd = (e: TouchEvent) => {
  30.     touchEnd.current = {
  31.       x: e.changedTouches[0].clientX,
  32.       y: e.changedTouches[0].clientY
  33.     };
  35.     const deltaX = touchEnd.current.x - touchStart.current.x;
  36.     const deltaY = touchEnd.current.y - touchStart.current.y;
  38.     if (Math.abs(deltaX) > Math.abs(deltaY)) {
  39.       // 水平滑动
  40.       if (Math.abs(deltaX) > threshold) {
  41.         if (deltaX > 0) {
  42.           onSwipeRight?.();
  43.         } else {
  44.           onSwipeLeft?.();
  45.         }
  46.       }
  47.     } else {
  48.       // 垂直滑动
  49.       if (Math.abs(deltaY) > threshold) {
  50.         if (deltaY > 0) {
  51.           onSwipeDown?.();
  52.         } else {
  53.           onSwipeUp?.();
  54.         }
  55.       }
  56.     }
  57.   };
  59.   return {
  60.     handleTouchStart,
  61.     handleTouchEnd
  62.   };
  63. };

下拉刷新组件

  1. // components/PullToRefresh.tsx
  2. interface PullToRefreshProps {
  3.   onRefresh: () => Promise<void>;
  4.   children: React.ReactNode;
  5. }
  7. const PullToRefresh: React.FC<PullToRefreshProps> = ({
  8.   onRefresh,
  9.   children
  10. }) => {
  11.   const [refreshing, setRefreshing] = useState(false);
  12.   const [pullDistance, setPullDistance] = useState(0);
  13.   const containerRef = useRef<HTMLDivElement>(null);
  14.   const touchStart = useRef(0);
  15.   const pulling = useRef(false);
  17.   const handleTouchStart = (e: React.TouchEvent) => {
  18.     if (containerRef.current?.scrollTop === 0) {
  19.       touchStart.current = e.touches[0].clientY;
  20.       pulling.current = true;
  21.     }
  22.   };
  24.   const handleTouchMove = (e: React.TouchEvent) => {
  25.     if (!pulling.current) return;
  27.     const touch = e.touches[0].clientY;
  28.     const distance = touch - touchStart.current;
  30.     if (distance > 0) {
  31.       e.preventDefault();
  32.       setPullDistance(Math.min(distance * 0.5, 100));
  33.     }
  34.   };
  36.   const handleTouchEnd = async () => {
  37.     if (!pulling.current) return;
  39.     pulling.current = false;
  41.     if (pullDistance > 60 && !refreshing) {
  42.       setRefreshing(true);
  43.       try {
  44.         await onRefresh();
  45.       } finally {
  46.         setRefreshing(false);
  47.       }
  48.     }
  50.     setPullDistance(0);
  51.   };
  53.   return (
  54.     <div
  55.       ref={containerRef}
  56.       className="overflow-auto touch-pan-y"
  57.       onTouchStart={handleTouchStart}
  58.       onTouchMove={handleTouchMove}
  59.       onTouchEnd={handleTouchEnd}
  60.     >
  61.       {/* 刷新指示器 */}
  62.       <div
  63.         className="flex items-center justify-center transition-transform"
  64.         style={{
  65.           transform: `translateY(${pullDistance}px)`,
  66.           height: refreshing ? '50px' : '0'
  67.         }}
  68.       >
  69.         {refreshing ? (
  70.           <div className="animate-spin rounded-full h-6 w-6 border-2 border-gray-900 border-t-transparent" />
  71.         ) : (
  72.           <div className="h-6 w-6 transition-transform" style={{
  73.             transform: `rotate(${Math.min(pullDistance * 3.6, 360)}deg)`
  74.           }}>
  75.             ↓
  76.           </div>
  77.         )}
  78.       </div>
  80.       {/* 内容区域 */}
  81.       <div style={{
  82.         transform: `translateY(${pullDistance}px)`,
  83.         transition: pulling.current ? 'none' : 'transform 0.2s'
  84.       }}>
  85.         {children}
  86.       </div>
  87.     </div>
  88.   );
  89. };

自适应布局

媒体查询工具

  1. // hooks/useMediaQuery.ts
  2. export const useMediaQuery = (query: string) => {
  3.   const [matches, setMatches] = useState(false);
  5.   useEffect(() => {
  6.     const media = window.matchMedia(query);
  7.     const updateMatch = (e: MediaQueryListEvent) => {
  8.       setMatches(e.matches);
  9.     };
  11.     setMatches(media.matches);
  12.     media.addListener(updateMatch);
  14.     return () => media.removeListener(updateMatch);
  15.   }, [query]);
  17.   return matches;
  18. };
  20. // 使用示例
  21. const isMobile = useMediaQuery('(max-width: 768px)');
  22. const isTablet = useMediaQuery('(min-width: 769px) and (max-width: 1024px)');
  23. const isDesktop = useMediaQuery('(min-width: 1025px)');

自适应容器

  1. // components/AdaptiveContainer.tsx
  2. interface AdaptiveContainerProps {
  3.   children: React.ReactNode;
  4.   className?: string;
  5. }
  7. const AdaptiveContainer: React.FC<AdaptiveContainerProps> = ({
  8.   children,
  9.   className = ''
  10. }) => {
  11.   return (
  12.     <div className={`
  13.       w-full px-4 mx-auto
  14.       sm:max-w-screen-sm sm:px-6
  15.       md:max-w-screen-md
  16.       lg:max-w-screen-lg lg:px-8
  17.       xl:max-w-screen-xl
  18.       ${className}
  19.     `}>
  20.       {children}
  21.     </div>
  22.   );
  23. };

调试工具

设备模拟器

  1. // components/DeviceEmulator.tsx
  2. interface DeviceEmulatorProps {
  3.   children: React.ReactNode;
  4.   device?: 'iphone' | 'ipad' | 'android' | 'pixel';
  5. }
  7. const deviceSpecs = {
  8.   iphone: {
  9.     width: '375px',
  10.     height: '812px',
  11.     safeAreaTop: '44px',
  12.     safeAreaBottom: '34px'
  13.   },
  14.   ipad: {
  15.     width: '768px',
  16.     height: '1024px',
  17.     safeAreaTop: '20px',
  18.     safeAreaBottom: '20px'
  19.   },
  20.   // ... 其他设备规格
  21. };
  23. const DeviceEmulator: React.FC<DeviceEmulatorProps> = ({
  24.   children,
  25.   device = 'iphone'
  26. }) => {
  27.   const specs = deviceSpecs[device];
  29.   return (
  30.     <div
  31.       className="relative bg-black rounded-[3rem] p-4"
  32.       style={{
  33.         width: `calc(${specs.width} + 2rem)`,
  34.         height: `calc(${specs.height} + 2rem)`
  35.       }}
  36.     >
  37.       <div
  38.         className="overflow-hidden rounded-[2.5rem] bg-white"
  39.         style={{
  40.           width: specs.width,
  41.           height: specs.height,
  42.           paddingTop: specs.safeAreaTop,
  43.           paddingBottom: specs.safeAreaBottom
  44.         }}
  45.       >
  46.         {children}
  47.       </div>
  48.     </div>
  49.   );
  50. };

开发者工具

  1. // utils/mobileDebugger.ts
  2. export const initMobileDebugger = () => {
  3.   if (process.env.NODE_ENV === 'development') {
  4.     // 显示点击区域
  5.     document.addEventListener('touchstart', (e) => {
  6.       const touch = e.touches[0];
  7.       const dot = document.createElement('div');
  8.       dot.style.cssText = `
  9.         position: fixed;
  10.         z-index: 9999;
  11.         width: 20px;
  12.         height: 20px;
  13.         background: rgba(255, 0, 0, 0.5);
  14.         border-radius: 50%;
  15.         pointer-events: none;
  16.         transform: translate(-50%, -50%);
  17.         left: ${touch.clientX}px;
  18.         top: ${touch.clientY}px;
  19.       `;
  20.       document.body.appendChild(dot);
  21.       setTimeout(() => dot.remove(), 500);
  22.     });
  24.     // 显示视口信息
  25.     const viewport = document.createElement('div');
  26.     viewport.style.cssText = `
  27.       position: fixed;
  28.       z-index: 9999;
  29.       bottom: 0;
  30.       left: 0;
  31.       background: rgba(0, 0, 0, 0.7);
  32.       color: white;
  33.       padding: 4px 8px;
  34.       font-size: 12px;
  35.     `;
  36.     document.body.appendChild(viewport);
  38.     const updateViewport = () => {
  39.       viewport.textContent = `${window.innerWidth}x${window.innerHeight}`;
  40.     };
  42.     window.addEventListener('resize', updateViewport);
  43.     updateViewport();
  44.   }
  45. };

最佳实践

  1. 响应式设计

    • 移动优先策略
    • 合理的断点设置
    • 灵活的布局系统

  2. 触摸交互

    • 适当的点击区域
    • 清晰的反馈效果
    • 流畅的动画过渡

  3. 性能优化

    • 图片优化处理
    • 延迟加载策略
    • 虚拟滚动列表

  4. 用户体验

    • 合理的字体大小
    • 清晰的视觉层级
    • 直观的操作反馈