React Three Fiber 實現 3D 模型點擊高亮交互的核心技巧

在 WebGL 3D 開發中，模型交互是提升用戶體驗的關鍵功能之一。本文將基于 React Three Fiber（R3F）和 Three.js，總結 3D 模型點擊高亮（包括模型本身和邊框）的核心技術技巧，幫助開發者快速掌握復雜 3D 交互的實現思路。本文主要圍著以下功能進行講述

加載 GLB?格式的 3D 城市模型
通過鼠標點擊實現模型的選中 / 取消選中狀態切換
選中時同時顯示兩種高亮效果：
模型本身的半透明材質覆蓋
模型邊緣的線框高亮

完善的資源管理和內存清理機制

操作面板和模型導入功能參考這篇博客

Three.js 如何控制 GLB 模型的內置屬性實現精準顯示-CSDN博客

?3D 模型加載與引用管理

?使用?useGLTF?鉤子簡化 GLTF 模型加載，這是 R3F 生態中處理 3D 資源的標準方式，內部已處理加載狀態、資源緩存和內存管理；通過?ref?引用 Three.js 原生 Group 對象，使我們能直接操作 3D 場景對象；使用?<primitive>?組件將 Three.js 原生對象掛載到 React 虛擬 DOM 中，實現 React 對 Three.js 對象的管理

import { useGLTF } from '@react-three/drei'export const CityModel = ({ url }: { url: string }) => {const { scene } = useGLTF(url)const modelRef = useRef<THREE.Group>(null)// 組件渲染return <primitive object={scene} ref={modelRef} />
}

?射線檢測實現模型點擊交互

?這是 3D 交互的核心機制，通過?Raycaster?模擬一條從相機發射到點擊位置的射線。坐標轉換是關鍵：將屏幕像素坐標（0~window.innerWidth）轉換為 Three.js 標準化設備坐標（-1~1）。intersectObject?方法第二個參數設為?true?表示遞歸檢測所有子對象，確保能選中復雜模型的子網格。優先處理?intersects[0]（最近的交點），符合真實世界的交互邏輯

const raycaster = useRef(new THREE.Raycaster())
const pointer = useRef(new THREE.Vector2())const handleClick = (event: MouseEvent) => {// 僅響應左鍵點擊if (event.button !== 0) return// 屏幕坐標轉換為 Three.js 標準化設備坐標pointer.current.x = (event.clientX / window.innerWidth) * 2 - 1pointer.current.y = -(event.clientY / window.innerHeight) * 2 + 1detectClickedMesh()
}const detectClickedMesh = () => {if (!modelRef.current) return// 更新射線（從相機到點擊位置）raycaster.current.setFromCamera(pointer.current, camera)// 檢測與模型的交點（遞歸檢測所有子Mesh）const intersects = raycaster.current.intersectObject(modelRef.current, true)if (intersects.length > 0) {const clickedObject = intersects[0].object as THREE.Mesh// 處理點擊邏輯...}
}

材質切換實現模型高亮

利用 Three.js 的?userData?存儲原始材質，這是一種安全的擴展對象屬性的方式；同時支持單材質和多材質（MeshFaceMaterial）的場景，處理更全面

使用?clone()?方法創建材質副本，避免多個對象共享同一材質實例導致的樣式沖突

半透明材質（transparent: true）實現高亮效果的同時不遮擋其他重要信息

// 高亮材質（半透明效果）
const highlightMaterial = useRef(new THREE.MeshBasicMaterial({ color: '#040912', transparent: true, opacity: 0.4 })
)// 保存原始材質并應用高亮材質
const saveOriginalAndApplyHighlight = (mesh: THREE.Mesh) => {// 保存原始材質（處理單材質和多材質情況）if (!mesh.userData.originalMaterial) {if (Array.isArray(mesh.material)) {mesh.userData.originalMaterial = [...mesh.material]mesh.material = mesh.material.map(() => highlightMaterial.current.clone())} else {mesh.userData.originalMaterial = mesh.materialmesh.material = highlightMaterial.current.clone()}}
}// 恢復原始材質
const restoreOriginalMaterial = (mesh: THREE.Mesh[]) => {mesh.forEach(m => {if (m.userData.originalMaterial) {m.material = m.userData.originalMaterial}})
}

邊緣線框高亮效果實現

使用?EdgesGeometry?從網格幾何體生成邊緣線，自動計算模型的輪廓邊緣
通過?LineSegments?創建線框對象，比?Line?更適合表現閉合輪廓
將線框作為模型的子對象，確保線框能跟隨模型一起變換（移動、旋轉、縮放）
使用?Map?+?uuid?管理線框對象，確保每個模型對應唯一的線框，方便添加 / 移除

// 存儲所有創建的邊緣線對象
const edgeLines = useRef<Map<string, THREE.LineSegments>>(new Map())// 添加邊緣高亮效果
const addHighlight = (object: THREE.Mesh) => {if (!object.geometry) return// 創建邊緣幾何體const geometry = new THREE.EdgesGeometry(object.geometry)// 創建邊緣線材質const material = new THREE.LineBasicMaterial({color: 0x4C8BF5, // 藍色邊緣linewidth: 2,})// 創建邊緣線對象const line = new THREE.LineSegments(geometry, material)// 繼承原始模型的變換屬性line.position.copy(object.position)line.rotation.copy(object.rotation)line.scale.copy(object.scale)// 添加到模型并記錄object.add(line)edgeLines.current.set(object.uuid, line)
}// 移除邊緣高亮效果
const removeHighlight = (object: THREE.Mesh) => {const line = edgeLines.current.get(object.uuid)if (line && object.children.includes(line)) {object.remove(line)}edgeLines.current.delete(object.uuid)
}

組件生命周期與資源管理

在?useEffect?中管理事件監聽，確保只在模型加載完成后綁定事件
卸載時執行完整的清理工作：移除事件監聽、清理線框對象、恢復材質狀態
避免內存泄漏：Three.js 對象如果不手動清理，即使組件卸載也可能殘留在內存中
狀態重置：確保組件卸載后所有引用和狀態都回到初始狀態?

useEffect(() => {if (!modelRef.current) return// 模型初始化邏輯...// 綁定點擊事件window.addEventListener('click', handleClick)// 組件卸載時清理return () => {window.removeEventListener('click', handleClick)// 移除所有高亮邊緣線highlightedMeshRef.current.forEach(mesh => {removeHighlight(mesh)})edgeLines.current.clear()// 清理高亮狀態if (highlightedMeshRef.current) {restoreOriginalMaterial(highlightedMeshRef.current)}highlightedMeshRef.current = []}
}, [modelRef.current])

完整代碼?

其中? const helper = useModelManager()是我用于操作面板管理時獲取模型數據，不用可以移除

?CityModel.tsx

import { useGLTF } from '@react-three/drei'
import { useThree } from '@react-three/fiber'
import { useEffect, useRef } from 'react'
import * as THREE from 'three'
import { useModelManager } from '../../../utils/viewHelper/viewContext'export const CityModel = ({ url }: { url: string }) => {const { scene } = useGLTF(url)const modelRef = useRef<THREE.Group>(null)const helper = useModelManager()const { camera } = useThree()const raycaster = useRef(new THREE.Raycaster())const pointer = useRef(new THREE.Vector2())const highlightedMeshRef = useRef<THREE.Mesh[]>([])// 存儲所有創建的邊緣線對象const edgeLines = useRef<Map<string, THREE.LineSegments>>(new Map())// 高亮材質（半透明青色）const highlightMaterial = useRef(new THREE.MeshBasicMaterial({color: '#5a6f85',transparent: true,opacity: 0.7,}),)// 添加邊緣高亮效果const addHighlight = (object: THREE.Mesh) => {if (!object.geometry) return// 創建邊緣幾何體const geometry = new THREE.EdgesGeometry(object.geometry)// 創建邊緣線材質const material = new THREE.LineBasicMaterial({color: 0x4c8bf5, // 藍色邊緣linewidth: 2, // 線寬})// 創建邊緣線對象const line = new THREE.LineSegments(geometry, material)line.name = 'surroundLine'// 復制原始網格的變換line.position.copy(object.position)line.rotation.copy(object.rotation)line.scale.copy(object.scale)// 設置為模型的子對象，確保跟隨模型變換object.add(line)edgeLines.current.set(object.uuid, line)}// 移除邊緣高亮效果const removeHighlight = (object: THREE.Mesh) => {const line = edgeLines.current.get(object.uuid)if (line && object.children.includes(line)) {object.remove(line)}edgeLines.current.delete(object.uuid)}// 處理左鍵點擊事件const handleClick = (event: MouseEvent) => {// 僅響應左鍵點擊（排除右鍵/中鍵/滾輪）if (event.button !== 0) return// 計算點擊位置的標準化設備坐標pointer.current.x = (event.clientX / window.innerWidth) * 2 - 1pointer.current.y = -(event.clientY / window.innerHeight) * 2 + 1// 執行射線檢測，判斷點擊目標detectClickedMesh()}// 檢測點擊的Mesh并切換高亮狀態const detectClickedMesh = () => {if (!modelRef.current) return// 更新射線（從相機到點擊位置）raycaster.current.setFromCamera(pointer.current, camera)// 檢測與模型的交點（遞歸檢測所有子Mesh）const intersects = raycaster.current.intersectObject(modelRef.current, true)if (intersects.length > 0) {const clickedObject = intersects[0].object as THREE.Mesh// 僅處理標記為可交互的Meshif (clickedObject instanceof THREE.Mesh &&clickedObject.userData.interactive) {// 切換高亮狀態：點擊已高亮的Mesh則取消，否則高亮新Meshif (highlightedMeshRef.current?.includes(clickedObject)) {console.log('取消高亮', clickedObject.name)// 取消高亮：恢復原始材質restoreOriginalMaterial([clickedObject])// 移除邊框高亮removeHighlight(clickedObject)const newHighlighted = highlightedMeshRef.current.filter((m) => m.name !== clickedObject.name,)highlightedMeshRef.current = [...newHighlighted]} else {console.log('高亮', clickedObject.name)// 高亮當前點擊的MeshsaveOriginalAndApplyHighlight(clickedObject)// 添加邊框高亮addHighlight(clickedObject)highlightedMeshRef.current = [...highlightedMeshRef.current,clickedObject,]}}}}// 工具函數：恢復原始材質const restoreOriginalMaterial = (mesh: THREE.Mesh[]) => {mesh.forEach((m) => {if (m.userData.originalMaterial) {m.material = m.userData.originalMaterial}})}// 工具函數：保存原始材質并應用高亮材質const saveOriginalAndApplyHighlight = (mesh: THREE.Mesh) => {// 保存原始材質（處理單材質和多材質情況）if (!mesh.userData.originalMaterial) {if (Array.isArray(mesh.material)) {mesh.userData.originalMaterial = [...mesh.material]mesh.material = mesh.material.map(() =>highlightMaterial.current.clone(),)} else {mesh.userData.originalMaterial = mesh.materialmesh.material = highlightMaterial.current.clone()}} else {// 已保存過原始材質，直接應用高亮if (Array.isArray(mesh.material)) {mesh.material = mesh.material.map(() =>highlightMaterial.current.clone(),)} else {mesh.material = highlightMaterial.current.clone()}}}// 模型加載后初始化useEffect(() => {if (!modelRef.current) returnaddModel()const box = new THREE.Box3().setFromObject(modelRef.current)const center = new THREE.Vector3()box.getCenter(center)const size = new THREE.Vector3()box.getSize(size)const maxDim = Math.max(size.x, size.y, size.z)const fov = 100const cameraZ = Math.abs(maxDim / 2 / Math.tan((Math.PI * fov) / 360))camera.position.set(0, maxDim * 0.8, cameraZ * 1.2)camera.lookAt(0, 0, 0)// 遍歷模型設置通用屬性并標記可交互modelRef.current.traverse((child) => {if (child instanceof THREE.Mesh) {child.castShadow = truechild.receiveShadow = truechild.material.transparent = true// 標記為可交互（后續可通過此屬性過濾）child.userData.interactive = true}})// 綁定點擊事件監聽window.addEventListener('click', handleClick)// 組件卸載時清理return () => {window.removeEventListener('click', handleClick)// 移除所有高亮邊緣線highlightedMeshRef.current.forEach((mesh) => {removeHighlight(mesh)})edgeLines.current.clear()// 清理高亮狀態if (highlightedMeshRef.current) {restoreOriginalMaterial(highlightedMeshRef.current)}highlightedMeshRef.current = []}}, [modelRef.current])// 添加模型到管理器const addModel = () => {if (modelRef.current) {helper.addModel({id: '模型1',name: '模型1',url: url,model: modelRef.current,})}}return <primitive object={scene} ref={modelRef} />
}

?CityScene.tsx

import { Suspense, useRef } from 'react'
import { CityModel } from '../model/CityModal'
import { OrbitControls } from '@react-three/drei'export const CityScene = ({ modelUrl }: { modelUrl: string }) => {const controlsRef = useRef<any>(null)return (<><Suspense><CityModel url={modelUrl} />{/* 控制器 */}<OrbitControls ref={controlsRef} /></Suspense>{/* 環境光和方向光 */}<ambientLight intensity={0.5} color={0xffffff} /><directionalLightposition={[100, 200, 100]}intensity={3}castShadowcolor="#ffffff"shadow-mapSize-width={2048}shadow-mapSize-height={2048}/>{/* 環境貼圖 */}{/* 純色背景替代環境貼圖 */}<color attach="background" args={['#0a1a3a']} /></>)
}

?CityView.tsx

import { Canvas } from '@react-three/fiber'
import { CityScene } from './scene/CityScene'export const CityView = () => {const cityModelUrl = '/models/city-_shanghai-sandboxie.glb'return (<div className="w-[100vw] h-full absolute"><Canvas style={{ width: '100vw', height: '100vh' }}  shadows={true}   ><ambientLight /><CityScene modelUrl={cityModelUrl} /></Canvas></div>)
}

Home.tsx?

import { CityView } from './CityView'
import './index.less'
import { OperationPanel } from './OperationPanel'
export const Home = () => {return (<div className="screen-container"><CityView /><OperationPanel /></div>)
}

?操作面板有需要的話自取

OperationPanel.tsx

import { Space, Tag } from 'antd'
import { useModelManager, useModels } from '../../utils/viewHelper/viewContext'
import './index.less'
import * as THREE from 'three'export const OperationPanel = () => {const helper = useModelManager()const models = useModels()// 收集模型子對象const getMeshChildren = (model: THREE.Group | undefined): THREE.Mesh[] => {const meshes: THREE.Mesh[] = []model?.traverse((child) => {if (child instanceof THREE.Mesh) {meshes.push(child)}})return meshes}// 切換可見性const toggleMeshVisibility = (mesh: THREE.Mesh) => {mesh.visible = !mesh.visiblehelper.updateModelVisibility(mesh.uuid, mesh.visible) // 可選：通知管理器保存狀態}return (<div className="screen-operation absolute top-[10px] right-[30px] w-[20vw] h-[60vh] text-white z-10 ">{/* 面板標題欄 */}<div className=" px-[12px] py-3 shadow-lg"><span className="text-lg font-semibold tracking-wide">操作面板</span></div>{/* 模型列表 */}<div className="overflow-y-auto h-[calc(100%-30px)]">{models.map((model) => {const meshes = getMeshChildren(model.model)return (<div key={model.id} className="mt-[10px]">{/* 子對象列表 */}<div className="space-y-1 pl-[3px] pb-[6px]">{meshes.length > 0 ? (meshes.map((mesh) => (<divkey={mesh.uuid}// 核心樣式：狀態顏色 + 懸浮效果className={`px-[6px] my-[6px] rounded-md cursor-pointer transition-all duration-300 ease-out${/* 基礎樣式 */ 'shadow-md transform border border-transparent'}${/* 懸浮效果 */ 'hover:shadow-lg hover:shadow-blue-900/20'}${/* 顯示狀態 */ mesh.visible? 'bg-gradient-to-r from-[#47718b] to-[#3a5a70] text-[#fff] hover:border-[#8ec5fc]': 'bg-gradient-to-r from-[#2d3b45] to-[#1f2930] text-[#a0a0a0] hover:border-[#555]'}`}title={mesh.name}onClick={() => toggleMeshVisibility(mesh)}><div className="flex items-center justify-between"><span className="font-medium w-[14vw] overflow-hidden whitespace-nowrap text-ellipsis">{mesh.name}</span><Space><Tag>{mesh.type}</Tag><Tag color={mesh.visible ? 'success' : 'error'}>{' '}{mesh.visible ? '顯示中' : '已隱藏'}</Tag></Space></div></div>))) : (<div className="px-3 py-4 text-center text-gray-400 italic">無可用模型數據</div>)}</div></div>)})}</div></div>)
}