用 HTML 声明式构建 WebXR/VR/AR 与…

需要在浏览器中低 JavaScript 构建 3D、VR、AR、360 查看器或沉浸式 Web 内容时使用。

适用场景

解决思路

1. 使用实体-组件-系统（ECS）：用 <a-entity> 作为容器，通过 geometry、material、position、rotation 等组件添加功能/外观；用 <a-box>、<a-sphere> 等 primitive 作为常见组合的简写。
2. 搭建场景：在 HTML head 引入 <script src='https://aframe.io/releases/1.7.1/aframe.min.js'></script>，在 body 中使用 <a-scene> 作为根，内部放置 <a-box>、<a-sphere>、<a-cylinder>、<a-plane>、<a-sky> 等实体；场景会自动注入默认相机（position: 0 1.6 0）、look-controls 和 wasd-controls。
3. 配置默认相机：在无自定义相机时，A-Frame 自动注入 <a-entity camera='active: true' look-controls wasd-controls position='0 1.6 0'>。
4. 配置自定义相机：使用 <a-camera position='0 2 5' look-controls wasd-controls='acceleration: 50'></a-camera>。
5. 使用相机 rig 实现独立移动和旋转：创建 <a-entity id='rig' position='0 0 0'>，内部放 <a-camera look-controls></a-camera>，将移动应用到 rig 而不是相机。
6. 创建 VR 相机 rig 和控制器：在 <a-entity id='rig'> 内放 <a-camera position='0 1.6 0'></a-camera>，再添加左右手实体 <a-entity hand-controls='hand: left' laser-controls='hand: left'></a-entity> 和 right 版本。
7. 添加环境光：<a-entity light='type: ambient; color: #BBB; intensity: 0.5'></a-entity>。
8. 添加方向光：<a-entity light='type: directional; color: #FFF; intensity: 0.8' position='1 2 1'></a-entity>。
9. 添加点光：<a-entity light='type: point; color: #F00; intensity: 2; distance: 50' position='0 3 0'></a-entity>。
10. 添加聚光：<a-entity light='type: spot; angle: 45; intensity: 1.5' position='0 5 0' rotation='-90 0 0'></a-entity>。
11. 使用标准材质：<a-sphere material='color: #FF0000; metalness: 0.5; roughness: 0.3' position='0 1 -3'></a-sphere>。
12. 使用纹理材质：在 <a-assets> 中放 <img id='woodTexture' src='wood.jpg'>，然后用 <a-box material='src: #woodTexture' position='0 1 -3'></a-box>。
13. 使用平面着色：<a-plane material='shader: flat; color: #4CC3D9'></a-plane>。
14. 制作属性动画：<a-box position='0 1 -3' animation='property: rotation; to: 0 360 0; loop: true; dur: 5000'></a-box>。
15. 制作多组动画：使用 animation__* 命名，如 animation__position、animation__rotation、animation__scale，分别设置 property、to、dir、loop、dur。
16. 制作事件驱动动画：使用 startEvents，如 animation__mouseenter='property: scale; to: 1.2 1.2 1.2; startEvents: mouseenter'，以及 mouseleave、click 版本。
17. 预加载资源：在 <a-scene> 内用 <a-assets> 放 <img>、<video>、<audio>、<a-asset-item> 和 <a-mixin>；通过 id 引用，如 gltf-model='#tree'、mixin='redMaterial'、<a-sky src='#skyTexture'>。
18. 注册自定义组件：用 AFRAME.registerComponent('rotate-on-click', { schema: { speed: {type: 'number', default: 1} }, init: function() {...}, tick: function(time, timeDelta) {...} })；在实体上用 rotate-on-click='speed: 2'。
19. 实现 VR 控制器抓取：为左右手添加 hand-controls 和 laser-controls；给可抓取对象加 class='grabbable'；注册 grabbable 组件监听 triggerdown/triggerup/gripdown/gripup；gripdown 时用 controllerEl.object3D.attach(el.object3D) 挂载，gripup 时用 sceneEl.object3D.attach(el.object3D) 放回场景；用 document.querySelectorAll('.grabbable') 应用组件。
20. 创建 360° 图像库：用 <a-sky id='image-360' src='#city' rotation='0 -130 0'> 显示全景；在 <a-assets> 预加载全景图、缩略图和点击音效；创建菜单实体，每个链接用 plane geometry、flat material、sound 和 event-set__mouseenter/leave/click 切换 _target: #image-360; material.src；相机加 <a-cursor raycaster='objects: .link'>。
21. 实现 AR Hit Testing：用 <a-scene webxr='optionalFeatures: hit-test, dom-overlay; overlayElement: #overlay' ar-hit-test='target: #furniture; type: footprint'>；预加载模型 <a-asset-item id='chair' src='chair.gltf'>；放置对象 <a-entity id='furniture' gltf-model='#chair' scale='0.5 0.5 0.5'>；添加 overlay div；监听 enter-vr、ar-hit-test-start、ar-hit-test-achieved、ar-hit-test-select 更新提示；监听 exit-vr 重置。
22. 实现鼠标/注视交互：给交互对象加 class='interactive'；用 event-set__mouseenter/leave/click 改变颜色或缩放；相机加 <a-cursor raycaster='objects: .interactive' fuse='true' fuse-timeout='1500'>；用 JS 监听 click 并访问 evt.detail.intersection.point。
23. 动态生成场景：用 document.createElement('a-entity')，setAttribute 设置 geometry、material、position、animation；appendChild 到 scene；循环生成网格；监听 componentchanged；通过 el.object3D 直接操作 Three.js 对象。
24. 创建环境和天空盒：引入 sky-background 和 aframe-extras 脚本；用 <a-sky-background top-color='#4A90E2' bottom-color='#87CEEB'> 渐变天空；或 <a-sky src='sky.jpg' rotation='0 -130 0'>；用 ocean 组件（density: 20; width: 50; depth: 50; speed: 4）创建海洋；用 particle-system='preset: snow; particleCount: 2000; color: #FFF' 创建粒子；添加环境光和方向光。
25. 加载 GLTF 模型：在 <a-assets> 中用 <a-asset-item id='robot' src='robot.gltf'> 和 building.glb；用 <a-entity gltf-model='#robot' position='0 0 -3' scale='0.5 0.5 0.5' animation='...'>；用 animation-mixer='clip: *; loop: repeat' 播放模型动画；监听 model-loaded 和 model-error，遍历 evt.detail.model 检查 mesh。
26. 与 Three.js 集成：通过 document.querySelector('a-scene').object3D 获取 Three.js 场景；通过 box.object3D 获取实体 Three.js 对象；直接设置 position、rotation；用 new THREE.BoxGeometry 等创建对象并 scene.add(mesh)。
27. 与 GSAP 集成：引入 gsap.min.js；用 gsap.to(box.object3D.position, {x:3, y:2, z:-5, duration:2, ease:'power2.inOut'})；gsap.to(box.object3D.rotation, {y: Math.PI*2, duration:3, repeat:-1, ease:'none'})；gsap.to(box.components.material.material, {opacity:0.5, duration:1})。
28. 与 React 集成：import 'aframe'；在 useRef 的 <a-scene> 中；useEffect 中动态创建实体，appendChild；监听 enter-vr；返回 JSX 包含 <a-box> 等。
29. 性能实践：使用 <a-assets> 预加载图片、视频、模型。
30. 性能实践：池化实体，注册 bullet-pool 组件，预创建 20 个 bullet，隐藏，getBullet/returnBullet 复用。
31. 性能实践：优化几何，远处用低多边形（segments-width='8' segments-height='6'），近处用高多边形（segments-width='32' segments-height='32'）。
32. 性能实践：限制 draw calls，用 Three.js InstancedMesh 创建 instanced-trees 组件，用 ConeGeometry 和 MeshStandardMaterial，setMatrixAt 定位 100 棵树，scene.add(mesh)。
33. 性能实践：节流 tick()，在组件 init 设 lastUpdate 和 updateInterval=100，tick 中判断 time - lastUpdate >= updateInterval 才执行昂贵操作。
34. 性能实践：在 <a-scene stats> 上启用 stats 组件监控 FPS。
35. 解决实体不出现：等待 scene loaded 事件后再创建实体；设置 position 在相机前；检查 scale、opacity、frustum；console.log position 和 parentNode。
36. 解决事件不触发：给相机加 <a-cursor raycaster='objects: .interactive'>；给交互对象加 class；或用 <a-entity raycaster='objects: [geometry]' cursor>。
37. 解决性能下降：对象池化、简化几何、优化纹理、节流更新；可注册 optimize-far-entities 组件，在 tick 中计算到相机距离，隐藏 distance >= 50 的实体。
38. 解决 Z-Fighting：将重叠表面稍微偏移（如 0.01、0.02）；或设置 object3D.renderOrder = 1。
39. 解决移动 VR 性能：<a-scene renderer='maxCanvasWidth: 1920; maxCanvasHeight: 1920'>；低多边形模型；限制灯光为环境光+方向光；必要时 <a-scene renderer='antialias: false'>。
40. 解决资源加载问题/CORS：在 <a-assets> 中用 crossorigin='anonymous'；监听 assets 的 loaded 和 timeout 事件；监听 img 的 error 并提供 fallback。

适用边界 · 注意事项

• 当需要完全底层、非声明式的 Three.js 控制时，A-Frame 可能不够灵活。
• 当项目强制使用 Babylon.js 或 React Three Fiber 等其他 3D 架构时，不应改用 A-Frame。
• AR hit testing 依赖设备/浏览器支持 WebXR，不支持该能力的设备无法使用。