PDF.js移动端适配指南：在React中实现完美触控缩放与响应式布局

PDF.js移动端适配实战：在React中构建丝滑触控与响应式布局

如果你最近在移动端项目中集成过PDF.js，大概率遇到过这样的场景：用户在手机上打开一份PDF，想放大看看细节，结果双指缩放要么没反应，要么直接跳页；横屏切换后，页面布局直接错位；稍微大点的文件，滑动几下就开始卡顿甚至闪退。这些看似“小问题”，在移动办公、在线教育、移动审批等场景下，却足以让用户体验大打折扣。

移动端的PDF预览，远不止是把桌面端的组件缩小那么简单。它涉及到触控手势的精准识别、视口（viewport）的动态计算、横竖屏的无缝切换、以及移动设备特有的内存与性能管理。很多开发者习惯性地用桌面端的思维去处理移动端，结果就是各种“水土不服”。今天，我们就抛开那些宽泛的理论，直接切入移动端开发者的视角，分享一套在React中深度适配PDF.js的实战方案，重点解决触控不灵、布局错乱、性能低下这三个核心痛点。

1. 移动端触控手势的深度优化：超越默认事件

PDF.js自带的交互事件在移动端往往力不从心。默认的click和wheel事件是为鼠标设计的，直接映射到触摸屏上，会导致缩放延迟、滚动冲突。我们的目标是实现如原生阅读应用般的跟手体验。

1.1 识别并拦截原生冲突

首先，我们需要理解冲突的根源。在移动浏览器中，触摸事件会触发一系列默认行为，比如双指捏合可能触发页面的整体缩放（gesturestart、gesturechange），这与我们希望在Canvas内部进行PDF缩放的目标相冲突。

一个关键步骤是阻止这些默认行为，但必须精准，不能影响页面其他部分的正常滚动。我们可以在PDF渲染容器上这样做：

import { useRef, useEffect } from 'react';

const PDFViewerContainer = () => {
  const containerRef = useRef(null);

  useEffect(() => {
    const container = containerRef.current;
    if (!container) return;

    const preventNativeZoom = (e) => {
      // 当触摸点在我们的PDF画布区域内时，阻止浏览器的默认缩放行为
      if (e.touches.length === 2) {
        e.preventDefault();
      }
    };

    // 使用 passive: false 以确保 preventDefault() 能生效
    container.addEventListener('touchstart', preventNativeZoom, { passive: false });
    container.addEventListener('touchmove', preventNativeZoom, { passive: false });

    return () => {
      container.removeEventListener('touchstart', preventNativeZoom);
      container.removeEventListener('touchmove', preventNativeZoom);
    };
  }, []);

  return <div ref={containerRef} className="pdf-container">...</div>;
};

注意：过度使用 preventDefault() 可能会影响页面的其他交互。最佳实践是将其限制在确实需要处理复杂手势的特定元素上，并确保在不需要时及时清理事件监听器。

1.2 实现自定义双指缩放与平移

接下来，我们需要自己计算缩放和平移。核心是监听 touchstart、touchmove、touchend 事件，并计算两点间的距离变化（缩放）和中心点位移（平移）。

const useTouchGesture = (canvasRef, onZoom, onPan) => {
  const touchState = useRef({ initialDistance: null, initialCenter: null, isTouching: false });

  useEffect(() => {
    const canvas = canvasRef.current;
    if (!canvas) return;

    const handleTouchStart = (e) => {
      if (e.touches.length === 2) {
        const touch1 = e.touches[0];
        const touch2 = e.touches[1];
        const dx = touch1.clientX - touch2.clientX;
        const dy = touch1.clientY - touch2.clientY;
        const distance = Math.sqrt(dx * dx + dy * dy);
        const centerX = (touch1.clientX + touch2.clientX) / 2;
        const centerY = (touch1.clientY + touch2.clientY) / 2;

        touchState.current = {
          initialDistance: distance,
          initialCenter: { x: centerX, y: centerY },
          isTouching: true,
        };
        e.preventDefault();
      }
    };

    const handleTouchMove = (e) => {
      if (e.touches.length === 2 && touchState.current.isTouching) {
        const touch1 = e.touches[0];
        const touch2 =