当前位置：首页 > news >正文

React 图片放大镜组件使用文档

news 2026/4/13 5:16:15

一、组件概述

ImageMagnifier 是一个基于 React 实现的图片局部放大预览组件，核心功能为：

展示 500×500px 原始图片
鼠标悬浮时显示 100×100px 半透明遮罩（以鼠标为中心）
右侧同步预览遮罩覆盖区域的图片细节（放大 5 倍）
支持边界限制，避免遮罩移出图片容器
状态驱动视图，符合 React 开发规范

二、核心特性

特性	说明
🖱️ 鼠标跟随	遮罩以鼠标为中心，跟随鼠标移动
🎯 边界限制	遮罩不会超出 500×500px 图片容器
🔍 局部放大	右侧预览区将遮罩区域放大 5 倍展示
🎨 样式可配置	所有样式均通过对象定义，便于修改
♻️ 可复用性 x	所有样式均通过对象定义，便于修改
⚡ 性能优化	遮罩设置 pointer-events: none，避免鼠标事件抖动

三、安装与引入

1. 组件文件创建

在项目中新建ImageMagnifier.jsx文件，粘贴以下完整代码：

import{useState,useRef,useEffect}from'react';constImageMagnifier=({imgUrl})=>{// 容器、遮罩、预览区 DOM 引用constcontainerRef=useRef(null);constmaskRef=useRef(null);constpreviewRef=useRef(null);// 控制遮罩和预览区显示/隐藏const[visible,setVisible]=useState(false);// 图片加载完成后初始化预览区背景useEffect(()=>{constimg=newImage();img.src=imgUrl;img.onload=()=>{if(previewRef.current){// 设置预览区背景图 + 放大 5 倍（500/100）previewRef.current.style.backgroundImage=`url(${imgUrl})`;previewRef.current.style.backgroundSize='2500px 2500px';}};},[imgUrl]);// 鼠标移动：更新遮罩位置 + 预览区显示内容consthandleMouseMove=(e)=>{if(!containerRef.current||!maskRef.current)return;constrect=containerRef.current.getBoundingClientRect();// 鼠标在容器内的坐标constx=e.clientX-rect.left;consty=e.clientY-rect.top;// 遮罩尺寸 100px，以鼠标为中心constmaskWidth=100;constmaskHeight=100;letmaskX=x-maskWidth/2;letmaskY=y-maskHeight/2;// 限制遮罩不超出容器maskX=Math.max(0,Math.min(maskX,500-maskWidth));maskY=Math.max(0,Math.min(maskY,500-maskHeight));// 更新遮罩位置maskRef.current.style.left=`${maskX}px`;maskRef.current.style.top=`${maskY}px`;// 更新预览区背景位置（放大 5 倍）if(previewRef.current){previewRef.current.style.backgroundPosition=`-${maskX*5}px -${maskY*5}px`;}};return(<div style={containerStyle}>{/* 左侧原图容器 */}<div ref={containerRef}style={imgContainerStyle}onMouseMove={handleMouseMove}onMouseEnter={()=>setVisible(true)}onMouseLeave={()=>setVisible(false)}><img src={imgUrl}alt="原图"style={imgStyle}/>{/* 鼠标遮罩层 */}<div ref={maskRef}style={{...maskStyle,display:visible?'block':'none',}}/></div>{/* 右侧细节预览区 */}<div ref={previewRef}style={{...previewStyle,display:visible?'block':'none',}}/></div>);};// 样式配置constcontainerStyle={display:'flex',gap:'20px',padding:'20px',};constimgContainerStyle={position:'relative',width:'500px',height:'500px',border:'1px solid #eee',overflow:'hidden',cursor:'crosshair',};constimgStyle={width:'100%',height:'100%',objectFit:'cover',};constmaskStyle={position:'absolute',width:'100px',height:'100px',background:'rgba(255, 255, 255, 0.3)',border:'1px solid rgba(0,0,0,0.2)',pointerEvents:'none',};constpreviewStyle={width:'500px',height:'500px',border:'1px solid #eee',backgroundRepeat:'no-repeat',};exportdefaultImageMagnifier;

2. 组件使用

在需要使用放大镜的页面中引入并使用组件：

importImageMagnifierfrom'./ImageMagnifier';functionApp(){return(<div className="App"><h1>图片放大镜预览</h1>{/* 传入图片地址即可 */}<ImageMagnifier imgUrl="https://p.qqan.com/up/2021-3/16153651644385966.jpg"/></div>);}exportdefaultApp;