`Class.BillboardGui` 是一个用于在 3D 空间中显示 UI 对象的容器，但始终面向相机。容器的位置相对于父级 `Class.BasePart` 或 `Class.Attachment`（或 `Class.BillboardGui.Adornee|Adornee`）。对于 `Class.BasePart|BaseParts`，使用 `Class.BasePart.Position|Position` 属性，而对于 `Class.Attachment|Attachments`，使用 `Class.Attachment.WorldPosition|WorldPosition` 属性。

<img src="/assets/ui/in-experience/BillboardGui-Diagram.jpg" width="800" alt="描述它漂浮在上面的屏幕控制台的 TextLabel 的 BillboardGui。" />

一个横幅的 `Class.BillboardGui.Size|Size` 属性的工作方式与 `Class.GuiObject.Size` 有些不同。虽然 **offset** 组件的工作方式相同，但 **scale** 组件在 3D 空间中用作建筑尺寸。

创建一个包含 `Class.TextLabel` 的大小缩放 `Class.BillboardGui` 时，启用标签的 `Class.TextLabel.TextScaled|TextScaled` 属性是有用的，这样随着相机距离的变化，其文本会随着横幅画布一起缩放。

请注意，像 `Class.ImageButton|ImageButtons` 和 `Class.TextButton|TextButtons` 这样的互动 UI 元素只有在它们被放置在 `Class.PlayerGui` 下时才会接收用户输入，通常是通过将 `Class.BillboardGui` 放置在 `Class.StarterGui` 中。`Class.BillboardGui.Adornee|Adornee` 属性可用于瞄准 3D 世界中的部件或附件，同时 `Class.BillboardGui` 本身保持在 `Class.PlayerGui` 中。

有关使用 `Class.BillboardGui` 容器的指南，请参见 [体验中的 UI](/ui/in-experience-containers#billboard-ui)。

##### 缓存行为

为了改善性能，`Class.BillboardGui` 的外观会被缓存，直到以下之一发生，然后在下一个渲染帧上重新计算其外观。

- 向 `Class.BillboardGui` 添加或移除一个后代。
- `Class.BillboardGui` 的一个后代的属性更改。
- `Class.BillboardGui` 自身的一个属性更改。


BillboardGui

控制后代是否会接收输入事件。如果 `Class.BillboardGui` 包含一个 `Class.GuiButton`，那么该按钮仅在 `Class.BillboardGui.Active|Active` 在 `Class.BillboardGui` **和**按钮上均设置为 `true` 时才会变得可点击。

请注意，像 `Class.ImageButton|ImageButtons` 和 `Class.TextButton|TextButtons` 这样的互动 UI 元素只有在它们被放置在 `Class.PlayerGui` 下时才会接收用户输入，通常是通过将 `Class.BillboardGui` 放置在 `Class.StarterGui` 中。`Class.BillboardGui.Adornee|Adornee` 属性可用于将 `Class.BillboardGui` 附加到 `Class.BasePart` 或 `Class.Attachment`，而不是进行父级关联。


BillboardGui.Active

控制后代是否会接收输入事件。


设置 `Class.BillboardGui` 相对于哪个目标 `Class.BasePart` 或 `Class.Attachment` 进行定位，覆盖父级部分或附件。


BillboardGui.Adornee

设置 `Class.BillboardGui` 相对于哪个目标部分或附件进行定位。


该属性确定 `Class.BillboardGui` 是否会始终在其他 3D 对象上渲染。

当设置为 `false`（默认）时，`Class.BillboardGui` 的渲染方式与其他 3D 内容相同，并且会被其他 3D 对象遮挡。设置为 `true` 时，`Class.BillboardGui` 始终在 3D 内容上方渲染，外观会显著变化：

- 颜色与它们在 `Class.ScreenGui` 中的外观一致。
- 在高 DPI 设备上，文本可能显得更清晰。
- `Class.BillboardGui.LightInfluence|LightInfluence` 被视为 `0`。
- `Class.BillboardGui.Brightness|Brightness` 无效。


BillboardGui.AlwaysOnTop

确定 `Class.BillboardGui` 是否会始终在其他 3D 对象上渲染。


该属性确定当 `Class.BillboardGui.LightInfluence|LightInfluence` 为 `0` 时，`Class.BillboardGui` 容器的光的缩放因子。默认情况下，该属性为 `1`，可以设置为 `0` 到 `1000` 之间的任何数字。通过修改此属性，`Class.BillboardGui` 的表观亮度可以更好地与其环境匹配。例如，视频横幅可以在黑暗的房间中通过将 `Class.BillboardGui.Brightness|Brightness` 增加到 `10` 来提高亮度。

请注意，在 Studio 中不可访问 `Class.BillboardGui.Brightness|Brightness`，并且当 `Class.BillboardGui.LightInfluence|LightInfluence` 为 `1` 或 `Class.BillboardGui.AlwaysOnTop|AlwaysOnTop` 为 `true` 时无效。


BillboardGui.Brightness

确定当 `Class.BillboardGui.LightInfluence|LightInfluence` 为 `0` 时，`Class.BillboardGui` 容器的光的缩放因子。


设置为 `true`（默认）时，位于 `Class.BillboardGui` 画布边框外的部分 `Class.GuiObject|GuiObjects` 不会被绘制。

即使此属性为 `false`，**完全** 位于画布外的 `Class.GuiObject|GuiObjects` 也不会渲染。


BillboardGui.ClipsDescendants

是否将位于 `Class.BillboardGui` 画布边框外的部分 `Class.GuiObject|GuiObjects` 绘制出来。


当前 `Class.BillboardGui` 与玩家相机之间的距离，单位为个 stud。只有当 `Class.BillboardGui.DistanceStep|DistanceStep` 大于 `0` 时，此属性的改变事件才会触发。


BillboardGui.CurrentDistance

当前 `Class.BillboardGui` 与玩家相机之间的距离，单位为个 stud。


确定 `Class.BillboardGui` 将停止以更大尺寸缩放的距离，单位为个 stud，相对于玩家当前的相机，默认值为 `0`。如果 `Class.BillboardGui.CurrentDistance|CurrentDistance` 小于此值，则它不会比在该距离下更大。


BillboardGui.DistanceLowerLimit

确定 `Class.BillboardGui` 将停止以更大尺寸缩放的距离，单位为个 stud。


确定随玩家相机靠近和远离 `Class.BillboardGui` 时，`Class.BillboardGui.CurrentDistance|CurrentDistance` 的增减，单位为个 stud。属性默认为 `0`。


BillboardGui.DistanceStep

确定随玩家相机靠近和远离 `Class.BillboardGui` 时，`Class.BillboardGui.CurrentDistance|CurrentDistance` 的增减，单位为个 stud。


确定 `Class.BillboardGui` 将停止以更小尺寸缩放的距离，单位为个 stud，相对于玩家当前的相机。如果 `Class.BillboardGui.CurrentDistance|CurrentDistance` 大于此值，则它不会比在该距离下更小。

如果值小于 `0`，则此属性会被忽略。默认值为 `-1`，意味着该属性默认会被忽略。


BillboardGui.DistanceUpperLimit

确定 `Class.BillboardGui` 将停止以更小尺寸缩放的距离，单位为个 stud。


该属性确定 `Class.BillboardGui` 相对于其 `Class.BillboardGui.Adornee|Adornee` 的偏移量，按模型的 `Class.Camera` 方向，单位为该模型的 `Class.Camera` 对齐边界框的一半维度。

另请参见 `Class.BillboardGui.StudsOffset|StudsOffset`，该属性也有类似的工作方式，但使用的是 stud 单位，或 `Class.BillboardGui.ExtentsOffsetWorldSpace|ExtentsOffsetWorldSpace`，该属性的工作方式类似，只是偏移方向相对于全球轴。


BillboardGui.ExtentsOffset

确定 `Class.BillboardGui` 相对于其 `Class.BillboardGui.Adornee|Adornee` 的偏移量，按模型的 `Class.Camera` 方向，单位为该模型的 `Class.Camera` 对齐边界框的一半维度。


该属性确定 `Class.BillboardGui` 相对于其 `Class.BillboardGui.Adornee|Adornee` 的偏移量，相对于全球轴，单位为该模型的轴对齐边界框的一半维度。

另请参见 `Class.BillboardGui.StudsOffset|StudsOffset`，该属性也有类似的工作方式，但使用的是 stud 单位，或 `Class.BillboardGui.ExtentsOffset|ExtentsOffset`，该属性的工作方式类似，只是偏移方向相对于 `Class.Camera`。


BillboardGui.ExtentsOffsetWorldSpace

确定 `Class.BillboardGui` 相对于其 `Class.BillboardGui.Adornee|Adornee` 的偏移量，相对于全球轴，单位为该模型的轴对齐边界框的一半维度。


控制 `Class.BillboardGui` 受环境光的影响程度，范围从 `0` 到 `1`。将其设置为 `1` 意味着周围光照完全控制外观，而将其设置为 `0` 意味着光照没有效果。


BillboardGui.LightInfluence

控制 `Class.BillboardGui` 受环境光的影响程度。


该属性控制 `Class.BillboardGui` 距离相机的最大距离，在此距离之前停止渲染。值为 `0` 或 `inf`（默认）意味着没有限制，并将无限远渲染。

对于出现在户外的 `Class.BillboardGui|BillboardGuis`，建议 `Class.BillboardGui.MaxDistance|MaxDistance` 足够高，以确保容器的 UI 在出现或消失时在屏幕上足够小，最小化突然弹出/消失效果。


BillboardGui.MaxDistance

控制 `Class.BillboardGui` 可以显示的最大距离，在此距离之前停止渲染。


供脚本使用，以从特定玩家处隐藏 `Class.BillboardGui`。

要从多个玩家处隐藏 `Class.BillboardGui`，请将其放入 `Class.StarterGui` 中，并使用脚本根据 `Class.Players.LocalPlayer|LocalPlayer` 是否能看到它来设置 `Class.BillboardGui.Enabled|Enabled` 属性。`Class.BillboardGui.Adornee|Adornee` 属性可用于将 `Class.BillboardGui` 附加到 `Class.BasePart` 或 `Class.Attachment`，而不是进行父级关联。


BillboardGui.PlayerToHideFrom

供脚本使用，以从特定玩家处隐藏 `Class.BillboardGui`。


控制 `Class.BillboardGui` 在屏幕上的大小。与 `Class.GuiObject.Size` 不同，该属性的 [scale](/ui/position-and-size#size) 组件设置了横幅在 3D 空间中的 stud 尺寸。


BillboardGui.Size

控制 `Class.BillboardGui` 在屏幕上的大小。


一个以大小相关单位表示的 2D 偏移量，起到锚点的作用。它可以与 `Class.GuiObject.AnchorPoint` 属性类似使用，但值不同。

<table size="small">
<thead>
<th>大小偏移量</th>
<th>说明</th>
</thead>
<tbody>
<tr>
<td><code>0, 0</code></td>
<td>默认情况下，UI 将在其中心锚定。</td>
</tr>
<tr>
<td><code>0.5, 0.5</code></td>
<td>UI 将在左下角锚定。</td>
</tr>
<tr>
<td><code>0.5, -0.5</code></td>
<td>UI 将在左上角锚定。</td>
</tr>
<tr>
<td><code>-0.5, 0.5</code></td>
<td>UI 将在右上角锚定。</td>
</tr>
<tr>
<td><code>-0.5, -0.5</code></td>
<td>UI 将在右下角锚定。</td>
</tr>
</tbody>
</table>

另请参见 `Class.BillboardGui.StudsOffset|StudsOffset`、`Class.BillboardGui.StudsOffsetWorldSpace|StudsOffsetWorldSpace`、`Class.BillboardGui.ExtentsOffset|ExtentsOffset` 和 `Class.BillboardGui.ExtentsOffsetWorldSpace|ExtentsOffsetWorldSpace`，这些都是在 3D 空间中工作的偏移属性。


BillboardGui.SizeOffset

一个以大小相关单位表示的 2D 偏移量，起到锚点的作用。


该属性确定 `Class.BillboardGui` 相对于其 `Class.BillboardGui.Adornee|Adornee` 的偏移量，单位为个 stud，按 `Class.Camera` 方向。

另请参见 `Class.BillboardGui.StudsOffsetWorldSpace|StudsOffsetWorldSpace`，该属性也有类似的工作方式，但偏移方向相对于全球轴。


BillboardGui.StudsOffset

确定 `Class.BillboardGui` 相对于其 `Class.BillboardGui.Adornee|Adornee` 的偏移量，单位为个 stud，按 `Class.Camera` 方向。 


该属性确定 `Class.BillboardGui` 相对于其 `Class.BillboardGui.Adornee|Adornee` 的偏移量，单位为个 stud，按全球轴。

另请参见 `Class.BillboardGui.StudsOffset|StudsOffset`，该属性也有类似的工作方式，但偏移方向相对于 `Class.Camera`。


BillboardGui.StudsOffsetWorldSpace

确定 `Class.BillboardGui` 相对于其 `Class.BillboardGui.Adornee|Adornee` 的偏移量，单位为个 stud，按全球轴。


一个用于 `Class.GuiObject|GuiObjects` 的容器，在 3D 空间中面向相机渲染。


**LayerCollector** 是渲染 `Class.GuiObject` 后代的 2D UI 容器的基类，例如 `Class.ScreenGui`。

为了提高性能，`Class.LayerCollector` 的外观在发生以下事件之前会被缓存：

- 添加或移除一个后代。
- 后代的属性发生变化。
- `Class.LayerCollector` 本身的属性发生变化。

LayerCollector:GetLayoutNodeTree

LayerCollector

切换此 `Class.LayerCollector` 的可见性。当为 `false` 时，
UI 内容将不会渲染，不会处理用户输入，也不会对
变化进行更新。

LayerCollector.Enabled

切换此 `Class.LayerCollector` 的可见性。

当设置为 `false` 且此 `Class.LayerCollector` 是 `Class.StarterGui` 的直接子对象时，
它只会克隆到每个玩家的 `Class.PlayerGui` 一次，并且在玩家的
角色重生时不会被删除。

当设置为 `true`（默认值），或者此 `Class.LayerCollector` 是 `Class.StarterGui` 的
**间接** 后代时，它将在玩家角色重生时被克隆到每个
玩家的 `Class.PlayerGui` 中，并且在玩家的角色再次重生时会
删除自身。

LayerCollector.ResetOnSpawn

确定每当玩家的角色重生时，`Class.LayerCollector` 是否会重置（删除自身并
重新克隆到玩家的 `Class.PlayerGui`）。

控制此 `Class.LayerCollector` 所有后代中 `Class.GuiObject.ZIndex` 的行为。

使用 `Enum.ZIndexBehavior.Sibling`（默认），子项总是渲染在其父项之上，
并且使用 `Class.GuiObject.ZIndex|ZIndex` 来决定单个 UI 对象的子项将如何相互渲染的顺序。

`Enum.ZIndexBehavior.Global` 根据 `Class.GuiObject.ZIndex|ZIndex` 对所有后代进行排序，
然后使用层级顺序来打破平局。结果是，一个 `Class.GuiObject` 的后代需要有一个
至少与父项同样高的 `Class.GuiObject.ZIndex|ZIndex` 值，否则它们将渲染在父项之下。


LayerCollector.ZIndexBehavior

控制此 `Class.LayerCollector` 所有后代中 `Class.GuiObject.ZIndex` 的行为。


渲染 `Class.GuiObject|GuiObjects` 的 2D UI 容器的基类
在层中。

`Class.GuiBase2d` 是一个由 2D
`Class.GuiObject|GuiObjects` 继承的抽象类。


当游戏手柄选择移动到、离开或在连接的 `Class.GuiBase2d` 或任何子 `Class.GuiObject|GuiObjects` 中更改时，该事件会被触发。当选择高亮移动到一个 `Class.GuiObject` 时，事件会从该 `Class.GuiObject` 向所有其祖先冒泡，通知它们选择已更改/进入/退出其子树中的 `Class.GuiObject`。


GuiBase2d.SelectionChanged

amISelected

如果新选择与附加的 GuiBase2d 匹配，则为真。


previousSelection

newSelection

当游戏手柄选择移动到、离开或在连接的 `Class.GuiBase2d` 或任何子 `Class.GuiObject|GuiObjects` 中更改时触发。


GuiBase2d

`Class.GuiBase2d.AbsolutePosition|AbsolutePosition` 是一个只读属性，提供 `Class.GuiBase2d` 元素的屏幕位置，以像素为单位。这代表了元素根据其祖先的大小和位置渲染的实际像素位置。请注意，`Class.GuiBase2d.AbsolutePosition|AbsolutePosition` 始终表示 `Class.GuiBase2d` 元素的左上角。

如果 `Class.GuiBase2d` 位于 `Class.ScreenGui` 中，`Class.GuiBase2d.AbsolutePosition|AbsolutePosition` 属性使用 `Enum.ScreenInsets|CoreUISafeInsets` 视口坐标系统。该坐标系统的原点位于 Roblox 顶部栏的左下角。请注意，这与 `Class.InputObject.Position` 属性使用的坐标系统相同。

<img src="/assets/engine-api/classes/GuiBase2d/AbsolutePositionCoordinateSystem.png" width="840" alt="显示 AbsolutePosition 坐标系统原点的图表." />

另请参见 `Class.GuiBase2d.AbsoluteRotation|AbsoluteRotation` 和 `Class.GuiBase2d.AbsoluteSize|AbsoluteSize`。


GuiBase2d.AbsolutePosition

描述 `Class.GuiBase2d` 元素的实际屏幕位置，以像素为单位。


`Class.GuiBase2d.AbsoluteRotation|AbsoluteRotation` 是一个只读属性，描述 `Class.GuiBase2d` 元素的实际屏幕旋转，以度为单位。它**不**执行边界检查，因此其值可能不在 `0` 到 `360` 范围内。

另请参见 `Class.GuiBase2d.AbsolutePosition|AbsolutePosition` 和 `Class.GuiBase2d.AbsoluteSize|AbsoluteSize`。


GuiBase2d.AbsoluteRotation

描述 `Class.GuiBase2d` 元素的实际屏幕旋转，以度为单位。


`Class.GuiBase2d.AbsoluteSize|AbsoluteSize` 是一个只读属性，描述 `Class.GuiBase2d` 元素的实际屏幕大小，以像素为单位。

另请参见 `Class.GuiBase2d.AbsolutePosition|AbsolutePosition` 和 `Class.GuiBase2d.AbsoluteRotation|AbsoluteRotation`。


GuiBase2d.AbsoluteSize

描述 `Class.GuiBase2d` 元素的实际屏幕大小，以像素为单位。


设置为 `true` 时，将对该 `Class.GuiBase2d` 及其子项应用本地化。用于本地化的条目与 `Class.LocalizationService:GetTableEntries()` 返回的条目集合相同。启用 `Class.GuiBase2d.AutoLocalize|AutoLocalize` 的条目如果需要将在云表加载后自动重新翻译。

另请参见 `Class.GuiBase2d.RootLocalizationTable|RootLocalizationTable`。


GuiBase2d.AutoLocalize

设置为 `true` 时，将对该 `Class.GuiBase2d` 及其子项应用本地化。


当本地化表的 `Class.LocalizationTable.Root` 目标指向该对象或该对象的一个祖先时，此属性自动设置为 true。指向实例的 `Class.LocalizationTable|LocalizationTables` 及其 `Class.LocalizationTable.Root` 属性将对 root 实例的所有子 `Class.TextLabel.TextButton` 进行本地化。


GuiBase2d.Localize

当本地化表的 `Class.LocalizationTable.Root` 目标指向该对象或该对象的一个祖先时，自动设置为 true。


对 `Class.LocalizationTable` 的引用，用于对该 `Class.GuiBase2d` 及其子项应用自动本地化。必须在 `Class.GuiBase2d` 及其祖先上将 `Class.GuiBase2d.AutoLocalize|AutoLocalize` 设置为 `true`，才能应用自动本地化。

您可以将其设置为引用 `Class.LocalizationTable` 中的任何内容。`Class.GuiBase2d` 对象及其所有子项将尝试使用该特定 `Class.LocalizationTable` 及其祖先进行自动文本替换，然后在未定义的顺序下使用 `Class.LocalizationService` 下的表和云表。

如果所引用的表中没有可用的翻译，它将查找该表的父级中的翻译，如果它也是 `Class.LocalizationTable`，依此类推。

另请参见 `Class.LocalizationService:GetTableEntries()`，以了解 `Class.GuiBase2d.RootLocalizationTable|RootLocalizationTable` 如何用于自动本地化。


GuiBase2d.RootLocalizationTable

对 `Class.LocalizationTable` 的引用，用于对该 `Class.GuiBase2d` 及其子项应用自动本地化。


自定义游戏手柄选择行为，向下方向。


GuiBase2d.SelectionBehaviorDown

自定义游戏手柄选择行为，向左方向。


GuiBase2d.SelectionBehaviorLeft

自定义游戏手柄选择行为，向右方向。


GuiBase2d.SelectionBehaviorRight

自定义游戏手柄选择行为，向上方向。


GuiBase2d.SelectionBehaviorUp

允许自定义游戏手柄选择如何在选择组的子按钮之间移动，离开组并选择其他按钮。

将 `Class.GuiBase2d.SelectionGroup|SelectionGroup` 设置为 `true` 时，暴露 `Class.GuiBase2d.SelectionBehaviorUp|SelectionBehaviorUp`、`Class.GuiBase2d.SelectionBehaviorDown|SelectionBehaviorDown`、`Class.GuiBase2d.SelectionBehaviorLeft|SelectionBehaviorLeft` 和 `Class.GuiBase2d.SelectionBehaviorRight|SelectionBehaviorRight` 属性。对于这些选择行为，`Enum.SelectionBehavior.Escape`（默认）表示游戏手柄选择首先尝试在选择组内查找选择，只有在没有找到合适按钮时才会移到外面。相反，设置为 `Enum.SelectionBehavior.Stop` 则表示游戏手柄选择仅在选择组内查找，不会从选择行为方向外移出组。


GuiBase2d.SelectionGroup

允许自定义游戏手柄选择移动。


一个由 2D `Class.GuiObject|GuiObjects` 继承的抽象类。


GuiBase 是一个抽象类，绝大多数图形用户界面对象
从中继承。


GuiBase

`Instance` 是 Roblox 类层次结构中所有类的基类
可以成为 `Class.DataModel` 树的一部分。

无法直接创建根 `Instance` 对象，但特殊的
`Datatype.Instance.new()` 构造函数通过代码创建对象，
以类的名称作为参数并返回创建的对象。

演示通过连接到
`Class.Instance.AncestryChanged` 事件来检测实例祖先的变化。

ChangingPart 的父级随着时间的推移而设置为不同的值。该零件的父级是该零件的祖先，因此
`Class.Instance.AncestryChanged` 事件将在每次变化时触发。


当此实例被重新设置父级或其任何祖先被重新设置父级时触发。

您可以使用此事件跟踪 Studio 中实例的删除，例如通过资源管理器手动删除或通过插件删除。如果您需要检测实例是否通过 `Class.Instance:Destroy()` 被销毁，请使用 `Class.Instance.Destroying` 事件。

Instance.AncestryChanged

child

更改了 `Class.Instance.Parent|Parent` 属性的实例，可以是此实例或更远的祖先，**不**一定是与处理程序连接的实例。

parent

当此对象或其祖先的 `Class.Instance.Parent` 属性被更改时触发。

每当实例上的任何属性被更改时触发，包括当某个属性被设置为 `nil`。更改的属性名称会传递给连接的函数。

例如，以下代码片段将 `attributeChanged()` 函数连接到每当部分的一个属性更改时触发：

```lua
local Workspace = game:GetService("Workspace")

local part = Workspace.Part

local function attributeChanged(attributeName)
	print(attributeName, "changed")
end

part.AttributeChanged:Connect(attributeChanged)
```
另请参见 `Class.Instance:GetAttributeChangedSignal()`，此方法返回一个事件，当特定给定属性更改时触发。

Instance.AttributeChanged

attribute

每当在 `Class.Instance` 上更改属性时触发。

此代码段打印添加到工作区的对象名称：

在对象被设置为此 `Class.Instance` 的父级后触发。

注意，当在客户端使用此方法检测由服务器创建的对象时，索引这些对象的后代时必须使用 `Class.Instance:WaitForChild()`。这是因为对象及其后代不能保证同时从服务器复制到客户端。例如：

```
local Workspace = game:GetService("Workspace")

Workspace.ChildAdded:Connect(function(child)
	-- 使用 WaitForChild() 因为后代可能尚未复制
	local head = child:WaitForChild("Head")
end)
```
注意，此事件仅对 `Class.Instance` 的直接子项起作用。要捕获所有后代的事件，请使用 `Class.Instance.DescendantAdded`。

另请参见 `Class.Instance.ChildRemoved`。

Instance.ChildAdded

在对象被设置为此 `Class.Instance` 的父级后触发。

Instance.childAdded

这个代码片段会在对象从工作区中移除时打印它们的名称：

在子项从此 `Class.Instance` 中移除后触发。

移除是指将一个对象的父级从这个 `Class.Instance` 更改为与这个 `Class.Instance` 不同的东西。请注意，当子项被销毁时（使用 `Class.Instance:Destroy()`），此事件也将触发，因为销毁函数将对象的父级设置为 `nil`。

此事件仅对 `Class.Instance` 的直接子项起作用。要捕获所有后代的事件，请使用 `Class.Instance.DescendantRemoving`。

另请参见 `Class.Instance.ChildAdded`。

Instance.ChildRemoved

在子项从此 `Class.Instance` 中移除后触发。

以下示例将打印添加到
工作区的任何对象的名称：


此事件在后代被添加到 `Class.Instance` 后触发。

由于它对每个后代触发，将对象设置为 `Class.Instance` 的父级将分别触发此对象及其所有后代的事件。

如果您只关心 `Class.Instance` 的 **直接子项**，请使用 `Class.Instance.ChildAdded`。 

另请参见 `Class.Instance.DescendantRemoving`。

Instance.DescendantAdded

descendant

在后代被添加到 `Class.Instance` 后触发。

以下示例在一个后代被移除时打印其名称
从工作区:

此事件在父级 `Class.Instance` 更改时 **立即之前** 触发，以至于 **后代** 实例将不再是后代。`Class.Instance:Destroy()|Destroy()` 将实例的 `Class.Instance.Parent|Parent` 更改为 `nil`，因此在父级的后代上调用该方法将导致触发此事件。

因为此事件在后代移除 **之前** 触发，所以在此事件触发时，后代的父级不会改变。如果后代也是父级的 **直接子项**，则此事件会在 `Class.Instance.ChildRemoved` 之前触发。

如果后代有子项，此事件会先触发后代，然后是其后代。

#### 警告

此事件与被移除的后代对象一起触发。尝试将后代的 `Class.Instance.Parent|Parent` 设置为其他内容将失败。下面是一个演示的示例：

```
local Workspace = game:GetService("Workspace")

Workspace.DescendantRemoving:Connect(function(descendant)
	-- 请勿在此函数中操作后代的父级！
	-- 此事件之所以触发是因为父级被操作，而更改尚未发生
	-- 因此，像这样更改父级是有问题的：
	descendant.Parent = game
end)

local part = Instance.new("Part")
part.Parent = Workspace
part.Parent = nil
```
另请参见 `Class.Instance.DescendantAdded|DescendantAdded`。

Instance.DescendantRemoving

在 `Class.Instance` 的后代被移除之前立即触发。

此示例演示了当使用即时信号行为时，
实例被销毁时仍保持在原位，直到连接的函数挂起。


此示例演示了如何在使用推迟信号行为时，在信号触发之前销毁实例。


连接的函数在使用时，`Class.Instance` 将永远不会从内存中删除。然而，如果函数在任何时候挂起，则 `Class.Instance` 及其后代将被设置为 `nil`。

如果 `Class.Workspace.SignalBehavior` 属性设置为 `Enum.SignalBehavior.Immediate`，则此事件将在 `Class.Instance` 或其任一祖先被使用 `Class.Instance:Destroy()` 销毁之前立即触发。

如果 `Class.Workspace.SignalBehavior` 属性设置为 `Enum.SignalBehavior.Deferred`，则此事件将在下一个恢复点触发，这将在 `Class.Instance` 或其任一祖先被使用 `Class.Instance:Destroy()` 销毁之后。

使用 `Enum.SignalBehavior.Deferred|Deferred` 行为，将脚本连接到其自己的 `Class.Instance.Destroying` 事件是有问题的，因为脚本将在回调被调用之前被销毁（这意味着它将无法执行）。

在 Studio 中删除 `Class.Instance` 时，例如通过 [Explorer](/studio/explorer) 手动删除或通过插件删除，`Class.Instance` 不会被销毁。相反，父级设置为 `nil`，您可以通过 `Class.Instance.AncestryChanged` 跟踪。

Instance.Destroying

在实例通过 `Class.Instance:Destroy()` 被销毁之前立即触发（或推迟到之后）。

此事件在实例上的任何样式属性被更改时触发，包括当某个属性被设置为 `nil`。

```lua
local Players = game:GetService("Players")

local player = Players.LocalPlayer
local playerGui = player.PlayerGui
local HUDContainer = playerGui:WaitForChild("HUDContainer")
local meterBar = HUDContainer.MeterBar

local function stylePropertyChanged()
	print("样式属性已更改")
end

meterBar:StyledPropertiesChanged():Connect(stylePropertyChanged)
```

Instance.StyledPropertiesChanged

每当实例上的任何样式属性被更改时触发，包括当某个属性被设置为 `nil`。

此方法将标签应用于实例，如果标签已被应用，则不会产生影响。
成功添加标签将触发由 `Class.CollectionService:GetInstanceAddedSignal()` 创建的信号，
并附有给定的标签。

#### 警告

- 客户端添加的实例标签将被丢弃，如果服务器后续在该实例上添加或移除标签，
因为服务器会将所有标签一起复制并覆盖先前的标签。

- 在为实例添加标签时，通常会使用一些资源为标签提供功能，例如事件连接或表。
为防止内存泄露，最好在不再需要标签时进行清理（断开连接，
设置为 `nil` 等）。在调用 `Class.Instance:RemoveTag()`、
调用 `Class.Instance:Destroy()` 或在连接到 `Class.CollectionService:GetInstanceRemovedSignal()` 返回的信号的函数中这么做。

Instance:AddTag

子项函数返回对象的子项数组。

Instance:children

此方法销毁实例的所有子项和后代。

```
local part = Instance.new("Part")

-- 添加一些闪光
for i = 1, 3 do
	local sparkles = Instance.new("Sparkles")
	sparkles.Parent = part

  local sc = Instance.new("Sparkles")
  sc.Parent = sparkles
end

print("Children:", #part:GetChildren())  --> Children: 3

part:ClearAllChildren()

print("Children:", #part:GetChildren())  --> Children: 0
```
如果您不想销毁 **所有** 子项和后代，请使用 `Class.Instance:GetChildren()` 或 `Class.Instance:GetDescendants()`
循环遍历这些子项/后代并选择需要销毁的内容。
例如以下代码示例将销毁从 `Class.Model` 下降的所有 `Class.BasePart|BaseParts`：

```
local Workspace = game:GetService("Workspace")

local model = Workspace:FindFirstChild("TestModel")

for _, descendant in model:GetDescendants() do
	if descendant:IsA("BasePart") then
		descendant:Destroy()
	end
end
```

Instance:ClearAllChildren

演示如何使用 `Class.Instance:Clone()` 克隆一个模型。

`Clone()` 创建实例及其所有后代的副本，
忽略所有不是 `Class.Instance.Archivable|Archivable` 的实例。根实例的副本由此方法返回，
并将其 `Class.Instance.Parent|Parent` 设置为 `nil`。注意，如果实例本身
的 `Class.Instance.Archivable|Archivable` 设置为 `false`，该方法将返回 `nil`。

如果在克隆的实例中设置了如 `Class.ObjectValue.Value` 的引用属性，
则副本的属性值取决于原始值：

- 如果引用属性指向的实例 **也** 被克隆，副本将指向副本。
- 如果引用属性指向的实例 **未** 被克隆，副本将保持相同的值。

Instance:Clone

创建实例及其所有后代的副本，忽略不
是 `Class.Instance.Archivable|Archivable` 的实例。

Instance:clone

演示使用 `Class.Instance:Destroy()` 函数销毁一个 Part。

该函数是处理不再需要的对象的正确方法。


将 `Class.Instance.Parent` 属性设置为 `nil`，锁定
`Class.Instance.Parent` 属性，断开所有连接，并对所有子项调用
`Destroy()`。此方法是处理不再需要的对象的正确方法。

处理不需要的对象非常重要，因为不必要的对象和连接会消耗内存，
这可能导致长期的严重性能问题。

最好在对对象调用 `Destroy()` 后，将引用该对象（或其后代）的任何变量设置为 `nil`。这可防止您的代码访问与该对象相关的任何内容。

```lua
local part = Instance.new("Part")
part.Name = "Hello, world"
part:Destroy()
-- 不要这样做：
print(part.Name)  --> "Hello, world"
-- 这样做可以防止上面的代码继续工作：
part = nil
```
一旦通过此方法销毁了 `Class.Instance`，便无法重复使用它，因为 `Class.Instance.Parent` 属性被锁定。要**暂时**移除对象而不是销毁它，请将
`Class.Instance.Parent|Parent` 设置为 `nil`。例如：

```
local Workspace = game:GetService("Workspace")

object.Parent = nil
task.wait(2)
object.Parent = Workspace
```
要在设定时间后销毁对象，请使用 `Class.Debris:AddItem()`。

Instance:Destroy

将 `Class.Instance.Parent` 属性设置为 `nil`，锁定
`Class.Instance.Parent` 属性，断开所有连接，并对所有子项调用
`Destroy()`。

Instance:destroy

返回 `Class.Instance` 的第一个祖先，
其 `Class.Instance.Name` 与给定名称相等。

该方法向上工作，意味着它从实例的直接 `Class.Instance.Parent` 开始，
向上到 `Class.DataModel`。如果未找到匹配的祖先，则返回 `nil`。

以下代码片段将查找名为 `Car` 的对象的第一个祖先。

```
local car = object:FindFirstAncestor("Car")
```
有关查找特定类的祖先的此方法的变体，请参见 `Class.Instance:FindFirstAncestorOfClass()` 和
`Class.Instance:FindFirstAncestorWhichIsA()`。

Instance:FindFirstAncestor

name

返回 `Class.Instance` 的第一个祖先，
其 `Class.Instance.Name` 与给定名称相等。

返回 `Class.Instance` 的第一个祖先，
其 `Class.Object.ClassName` 与给定的 className 相等。

该方法向上工作，意味着它从实例的直接 `Class.Instance.Parent` 开始，
向上到 `Class.DataModel`。如果未找到匹配的祖先，则返回 `nil`。

此方法的常见用途是查找 `Class.BasePart` 所属的 `Class.Model`。例如：

```
local model = part:FindFirstAncestorOfClass("Model")
```
此方法是 `Class.Instance:FindFirstAncestor()` 的变体，检查的是 `Class.Object.ClassName` 属性，而不是 `Class.Instance.Name`。
`Class.Instance:FindFirstAncestorWhichIsA()` 也存在，使用 `Class.Object:IsA()` 方法来尊重类继承。

Instance:FindFirstAncestorOfClass

className

返回 `Class.Instance` 的第一个祖先，
其 `Class.Object.ClassName` 与给定的 className 相等。

返回 `Class.Instance` 的第一个祖先，
对于给定的 className，`Class.Object:IsA()` 返回 true。

该方法向上工作，意味着它从实例的直接 `Class.Instance.Parent` 开始，
向上到 `Class.DataModel`。如果未找到匹配的祖先，则返回 `nil`。

与 `Class.Instance:FindFirstAncestorOfClass()` 不同，此方法使用 `Class.Object:IsA()` 来尊重类继承。例如：

```
print(part:IsA("Part"))  --> true
print(part:IsA("BasePart"))  --> true
print(part:IsA("Instance"))  --> true
```
因此，以下代码示例将返回第一个 `Class.BasePart` 祖先，无论它是否为 `Class.WedgePart`、`Class.MeshPart` 还是 `Class.Part`。

```
local part = object:FindFirstAncestorWhichIsA("BasePart")
```
另请参见 `Class.Instance:FindFirstAncestor()`。

Instance:FindFirstAncestorWhichIsA

返回 `Class.Instance` 的第一个祖先，
对于给定的 className，`Class.Object:IsA()` 返回 true。

下面的代码将在工作区中查找名为“Brick”的对象。如果找到，它将把该对象的名称更改为“Foo”。

返回具有给定名称的 `Class.Instance` 的第一个子项，如果没有此类子项，则返回 `nil`。如果可选的 `recursive` 参数为 `true`，
此方法将搜索所有后代，而不仅仅是 `Class.Instance` 的直接子项。

#### 检查对象的存在性

如果需要验证对象是否存在，则必须使用 `FindFirstChild()`。
尝试使用点操作符索引不存在的子项将引发错误。

```lua
local Workspace = game:GetService("Workspace")

-- 如果部件在工作区中不存在，以下行会出错
Workspace.Part.Transparency = 0.5
```
更好的方法是在先检查 `Part` 的情况下使用 `FindFirstChild()`，
然后使用 `if` 语句运行需要它的代码。

```lua
local Workspace = game:GetService("Workspace")

local part = Workspace:FindFirstChild("Part")
if part then
	part.Transparency = 0.5
end
```

#### 查找名称与属性匹配的子项

有时，对象的 `Class.Instance.Name|Name` 与其 `Class.Instance.Parent|Parent` 的属性相同。
使用点操作符时，如果属性和子项共享名称，属性将优先于子项。

在以下示例中，一个名为 `Color` 的 `Class.Folder` 被添加到一个 `Class.Part`，
该部分也具有 `Class.Part.Color` 属性。注意，`part.Color` 指的是 `Datatype.Color3` 属性值，而不是子 `Class.Folder` 实例。

使用 `Class.Instance:FindFirstChild()|FindFirstChild()` 的好处是，
引入新属性不会对您的代码构成风险。

```lua
local part = Instance.new("Part")
local folder = Instance.new("Folder")
folder.Name = "Color"
folder.Parent = part
local c1 = part.Color  -- 属性
local c2 = part:FindFirstChild("Color")  -- 子文件夹
```

#### 性能注意事项

`Class.Instance:FindFirstChild()|FindFirstChild()` 比直接使用点操作符慢约 20%
，并且几乎是简单存储对对象的引用所需时间的 8 倍。
因此，您应该避免在性能依赖的代码中（例如紧循环或连接到 `Class.RunService.Heartbeat` 和 `Class.RunService.PreRender` 的函数）调用它。
相反，请将结果存储在变量中，或考虑使用 `Class.Instance.ChildAdded|ChildAdded` 或
`Class.Instance:WaitForChild()|WaitForChild()` 来检测特定名称的子项何时可用。

Instance:FindFirstChild

recursive

返回以给定名称找到的 `Class.Instance` 的第一个子对象。

Instance:findFirstChild

返回 `Class.Instance` 的第一个子项，
其 `Class.Object.ClassName|ClassName` 等于给定的 `className`。
与 `Class.Instance:FindFirstChildWhichIsA()` 不同，此方法仅返回类与 `className` 匹配的对象，忽略类继承。如果没有找到匹配的子项，
此方法返回 `nil`。

Instance:FindFirstChildOfClass

返回 `Class.Instance` 的第一个子项，
其 `Class.Object.ClassName|ClassName` 等于给定类名称。

返回 `Class.Instance` 的第一个子项，
其 `Class.Object:IsA()` 对于给定的 className 返回 true。

如果没有找到匹配的子项，此方法返回 `nil`。如果可选的 `recursive` 参数为 true，
此方法将搜索所有后代，而不仅仅是 `Class.Instance` 的直接子项。

与 `Class.Instance:FindFirstChildOfClass()` 不同，此方法使用 `Class.Object:IsA()` 来尊重类继承。例如：

```lua
print(part:IsA("Part")) --> true
print(part:IsA("BasePart")) --> true
print(part:IsA("Instance")) --> true
```
因此，以下代码示例将返回第一个 `Class.BasePart` 子项，无论它是否为 `Class.WedgePart`、
`Class.MeshPart` 还是 `Class.Part`。

```
local part = object:FindFirstChildWhichIsA("BasePart")
```
寻找子项时，开发人员应使用 `Class.Instance:FindFirstChild()`。

Instance:FindFirstChildWhichIsA

返回 `Class.Instance` 的第一个子项，
其 `Class.Object:IsA()` 对于给定的 className 返回 true。

返回具有给定 `Class.Instance.Name` 的第一个后代。

此方法被禁用，无法使用。要查找实例的第一个后代，
请考虑使用 `Class.Instance:FindFirstChild()` 的 `recursive` 参数。

Instance:FindFirstDescendant

返回具有给定 `Class.Instance.Name` 的第一个后代。

如果 `Class.Instance` 是 `Class.Actor`，则返回 `Class.Actor` 本身。
否则，返回其最接近的祖先 `Class.Actor`。如果没有祖先是 `Class.Actor`，则结果为 `nil`。

Instance:GetActor

返回与该实例相关联的 `Class.Actor`，如果有的话。

此方法返回已分配给给定
属性名称的值。如果未分配任何属性，则返回 `nil`。

例如，以下代码片段设置并获取实例的 `InitialPosition` 属性：

```lua
local Workspace = game:GetService("Workspace")

local part = Workspace.Part
part:SetAttribute("InitialPosition", part.Position)

local initialPosition = instance:GetAttribute("InitialPosition")
print(initialPosition)
```

#### 另请参阅

- `Class.Instance:SetAttribute()` 设置给定名称的属性为给定值。
- `Class.Instance:GetAttributes()` 返回每个实例属性的键值对字典。

Instance:GetAttribute

已分配给给定属性名称的值。如果未分配任何属性，则返回 `nil`。

返回已分配给给定属性名称的值。

此方法返回一个事件，该事件与`Class.Object.Changed|Changed` 事件完全相同，
只是在特定的给定属性更改时触发；它实际上类似于 `Class.Object:GetPropertyChangedSignal()|GetPropertyChangedSignal()`，
但用于属性。

通常使用此方法代替连接到 `Class.Object.Changed|Changed` 的函数，
该函数检查属性名称。随后对同一对象使用相同属性名称调用此方法将返回相同事件。

以下代码示例返回一个信号，当部件的 `InitialPosition` 属性更改时触发 `attributeChanged()` 函数：

```lua
local Workspace = game:GetService("Workspace")

local part = Workspace.Part
part:SetAttribute("InitialPosition", part.Position)

local function attributeChanged()
	print("属性已更改")
end

part:GetAttributeChangedSignal("InitialPosition"):Connect(attributeChanged)
```
另请参见 `Class.Instance.AttributeChanged`，当实例上的任何属性更改时都会触发它。

Instance:GetAttributeChangedSignal

指定要返回更改信号的属性名称。

返回一个在给定属性更改时触发的事件。

Instance

`Instance` 是 Roblox 类层次结构中所有类的基类
可以成为 `Class.DataModel` 树的一部分。

/reference/engine/classes/BillboardGui.yaml