<needle-engine> Web 组件内置了一系列属性，可用于修改加载场景的外观和感觉，而无需直接添加或编辑 three.js 场景。 下表列出了其中最重要的属性：

属性描述
加载
src一个或多个 glTF 或 glb 文件的路径。
支持的类型包括 string、string[] 或字符串化数组（以 , 分隔）
dracoDecoderPathDraco 解码器的 URL
dracoDecoderTypeDraco 解码器类型。选项包括 wasm 或 js。参见 three.js documentation
ktx2DecoderPathKTX2 解码器的 URL
渲染
background-color可选，用作背景颜色的 hex 颜色值。示例：rgb(255, 200, 100)，#dddd00
background-image可选，天空盒图像（背景图像）的 URL 或预设字符串：studio, blurred-skybox, quicklook, quicklook-ar
background-blurriness可选，用于 background-image 的模糊度值，介于 0（不模糊）和 1（最大模糊）之间。示例：background-blurriness="0.5"
environment-image可选，环境图像（环境光）的 URL 或预设字符串：studio, blurred-skybox, quicklook, quicklook-ar
contactshadows可选，渲染接触阴影
tone-mapping可选，支持的值包括 none, linear, neutral, agx
tone-mapping-exposure可选数字，例如使用 tone-mapping-exposure="1.5" 增加曝光度，需要设置 tone-mapping
交互
autoplay添加或设置为 true 以自动播放动画，例如 <needle-engine autoplay
camera-controls添加或设置为 true 以在场景中未找到相机控制器时自动添加 OrbitControls
auto-rotate添加此属性以启用自动旋转（仅与 camera-controls 一起使用）
事件
loadstart加载开始时要调用的函数名称。注意参数是 (ctx:Context, evt:Event)。您可以调用 evt.preventDefault() 以隐藏默认加载叠加层
progress加载更新时要调用的函数名称。onProgress(ctx:Context, evt: {detail: {context:Context, name:string, index:number, count:number, totalProgress01:number}) { ... }
loadfinished加载完成时要调用的函数名称
加载显示更改 Needle Engine 加载显示外观的可用选项。使用 ?debugloadingrendering 可更轻松地编辑
loading-style选项包括 light 或 dark
loading-background-colorPRO — 更改加载背景颜色（例如 =#dd5500）
loading-text-colorPRO — 更改加载文本颜色
loading-logo-srcPRO — 更改加载标志图像
primary-colorPRO — 更改主要加载颜色
secondary-colorPRO — 更改次要加载颜色
hide-loading-overlayPRO — 不显示加载叠加层，在 Needle Engine > 3.17.1 中添加
内部
hash内部使用，附加到正在加载的文件以强制更新（例如，当浏览器缓存了 glb 文件时）。不应手动编辑。

示例

<!-- 设置要加载的自定义 glb 文件的路径 -->
<needle-engine src="path/to/your.glb"></needle-engine>
<!-- 覆盖 draco 解码器的位置 -->
<needle-engine src="path/to/your.glb" dracoDecoderPath="path/to/draco/folder"></needle-engine>

设置环境图像、播放动画和自动相机控制。在 stackblitz 上查看实时示例

<needle-engine
      camera-controls
      auto-rotate
      autoplay
      skybox-image="https://dl.polyhaven.org/file/ph-assets/HDRIs/hdr/1k/industrial_sunset_puresky_1k.hdr"
      environment-image="https://dl.polyhaven.org/file/ph-assets/HDRIs/hdr/1k/industrial_sunset_puresky_1k.hdr"
      src="https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/DamagedHelmet/glTF-Embedded/DamagedHelmet.gltf"
      >
      </needle-engine>

当 needle-engine 上下文完成加载时接收事件：

<needle-engine loadfinished="onLoadFinished"> </needle-engine>
<script>
    function onLoadFinished() {
        console.log("Needle Engine has finished loading");
    }
</script>

自定义加载样式 (PRO)

通过在 <needle-engine> web 组件上设置相应的属性，您可以轻松修改 Needle Engine 的外观。详细信息请参见上表。

custom loading在 github 上查看代码

页面由 AI 自动翻译