5.2 KiB
5.2 KiB
Web3D 场景 SDK 使用说明
本 SDK 用于在 Web 场景中快速完成三维展示与交互，核心能力包括：相机修改、灯光调参、环境贴图切换、按配置渲染热点、热点驱动抛出事件、模型热加载/热销毁/热替换，以及按部件切换材质。
功能概览
- 相机控制：支持位置/目标点/FOV/远近裁剪的即时更新，带缓动动画。
- 灯光调参：主光、辅光、环境光强度、颜色、方向、阴影开关与软硬度。
- 环境贴图：HDRI 切换、曝光度、旋转（偏航/俯仰）、模糊度。
- 热点系统：基于配置渲染热点 UI，可按 click/hover/focus 抛出事件。
- 模型热更新：按 ID 进行加载、销毁、替换，支持队列并行与完成回调。
- 材质切换：按部件或分组应用/还原材质，支持预设表与回滚。
- 事件总线：统一事件接口，便于业务侧订阅热点/相机/模型状态。
快速开始
npm install your-web3d-sdk
import { createViewer } from 'your-web3d-sdk'
const sdk = await createViewer({
container: '#viewer',
assetsBase: '/assets',
background: '#0f172a',
})
// 加载初始场景或模型
await sdk.model.load({ id: 'scene', url: '/models/showroom.glb' })
基础生命周期
- 初始化 viewer：
createViewer({ container }) - 加载模型或场景：
sdk.model.load(...) - 设置环境贴图/灯光：
sdk.environment.setHDRI(...)、sdk.lights.update(...) - 渲染热点：
sdk.hotspot.render(config.hotspots) - 订阅事件：
sdk.on('hotspot:click', handler) - 在业务侧按需调用相机/材质/模型热更新 API
相机控制
// 直接设置视角
sdk.camera.set({
position: [2.5, 1.6, 3.2],
target: [0, 0.8, 0],
fov: 45,
near: 0.1,
far: 200,
})
// 平滑过渡到指定视角
sdk.camera.animateTo(
{ position: [1.2, 1, 2.4], target: [0, 0.8, 0], fov: 50 },
{ duration: 0.8, easing: 'easeOutCubic' }
)
灯光调参
// 更新主方向光
sdk.lights.update('key', {
intensity: 1.5,
color: '#ffffff',
direction: [0.3, -1, 0.25],
castShadow: true,
})
// 环境光/辅光
sdk.lights.update('fill', { intensity: 0.6, color: '#dfe8ff' })
sdk.lights.update('ambient', { intensity: 0.25 })
环境贴图
await sdk.environment.setHDRI('/envs/showroom_2k.hdr', {
exposure: 1.1,
rotation: [0, 45, 0], // yaw/pitch/roll
blur: 0.2,
})
热点渲染与事件
const hotspots = [
{
id: 'engine',
position: [0.8, 0.6, -0.2],
icon: 'info',
label: '发动机舱',
event: 'show-engine',
payload: { part: 'engine' },
},
{
id: 'door',
position: [1.1, 0.9, 0.4],
icon: 'action',
label: '开启车门',
event: 'toggle-door',
payload: { side: 'left' },
},
]
sdk.hotspot.render(hotspots)
sdk.hotspot.on('click', ({ id, payload }) => {
// 业务侧根据 id/payload 触发操作
})
sdk.hotspot.on('hover', ({ id, hovering }) => {
// hover 高亮或提示
})
事件命名建议（可按需扩展）：
hotspot:click、hotspot:hover、hotspot:focushotspot:rendered（所有热点就绪）
模型热加载 / 热销毁 / 热替换
// 加载
await sdk.model.load({ id: 'car', url: '/models/car.glb', draco: true })
// 销毁
await sdk.model.destroy('car')
// 替换（内部自动销毁旧实例并加载新实例）
await sdk.model.replace('car', { url: '/models/car-white.glb' })
可以通过 sdk.model.on('loaded' | 'replaced' | 'destroyed', handler) 监听模型状态。
材质切换
// 应用材质预设
sdk.material.apply({
target: 'body', // 部件或分组名称
material: 'paint/blue', // 预设 Key
})
// 批量切换
sdk.material.batch([
{ target: 'wheel', material: 'rim/chrome' },
{ target: 'glass', material: 'glass/clear' },
])
// 还原默认材质
sdk.material.reset('body')
推荐的配置结构
{
"camera": { "position": [2.5, 1.6, 3.2], "target": [0, 0.8, 0], "fov": 45 },
"environment": { "hdr": "/envs/showroom_2k.hdr", "exposure": 1.1, "rotation": [0, 45, 0] },
"lights": {
"key": { "intensity": 1.5, "color": "#ffffff", "direction": [0.3, -1, 0.25] },
"fill": { "intensity": 0.6, "color": "#dfe8ff" },
"ambient": { "intensity": 0.25 }
},
"hotspots": [
{ "id": "engine", "position": [0.8, 0.6, -0.2], "icon": "info", "label": "发动机舱", "event": "show-engine" },
{ "id": "door", "position": [1.1, 0.9, 0.4], "icon": "action", "label": "开启车门", "event": "toggle-door" }
]
}
事件清单（示例）
- 相机：
camera:changed - 热点：
hotspot:click、hotspot:hover、hotspot:rendered - 模型：
model:loaded、model:replaced、model:destroyed - 材质：
material:applied、material:reset
订阅方式：
sdk.on('hotspot:click', (evt) => console.log(evt))
sdk.off('hotspot:click', handler) // 移除监听
调试建议
- 启用
sdk.debug(true)查看加载、事件、帧率等日志。 - 逐步应用配置：先确认相机与灯光，再添加环境贴图与热点，最后再做材质/模型热更新。
- 热更新前后记录 ID/实例，避免重复销毁或遗漏解绑事件。