useApp

useApp 在 React 组件中取得引擎 Application，用于读取状态和触发事件。

./my-component.jsx

import { useApp } from '@playcanvas/react/hooks'

function MyComponent() {
  const app = useApp()
  
  // Access application properties
  console.log('Scene:', app.scene)
  
  // Cameras are components on entities, so look them up from the root
  const cameras = app.root.findComponents('camera')
  console.log('Cameras:', cameras)
  
  return null
}

可访问场景、根实体、系统、资源和事件等。

应用上下文

必须在 Application 后代组件中调用，缺少上下文会抛错。

🚫 缺少 <Application> 上下文

// Nope, useApp is outside <Application>
export const Wrong = () => {
  const app = useApp();
  return (
    <Application>
      <Scene/>
    </Application>
  )
}

✅ 正确的 <Application> 上下文

// Yep! `useApp` has <Application> context
const Correct = () => {
  const app = useApp();
  return <Scene />;
}

export const App = () => <Application>
  <Correct/>
  </Application>

属性

名称	类型与说明	默认值
createDevice	(canvas: any, options: any) => WebglGraphicsDevice	-
addComponentSystems	(appOptions: any) => void	-
addResourceHandles	(appOptions: any) => void	-
_batcher	any 应用的批处理管理器。	-
_destroyRequested	any	-
_inFrameUpdate	any	-
_devtoolsRegistered	any 应用是否已向开发者工具钩子注册，以便销毁时注销。	-
_librariesLoaded	any	-
_fillMode	any	-
_resolutionMode	any	-
_allowResize	any	-
_skyboxAsset	any	-
_soundManager	any	-
_visibilityChangeHandler	any	-
renderNextFrame	boolean 设为 true 后，在主循环的下一次迭代渲染场景。仅在 autoRender 为 false 时有效，渲染完成后 renderNextFrame 自动恢复为 false。	-
timeScale	number 缩放全局时间增量，默认 1。脚本、动画和物理均接收缩放后的增量，因此 0 会同时停止它们。仅暂停或减慢物理而保持其他部分运行时，使用 RigidBodyComponentSystem#timeScale。	-
maxDeltaTime	number 限制每帧时间增量的上限，默认 0.1 秒。从后台标签页返回时 dt 可能很大，此设置可避免游戏状态异常。	-
scriptsOrder	string[] 优先加载的脚本及其顺序。	-
_stats	any	-
autoRender	boolean 为 true 时每帧调用应用的渲染函数，默认为 true。画面经常保持不变时，设为 false 可大幅降低 CPU 与 GPU 负载。	-
graphicsDevice	GraphicsDevice 应用使用的图形设备。	-
root	Entity 应用的根实体。	-
scene	Scene 应用管理的场景。	-
lightmapper	Lightmapper | null 运行时光照贴图生成器。	-
loader	ResourceLoader 资源加载器。	-
assets	AssetRegistry 应用管理的资源注册表。	-
scenes	SceneRegistry 应用管理的场景注册表。	-
scripts	ScriptRegistry 应用的脚本注册表。	-
systems	ComponentSystemRegistry 应用的组件系统注册表。	-
i18n	I18n 处理本地化。	-
keyboard	Keyboard | null 键盘设备。	-
mouse	Mouse | null 鼠标设备。	-
touch	TouchDevice | null 获取触摸事件输入。	-
gamepads	GamePads | null 访问游戏手柄输入。	-
elementInput	ElementInput | null 处理 ElementComponent 的输入。	-
xr	XrManager | null 提供启动 VR/AR 会话能力的 XR 管理器。	-
init	(appOptions: AppOptions) => void 初始化应用。	-
defaultLayerWorld	Layer	-
defaultLayerDepth	Layer	-
defaultLayerSkybox	Layer	-
defaultLayerUi	Layer	-
defaultLayerImmediate	Layer	-
_initDefaultMaterial	any	-
_initProgramLibrary	any	-
batcher	BatchManager 应用的批处理管理器，用于合并场景中的网格实例，减少总绘制调用数并提高性能。	-
fillMode	string 当前画布填充模式：FILLMODE_NONE 始终保持指定尺寸；FILLMODE_FILL_WINDOW 填满窗口并改变宽高比；FILLMODE_KEEP_ASPECT 在保持宽高比的前提下尽量填满窗口。	-
stats	AppStats 应用性能统计，每次访问返回同一 AppStats 实例。引擎测量值只读，AppStats#user 可存储应用自定义可写计数器。单位、采样与 GPU 分析设置见 AppStats。	-
resolutionMode	string 当前画布分辨率模式：RESOLUTION_AUTO 在未提供宽高时随画布客户端尺寸调整；RESOLUTION_FIXED 固定分辨率。	-
configure	(url: string, callback: ConfigureAppCallback) => void 加载应用配置文件，应用属性并填充资源注册表。	-
preload	(callback: PreloadAppCallback) => void 加载资源注册表中所有标为 preload 的资源。依赖容器的渲染资源会等待引用容器注册并加载。若其 data.containerAsset 永远未注册，本方法不会调用回调或触发 preload:end。容器可在调用前以任意顺序注册，调试构建会对尚未注册容器的预加载渲染资源发出警告。	-
_preloadScripts	(sceneData: any, callback: any) => void	-
_parseApplicationProperties	(props: any, callback: any) => void	-
_width	any	-
_height	any	-
_loadLibraries	any	-
_parseScenes	any 将场景名称与 URL 添加到注册表。	-
_parseAssets	any 将资源添加到注册表。	-
start	() => void 启动应用：依次触发 start 事件、对层级中全部组件调用 initialize、触发 initialize 事件、调用 postInitialize、触发 postinitialize 事件，再启动主循环。编辑器创建的应用内部自动调用，独立使用引擎时需自行调用 start。主循环由 requestAnimationFrame 驱动；Node.js 等无此 API 的环境不自动循环，需按所需频率自行调用 update。	-
_alreadyStarted	boolean	-
inputUpdate	any 更新应用管理的全部输入设备。	-
update	(dt: number) => void 更新应用，先调用全部启用组件的 update，再调用 postUpdate，随后更新连接的输入设备状态。通常由应用主循环内部调用，无需显式调用；Node.js 等无主循环环境除外。	-
renderComposition	(layerComposition: any) => void	-
setCanvasFillMode	(mode: string, width?: number | undefined, height?: number | undefined) => void 控制画布如何填充窗口。本方法和每次 AppBase#resizeCanvas 都会调整尺寸。引擎不自行注册窗口 resize 监听器，需在自己的处理函数中调用 resizeCanvas，使相对窗口的填充模式跟随窗口变化。	-
setCanvasResolution	(mode: string, width?: number | undefined, height?: number | undefined) => void 修改画布分辨率，并设置窗口调整尺寸时的行为。	-
isHidden	() => boolean 查询应用所在窗口或标签页的可见性。	-
onVisibilityChange	any 当前标签页或窗口的可见性变化时调用。	-
resizeCanvas	(width?: number | undefined, height?: number | undefined) => { width: number; height: number; } | undefined 根据当前填充模式调整应用画布。FILLMODE_KEEP_ASPECT 保持宽高比并尽量填满窗口；FILLMODE_FILL_WINDOW 填满窗口并改变宽高比；FILLMODE_NONE 保持指定尺寸。	-
updateCanvasSize	() => void 更新 GraphicsDevice 画布尺寸以匹配页面中的画布。建议在窗口调整大小、方向变化等画布尺寸改变时调用，立即更新渲染分辨率。	-
onLibrariesLoaded	any 所有代码库加载完成后的事件处理函数。代码库由 Application 构造函数传入，在它们全部加载前，应用不会运行或加载资源包。	-
applySceneSettings	(settings: { physics: { gravity: number[]; }; render: { global_ambient: number[]; fog: string; fog_color: number[]; fog_density: number; fog_start: number; fog_end: number; gamma_correction: number; tonemapping: number; ... 52 more ...; gsplatEnableIds?: boolean; }; }) => void 将场景设置应用到当前场景，适合从非 URL 来源解析或生成设置的情况。	-
setAreaLightLuts	(ltcMat1: number[], ltcMat2: number[]) => void 为应用设置面光源 LUT 查找表。	-
setSkybox	(asset: Asset<string>) => void 为当前场景设置天空盒资源，并监听资源加载和变化事件。	-
_onSkyboxRemoved	any	-
_onSkyboxChanged	any	-
_firstBake	any	-
_firstBatch	any	-
drawLine	(start: Vec3, end: Vec3, color?: Color | undefined, depthTest?: boolean | undefined, layer?: Layer | undefined) => void 绘制单条线段，起点和终点使用世界坐标，按指定颜色进行平面着色。	-
drawLines	(positions: Vec3[], colors: Color | Color[], depthTest?: boolean | undefined, layer?: Layer | undefined) => void 渲染任意数量的独立线段。数组中的连续点不组成折线，而是每两点定义一段，因此位置与颜色数组必须等长且长度为 2 的倍数。各线段两端的颜色沿线段插值。	-
drawLineArrays	(positions: number[], colors: number[] | Color, depthTest?: boolean | undefined, layer?: Layer | undefined) => void 渲染任意数量的独立线段，每两个点定义一段，而非将数组中各点顺次连接。	-
drawMeshInstance	() => void	-
drawMesh	() => void	-
drawQuad	() => void	-
drawTexture	() => void	-
drawDepthTexture	() => void	-
destroy	() => void 在当前引擎帧更新结束时销毁应用并移除所有事件监听器；若在帧更新之外调用 destroy()，则立即销毁。	-
_gsplatSortedEvt	EventHandle	-
context	any	-
_registerSceneImmediate	any	-
_callbacks	any	-
_callbackActive	any	-
on	(name: string, callback: HandleEventCallback, scope?: object | undefined) => EventHandle 为事件注册处理函数。	-
once	(name: string, callback: HandleEventCallback, scope?: object | undefined) => EventHandle 为事件注册仅执行一次的处理函数，触发后自动移除。	-
off	(name?: string | undefined, callback?: HandleEventCallback | undefined, scope?: object | undefined) => EventHandler 解除事件处理函数。省略 callback 时移除此事件的全部回调；省略 scope 时解除所有匹配 callback 的监听。此形式适合按名称及可选回调、作用域移除监听。若只移除一个已知订阅，优先保留 EventHandler#on 或 once 返回的 EventHandle 并调用其 off，能够精确移除且无需扫描回调列表，更快。	-
fire	(name: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any, arg6?: any, arg7?: any, arg8?: any) => EventHandler 触发事件，所有额外参数都会传给监听器。	-
hasEvent	(name: string) => boolean 检查指定事件名称是否注册了处理函数。	-

相关内容

• Application：提供应用上下文。
• useParent：父实体。
• useAppEvent：订阅事件。