<pc-node>

<pc-node> 绑定 <pc-model> 实例化树内的节点，声明覆盖值，无需改 GLB 即可隐藏、移动、添加组件或挂接内容。

pc-entity 创建实体，pc-node 则引用模型已创建的实体。name 用于查找，绝非重命名。

隐藏、姿态、换材质和挂接的完整案例详见调整模型。

用法

必须位于 <pc-model> 内，可直接或嵌套于另一个 pc-node。
可包含多个 pc-node，名称仅在当前绑定节点子树内解析。
可包含多个 <pc-entity>，创建为绑定节点子项，充当挂点。
支持与实体相同的组件，包括碰撞、灯光、脚本等。节点已有同类型时不重复添加，例如网格已有 Render，再加 pc-render 会警告且不操作。

属性

属性	类型	默认值	说明
`enabled`	Boolean（布尔）	原始值	覆盖启用状态
`index`	Number（数字）	-	同名匹配中按深度优先的零基索引，有歧义时必需，否则可省略
`material-overrides`	String（字符串）	原始值	JSON 将选择器映射到 pc-material id，覆盖 Render 材质，详见覆盖材质
`name`	String（字符串）	-	在所属模型或外层节点范围内查找的名称
`position`	Vector3	原始值	局部位置 X Y Z
`rotation`	Vector3	原始值	局部角度制欧拉角 X Y Z
`scale`	Vector3	原始值	局部缩放 X Y Z
`tags`	String（字符串）	原始值	逗号分隔标签，替换原列表

恢复模型原始值

除 name 和 index 外均为覆盖。存在时替换原始值，缺省不改变；运行时移除，或将对应 property 设为 null，会恢复模型原值，而非引擎默认，因此表中没有固定默认。

覆盖不是叠加，position="0 1 0" 将局部 Y 直接设为 1，与导出值无关。

查找节点

name 匹配加载后名称，需要在范围内唯一。嵌套节点将内层查询限制在外层子树，适合局部唯一名称。

同名不唯一时不绑定，并警告所有候选路径，使用 index 选择：

pc-node 'Wheel' is ambiguous in model 'car' - specify index: [0] Body/Wheel_FL/Wheel, [1] Body/Wheel_FR/Wheel

这是刻意行为，避免静默改错节点，以及重新导出新增同名后破坏原文档。

名称无匹配、索引越界或节点已被另一个 pc-node 绑定，也会警告且永不就绪。名称两次编辑距离内有候选时还会建议，便于发现拼写错误。

成功绑定后才就绪，后代也随之等待。模型重载或修改 name 重定向时，重新解析并将覆盖、组件和挂接内容应用到新节点。

覆盖材质

material-overrides 以 JSON 将选择器映射到 <pc-material> id。外层应使用单引号，因为 JSON 内部需要双引号：

<pc-model asset="car">
    <pc-node name="Body" material-overrides='{"name:CarPaint": "candy-red", "index:3": "smoked-glass"}'></pc-node>
</pc-model>

两种选择器都作用于绑定节点 Render 的网格实例：

选择器	目标
`name:X`	所有材质名为 X 的实例
`index:N`	Render 列表中从 0 开始的第 N 个实例

映射为稀疏覆盖，无规则匹配则保留原材质。两类同时命中时 index 优先，因此可按名统一替换，再按索引指定例外。

通过模型 hierarchy()查看名称和索引。名称可重复，Untitled、defaultGlbMaterial 及 -flatShaded 副本均不保证唯一，不明确时使用 index。

名称按首次应用映射时捕获的原始分配匹配，不会匹配其他规则刚替换的材质，之后重命名也不改变目标。移除属性、property 设 null 或空对象都会恢复捕获的分配。

只针对模型原有 Render。绑定到没有 Render 的分组节点会警告，不操作；子 pc-render 新增的组件不是覆盖目标。

规则逐项验证，无效项警告并忽略，其余继续。包括无前缀、index 非非负整数、索引越界、名称无匹配，以及材质 id 无匹配。整体不是 JSON 对象，例如格式错误或数组，则视为缺省并恢复原分配，不保留旧映射。

映射之后才加入的材质不会自动发现，应在元素存在后重新赋值。

事件

pc-node 支持与实体相同的指针事件，作用于被绑定几何体。绑定使部件成为拾取目标，未绑定部件命中则交给 pc-model。

事件	说明
`click`	主按钮在节点上按下并释放
`pointercancel`	浏览器取消按下时在起始节点触发，例如触摸转为滚动，不产生 click
`pointerdown`	在节点上按下
`pointerenter`	从整个子树之外进入节点或后代，不冒泡
`pointerleave`	离开节点及全部后代，不冒泡
`pointermove`	在节点上移动
`pointerout`	离开节点，relatedTarget 为目标元素
`pointerover`	进入节点，relatedTarget 为来源元素
`pointerup`	在节点上释放

事件沿 DOM 元素树传播，不沿模型节点树。命中绑定节点下几何体时，以此 pc-node 为目标，除非更近的 pc-node 代表该部分。后者只有在标记中嵌套于前者时才冒泡到它；同级则直接冒泡到模型。

onclick 和 onpointer* 与实体一致，包括按下释放命中不同部件时的点击解析。

示例

GLB 有 play 橙色镂空外壳和 canvas 深色内盒，还残留空 Light 与 Camera，可用 hierarchy() 查看。节点绑定 play，通过 material-overrides 将橙色换蓝。可改绑 canvas，或 enabled=false 隐藏外壳。拖动环绕：

实时示例

<pc-app>
    <pc-asset src="https://cdn.jsdelivr.net/npm/[email protected]/scripts/esm/camera-controls.mjs"></pc-asset>
    <pc-asset src="https://developer.playcanvas.com/assets/playcanvas-cube.glb" id="cube"></pc-asset>
    <pc-material id="repaint" name="Repaint" diffuse="#4a9eff"></pc-material>
    <pc-scene>
        <pc-entity name="camera" position="0 0 3">
            <pc-camera clear-color="#1d1f2b"></pc-camera>
            <pc-script>
                <pc-script-instance name="cameraControls" enable-pan="false" zoom-range="1.5 6"></pc-script-instance>
            </pc-script>
        </pc-entity>
        <pc-entity name="light" rotation="45 30 0">
            <pc-light intensity="2"></pc-light>
        </pc-entity>
        <pc-model asset="cube">
            <!-- Bind the node named "play" and swap in the repaint material -->
            <pc-node name="play" material-overrides='{"index:0": "repaint"}'></pc-node>
        </pc-model>
    </pc-scene>
</pc-app>

JavaScript 接口

可以通过 NodeElement API创建和操作元素。

entity 是绑定节点。state 为 pending 表示无 name 或模型未实例化，bound 成功，missing、ambiguous、duplicate 分别为解析失败。path 是相对查询范围的斜杠路径，未绑定为 null。可据此断言绑定，无需只看控制台：

import { whenReady } from '@playcanvas/web-components';

const node = await whenReady('pc-node[name="Roof"]');
console.log(node.state, node.path); // 'bound' 'Body/Roof'

materialOverrides 是覆盖材质映射对象形式，无需 JSON 字符串：

const body = await whenReady('pc-node[name="Body"]');
body.materialOverrides = { 'name:CarPaint': 'candy-red' };
body.materialOverrides = null; // back to the authored materials

元素保存冻结副本，之后修改原对象不生效，应重新赋新映射。property 不反映回 attribute，与其他覆盖属性一致。

另请参阅

<pc-model>：所属模型。
<pc-material>：可替换材质。
<pc-entity>：挂接新内容。
加载模型：查看内部节点。

示例：产品查看器、布娃娃和车辆物理。

属性​

查找节点​

覆盖材质​

事件​

示例​

JavaScript 接口​

另请参阅​

属性

查找节点

覆盖材质

事件

示例

JavaScript 接口

另请参阅