属性
所有 PlayCanvas Web Component 都通过 HTML 属性配置，遵循同一组约定。掌握后即可预测各标签的行为。
通用约定
属性遵循三条规则：
| 标记 | 结果 |
|---|---|
| 设置合法值 | 应用该值 |
| 属性不存在，或运行时移除 | 应用引擎默认值 |
| 设置无效值 | 控制台警告说明问题，并应用默认值 |
各标签表格的 Default 列表示属性缺省时的值。移除会恢复默认，因此可以在开发者工具或通过 setAttribute()、removeAttribute() 动态切换，场景会响应更新。
无效值不会传到引擎，控制台会指出属性和期望格式。编写时保持控制台打开，可及时发现拼写错误。
以下属性稍有不同：
<pc-node>覆盖模型原始节点状态，缺省时恢复模型制作时的值，而非引擎默认。- 资源 ID、材质 ID和实体引用通常在移除时保留最后解析结果。例如移除 pc-render 的 material 不会更换当前材质。空引用有特殊含义时，例如 pc-joint 没有 entity-b，各标签页会明确说明。
- 某些属性仅在启动时读取一次，例如 pc-app 图形选项和多数 pc-asset 属性。各标签页的读取时机说明会列出。
- 脚本属性直接设置脚本，无效或移除时保留当前脚本值。
类型列
各属性表的 Type 列表示书写形式，定义如下：
| 类型 | 写法 |
|---|---|
| Boolean（布尔） | true、false 或仅出现属性，详见布尔值 |
| Number（数字） | 任意有限数，详见数字 |
| Enum（枚举） | 描述中列出的固定名称之一，详见枚举 |
| Vector2、Vector3、Vector4 | 两个、三个或四个空格分隔数字，详见向量 |
| BoundingBox（包围盒） | 六个空格分隔数字，先为中心 X Y Z，再为各轴半尺寸。"0 2 0 5 2 5" 表示中心高度 2、尺寸 10 x 4 x 10 的盒体 |
| Planes（平面） | 多平面用逗号分隔，每个为四个空格分隔数字：先法线 X Y Z，再为原点位于平面前方的距离。"0 -1 0 3" 表示高度 3、朝下的平面；"0 -1 0 3, 1 0 0 0" 再加入经过原点、朝 X 的平面 |
| Color（颜色） | CSS 色名、十六进制或三／四个数字，详见颜色 |
| String（字符串） | 自由文本，例如名称、路径、JSON 对象 |
| Asset ID、Material ID | <pc-asset> 或 <pc-material> 的 id，详见资源与材质 ID |
| Entity Reference（实体引用） | 实体 name 或 # 选择器，详见实体引用 |
布尔值
属性存在且值不为 "false" 时为 true，包括不写值的空属性；值为 "false" 时为 false：
| 标记 | 结果 |
|---|---|
cast-shadows（仅出现） | true |
cast-shadows="true"（或任意非 false 值） | true |
cast-shadows="false" | false |
| 不存在或被移除 | 引擎默认值 |
<!-- Bare presence enables a default-false option -->
<pc-light type="directional" cast-shadows></pc-light>
<!-- Setting "false" disables a default-true option -->
<pc-scroll-view horizontal="false"></pc-scroll-view>
数字
接受整数、小数、负数和科学记数法，例如 1e3，但必须有限。带单位如 fov="60deg"、空值如 intensity=""、Infinity 等会警告并采用默认值。
<pc-camera fov="60" near-clip="0.1"></pc-camera>
枚举
只接受固定名称，无效名称会警告并列出合法值，再恢复默认：
Invalid value 'bogus' for attribute 'scroll-mode'. Valid values: clamp, bounce, infinite. Using 'bounce'.
不接受引擎数字常量，声明层只使用名称。JavaScript API 同样如此，例如 scrollbar.orientation 接收并返回字符串名称，不使用引擎数值常量。
<pc-camera tonemap="aces"></pc-camera>
向量
由空白分隔数字，数量必须与维度一致，即 Vector2 为两个、Vector3 为三个、Vector4 为四个。允许任意数量空白，不支持逗号，使用逗号会警告。
<pc-entity position="0 1.5 0" scale="2 2 2"></pc-entity>
颜色
接受三种形式：
| 格式 | 示例 |
|---|---|
| CSS 颜色名称 | clear-color="rebeccapurple" |
十六进制 #rgb、#rgba、#rrggbb 或 #rrggbbaa | color="#f00" 或 color="#ff0000" |
| 三或四个 0 到 1 的空格分隔数字 | color="1 0.5 0.5" 或 color="1 0.5 0.5 0.5" |
<pc-camera clear-color="#f0f8ff"></pc-camera>
<pc-light color="1 0.8 0.6"></pc-light>
资源与材质 ID
资源作为 <pc-app> 的直接子项声明一次，通过 id 引用。Asset ID 指向 <pc-asset>，Material ID 指向 <pc-material>：
<pc-asset id="tiles" src="tiles.png"></pc-asset>
<pc-material id="floor" diffuse-map="tiles"></pc-material>
<!-- ... -->
<pc-render type="plane" material="floor"></pc-render>
值直接填写 id，不加 #，因为这是应用注册表查询而非 CSS 选择器。各属性描述会说明接受的资源类型。
未匹配的 id 通常静默保留原值。pc-model 例外，因为内容来自资源：会清空内容、警告找不到资源，并始终未就绪。pc-app 的 area-light-luts、精灵 pc-asset 的 atlas、pc-node 的 material-overrides，以及脚本 asset: 无匹配时也会警告。
实体引用
某些属性引用其他实体，例如 <pc-button> 的 image、<pc-scrollbar> 的 handle、<pc-scroll-view> 的 viewport 和 content，以及 <pc-joint> 的 entity-a、entity-b。仅支持两种形式：
| 形式 | 含义 | 范围 |
|---|---|---|
handle | <pc-entity>、<pc-model> 或 <pc-node> 的 name | 最近实体宿主优先，再向外，最后整个文档 |
#handle, #hud pc-entity | 以 # 开头的 CSS 选择器，即 id 或基于 id 的选择器 | 整个文档 |
<pc-scrollbar orientation="vertical" handle="#handle"></pc-scrollbar>
规则明确封闭：裸值始终为名称，不是 id 或选择器；不以 # 开头的选择器不接受。因此形式一目了然，其他位置新增或改名不会改变解析类别。
名称从近到远解析
先查最近实体宿主，即 pc-entity、pc-model 或 pc-node，包括自身及子树，再依次向外查实体、所属 pc-app，最后整个文档。各范围内按文档顺序取首个匹配。pc-node 使用其绑定的 glTF 节点名称。
因此克隆模板内的名称会先找到自身实例，避免命中更早的克隆，详见模板复用。
# 引用作用于整个文档
以 # 开头的值直接作为 CSS 选择器查询文档，不再尝试名称。例如名为 #body 的实体不会遮蔽 id 为 body 的元素。需要与引用者位置无关的固定目标时，使用 #。
未解析引用会警告
非空引用无法解析时，控制台会指出属性和原因：没有匹配、匹配尚未生成实体，或类型根本不支持实体。尚未加载模型的 pc-node 通常在重新设置属性后可解析。如果裸值匹配某实体宿主的 id，警告还会建议 #id 形式，必要时会转义，例如 id a:b 对应 #a:b。
脚本属性同样遵循此规则：entity:body 指向名称 body，entity:#body 指向 id body。
脚本属性
<pc-script-instance> 根据脚本声明的默认类型解析逐属性值，语法基本相同，但没有引擎默认值，因此：
- 无效值会警告并保留脚本当前值。
- 移除也保留当前值，除非 attributes JSON 设置了同名属性，此时恢复 JSON 值。
未声明带类型默认值的名称会作为原始字符串赋值，并发出警告。详见通过脚本添加行为。