useParent

useParent 取得父 Entity，适用于需要操作父实体的组件。

基本用法

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

function MyComponent() {
  const parent = useParent()
  
  // Access parent entity properties
  console.log('Parent name:', parent.name)
  console.log('Parent position:', parent.position)
  
  return null
}

返回值

名称	类型与说明	默认值
anim	AnimComponent | undefined 获取此实体挂载的 AnimComponent。	-
animation	AnimationComponent | undefined 获取此实体挂载的 AnimationComponent。	-
audiolistener	AudioListenerComponent | undefined 获取此实体挂载的 AudioListenerComponent。	-
button	ButtonComponent | undefined 获取此实体挂载的 ButtonComponent。	-
camera	CameraComponent | undefined 获取此实体挂载的 CameraComponent。	-
collision	CollisionComponent | undefined 获取此实体挂载的 CollisionComponent。	-
element	ElementComponent | undefined 获取此实体挂载的 ElementComponent。	-
gsplat	GSplatComponent | undefined 获取此实体挂载的 GSplatComponent。	-
joint	JointComponent | undefined 获取此实体挂载的 JointComponent。	-
layoutchild	LayoutChildComponent | undefined 获取此实体挂载的 LayoutChildComponent。	-
layoutgroup	LayoutGroupComponent | undefined 获取此实体挂载的 LayoutGroupComponent。	-
light	LightComponent | undefined 获取此实体挂载的 LightComponent。	-
model	ModelComponent | undefined 获取此实体挂载的 ModelComponent。	-
particlesystem	ParticleSystemComponent | undefined 获取此实体挂载的 ParticleSystemComponent。	-
render	RenderComponent | undefined 获取此实体挂载的 RenderComponent。	-
rigidbody	RigidBodyComponent | undefined 获取此实体挂载的 RigidBodyComponent。	-
screen	ScreenComponent | undefined 获取此实体挂载的 ScreenComponent。	-
script	ScriptComponent | undefined 获取此实体挂载的 ScriptComponent。	-
scrollbar	ScrollbarComponent | undefined 获取此实体挂载的 ScrollbarComponent。	-
scrollview	ScrollViewComponent | undefined 获取此实体挂载的 ScrollViewComponent。	-
sound	SoundComponent | undefined 获取此实体挂载的 SoundComponent。	-
sprite	SpriteComponent | undefined 获取此实体挂载的 SpriteComponent。	-
_app	any	-
_guid	any	-
addComponent	<K extends ComponentName | (string & {})>(type: K, data?: (K extends ComponentName ? ComponentOptions<K> : object) | undefined) => (K extends ComponentName ? ComponentMap[K] : Component) | null 创建并添加组件，为实体提供渲染模型、播放声音等功能。对于内置组件，type 也决定 options 和结果类型，例如 entity.addComponent('camera', { fov: 45 }) 接受 CameraComponent 的可设置属性，并返回 CameraComponent | null。规则见 ComponentOptions，扩展应用自定义组件见 ComponentMap。	-
removeComponent	(type: ComponentName | (string & {})) => void 从实体移除组件。	-
findComponent	<K extends ComponentName | (string & {})>(type: K) => (K extends ComponentName ? ComponentMap[K] : Component) | null 在实体及全部后代中查找第一个指定类型组件。	-
findComponents	<K extends ComponentName | (string & {})>(type: K) => (K extends ComponentName ? ComponentMap[K] : Component)[] 在实体及全部后代中查找所有指定类型组件。	-
findScript	{ <T extends Script>(type: new (...args: any[]) => T): T | undefined; (name: string): Script | undefined; } 在实体及全部后代中查找第一个指定类的脚本实例，结果已具有该类类型，无需转换；也支持按脚本名称查找首个实例。	-
findScripts	{ <T extends Script>(type: new (...args: any[]) => T): T[]; (name: string): Script[]; } 在实体及全部后代中查找指定类的全部脚本实例，结果为该类实例数组，无需转换；也支持按脚本名称查找全部实例。	-
_onHierarchyStatePostChanged	any	-
findByGuid	(guid: string) => Entity | null 按 GUID 查找此实体的后代。	-
clone	() => Entity 深拷贝实体，复制完整实体层级、全部组件及后代。新实体尚未加入层级，必须手动添加。	-
_getSortedComponents	() => Component[]	-
_cloneRecursively	any	-
name	string 图节点名称，不要求唯一，默认 Untitled。	-
tags	Tags 为图节点添加标签的接口，可通过 findByTag 按标签查找。	-
localPosition	any	-
localRotation	any	-
localScale	any	-
localEulerAngles	any	-
position	any	-
rotation	any	-
eulerAngles	any	-
_scale	any	-
localTransform	any	-
_dirtyLocal	any	-
_aabbVer	any	-
_frozen	any 标记节点及其子级完全跳过层级同步。引擎按需自动冻结或解冻对象，将动态与静止节点分到不同子层级可显著减少同步时间。	-
worldTransform	any	-
_dirtyWorld	any	-
_worldScaleSign	any 世界变换是否包含负缩放的缓存值：0 表示脏状态需重算，1 表示无负缩放，-1 表示有负缩放。	-
_normalMatrix	any	-
_dirtyNormal	any	-
_right	any	-
_up	any	-
_forward	any	-
_parent	any	-
_children	GraphNode[]	-
_graphDepth	any	-
_enabled	any 实体自身的启用状态。禁用时，实体及全部子级均不参与更新。	-
_enabledInHierarchy	any 实体在层级中的启用状态，只有自身及直到场景根节点的所有父级都启用时才为 true。	-
right	Readonly<Vec3> 获取图节点局部 X 轴在世界空间中的归一化向量。	-
up	Readonly<Vec3> 获取图节点局部 Y 轴在世界空间中的归一化向量。	-
forward	Readonly<Vec3> 获取图节点局部负 Z 轴在世界空间中的归一化向量。	-
enabled	boolean 设置或获取 GraphNode 的启用状态。如果某个父级已禁用，不会产生额外影响；若所有父级启用，则新状态会激活或停用该节点下所有自身启用的子级。	-
parent	GraphNode | null 获取图节点父级。	-
path	string 获取图节点相对层级根节点的路径。	-
root	GraphNode 获取此节点最上层祖先。	-
children	readonly GraphNode[] 获取图节点子级。修改层级请使用 addChild、insertChild、removeChild 或 reparent。	-
graphDepth	number 获取此子节点在图中的深度。为提高性能，仅在加入新父级时重新计算，单纯从图中移除时不重算。	-
_notifyHierarchyStateChanged	(node: GraphNode, enabled: boolean) => void	-
_onHierarchyStateChanged	(enabled: boolean) => void 实体自身或任一父级的 enabled 标志变化时调用。	-
_cloneInternal	any	-
destroy	() => void 销毁图节点及全部后代。先从层级移除节点，再递归对后代执行相同操作，最后触发 destroy 事件。	-
find	(attr: string | FindNodeCallback, value?: any) => GraphNode[] 在图节点及全部后代中查找符合条件的节点。	-
findOne	(attr: string | FindNodeCallback, value?: any) => GraphNode | null 在图节点及全部后代中查找首个符合条件的节点。	-
findByTag	(...query: any[]) => GraphNode[] 返回符合查询的所有图节点。单个字符串或逗号分隔字符串表示匹配任一标签；标签数组表示必须同时具有数组中的全部标签。	-
findByName	(name: string) => GraphNode | null 通过深度优先搜索，返回图中首个具有指定名称的节点。	-
findByPath	(path: string | string[]) => GraphNode | null 通过深度优先搜索，按完整路径返回首个节点。路径格式为 parent/child/sub-child。	-
forEach	(callback: ForEachNodeCallback, thisArg?: object | undefined) => void 对图节点及全部后代分别执行一次指定函数。	-
isDescendantOf	(node: GraphNode) => boolean 检查节点是否为另一节点的后代。	-
isAncestorOf	(node: GraphNode) => boolean 检查节点是否为另一节点的祖先。	-
getEulerAngles	() => Readonly<Vec3> 获取 GraphNode 世界空间欧拉角旋转，单位度，顺序 XYZ。返回值应视为只读，设置世界旋转请使用 setEulerAngles。	-
getLocalEulerAngles	() => Readonly<Vec3> 获取 GraphNode 局部空间欧拉角旋转，单位度，顺序 XYZ。返回值应视为只读，设置局部旋转请使用 setLocalEulerAngles。	-
getLocalPosition	() => Readonly<Vec3> 以 Vec3 获取 GraphNode 局部位置，返回向量应视为只读，更新请使用 setLocalPosition。	-
getLocalRotation	() => Readonly<Quat> 以 Quat 获取 GraphNode 局部旋转，返回四元数应视为只读，更新请使用 setLocalRotation。	-
getLocalScale	() => Readonly<Vec3> 以 Vec3 获取 GraphNode 局部缩放，返回向量应视为只读，更新请使用 setLocalScale。	-
getLocalTransform	() => Readonly<Mat4> 获取图节点局部变换矩阵，即相对于父节点世界变换矩阵的变换。	-
getPosition	() => Readonly<Vec3> 以 Vec3 获取 GraphNode 世界位置，返回值应视为只读，设置请使用 setPosition。	-
getRotation	() => Readonly<Quat> 以 Quat 获取 GraphNode 世界旋转，返回值应视为只读，设置请使用 setRotation。	-
getWorldTransform	() => Readonly<Mat4> 获取图节点世界变换矩阵。	-
remove	() => void 将图节点从当前父级移除。	-
reparent	(parent: GraphNode, index?: number | undefined) => void 将图节点从当前父级移除，并作为子级加入新父级。	-
setLocalEulerAngles	{ (x: number, y: number, z: number): void; (angles: Vec3): void; } 使用 XYZ 顺序的欧拉角设置图节点局部旋转。	-
setLocalPosition	{ (x: number, y: number, z: number): void; (position: Vec3): void; } 设置图节点局部位置。	-
setLocalRotation	{ (x: number, y: number, z: number, w: number): void; (rotation: Quat): void; } 设置图节点局部旋转。	-
setLocalScale	{ (x: number, y: number, z: number): void; (scale: Vec3): void; } 设置图节点局部缩放。	-
_dirtifyLocal	any	-
_unfreezeParentToRoot	any	-
_dirtifyWorld	any	-
_dirtifyWorldInternal	any	-
setPosition	{ (x: number, y: number, z: number): void; (position: Vec3): void; } 设置图节点世界位置。	-
setRotation	{ (x: number, y: number, z: number, w: number): void; (rotation: Quat): void; } 设置图节点世界旋转。	-
setPositionAndRotation	(position: Vec3, rotation: Quat) => void 同时设置图节点世界位置和旋转，比独立设置两者更快。	-
setEulerAngles	{ (x: number, y: number, z: number): void; (angles: Vec3): void; } 使用 XYZ 顺序的欧拉角设置图节点世界旋转。	-
addChild	(node: GraphNode) => void 向子级列表添加新节点并更新其父级引用，若已有父级则先从旧父级移除。子级保留现有局部变换，并相对新父级解释，因此先按世界位置放置再添加时看起来会移动。应先添加再设置变换，或通过 GraphNode#setPosition 重新设置世界位置。	-
insertChild	(node: GraphNode, index: number) => void 在指定索引插入子节点并更新父级引用，若已有父级则先从旧父级列表移除。	-
_prepareInsertChild	any 为节点插入新父级做准备，并从原父级移除。	-
_fireOnHierarchy	any 向节点的全部子级触发事件。name 事件仅在首个根节点触发，nameHierarchy 在全部子级触发。	-
_onInsertChild	any 节点插入某节点子级列表时调用。	-
_updateGraphDepth	any 递归遍历层级，更新各节点的图深度。	-
removeChild	(child: GraphNode) => void 从子级列表移除节点并更新其父级引用。这只解除挂接，不会禁用：子树仍可能报告 enabled === true，光源、相机、脚本和声音继续运行。停用请设 enabled=false，彻底移除则销毁实体。	-
_sync	() => void	-
lookAt	{ (x: number, y: number, z: number, ux?: number | undefined, uy?: number | undefined, uz?: number | undefined): void; (target: Vec3, up?: Vec3 | undefined): void; } 重新定向图节点，使负 Z 轴朝向目标。up 向量不能与节点到目标的方向平行。默认 up 下直视正上或正下、或目标等于自身位置时，基底退化，旋转会静默重置为单位旋转，丢失原朝向。此时应传入其他 up 向量。	-
translate	{ (x: number, y: number, z: number): void; (translation: Vec3): void; } 在世界空间中按指定平移向量移动图节点。	-
translateLocal	{ (x: number, y: number, z: number): void; (translation: Vec3): void; } 在局部空间中按指定平移向量移动图节点。	-
rotate	{ (x: number, y: number, z: number): void; (rotation: Vec3): void; } 在世界空间中按指定欧拉角旋转图节点，单位度，顺序 XYZ。	-
rotateLocal	{ (x: number, y: number, z: number): void; (rotation: Vec3): void; } 在局部空间中按指定欧拉角旋转图节点，单位度，顺序 XYZ。	-
_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 检查指定事件名称是否注册了处理函数。	-

要求

必须在 Entity 后代组件中调用，否则抛错。

// ✅ Correct usage
<Entity>
  <MyComponent /> {/* useParent works here */}
</Entity>

// ❌ Incorrect usage
<MyComponent /> {/* useParent will throw an error */}

示例

访问实体属性

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

function EntityInfo() {
  const parent = useParent()
  
  return (
    <div>
      <p>Entity Name: {parent.name}</p>
      <p>Position: {parent.position.toString()}</p>
      <p>Rotation: {parent.rotation.toString()}</p>
      <p>Scale: {parent.scale.toString()}</p>
    </div>
  )
}

相关内容

• Entity：提供上下文。
• useApp：应用实例。
• Entity API：引擎文档。