`Class.SurfaceGui` 允许在 3D 世界中的零件表面上渲染 UI 对象，同时允许进行基本的用户交互。类似于 `Class.Decal|Decals` 和 `Class.Texture|Textures`，父级为 `Class.SurfaceGui` 的 UI 对象，如 `Class.TextLabel|TextLabels` 和 `Class.ImageLabel|ImageLabels`，将面向其所在表面的同一方向，并可以通过 `Class.SurfaceGui.Face|Face` 属性进行编辑。

<img src="/assets/ui/in-experience/SurfaceGui-Diagram.jpg" width="800" alt="在地方上有 ImageLabel 子项以表示屏幕控制台的 3D 零件上的 SurfaceGui。" />

请注意，像 `Class.ImageButton|ImageButtons` 和 `Class.TextButton|TextButtons` 这样的交互式 UI 元素只能接收用户输入，前提是它们父级为 `Class.PlayerGui`，通常是通过将 `Class.SurfaceGui` 放置在 `Class.StarterGui` 中（`Class.SurfaceGui.Adornee|Adornee` 属性可以用于定位 3D 世界中的零件，而 `Class.SurfaceGui` 本身保持在 `Class.PlayerGui` 中）。此外，部分的 `Class.BasePart.CanQuery|CanQuery` 属性必须为 `true`，以便交互式 UI 元素接收输入。

请参阅 [In-Experience UI](/ui/in-experience-containers#surface-ui) 以获取有关使用 `Class.SurfaceGui` 容器的指南。

##### 缓存行为

为了改善性能，`Class.SurfaceGui` 的外观会被缓存，直到发生以下情况之一，此后它的外观会在下一个渲染帧中重新计算。

- 向 `Class.SurfaceGui` 添加或移除子元素。
- `Class.SurfaceGui` 的子元素的属性发生变化。
- `Class.SurfaceGui` 本身的属性发生变化。


SurfaceGui

此属性确定 `Class.SurfaceGui` 是否将始终在其他 3D 对象之上渲染。

当设置为 `false`（默认）时，`Class.SurfaceGui` 像其他 3D 内容一样渲染，并被其他 3D 对象遮挡。当设置为 `true` 时，`Class.SurfaceGui` 总是会在 3D 内容之上渲染，外观会发生显著变化：

- 颜色与它们在 `Class.ScreenGui` 内部的外观相匹配。
- 在高 DPI 设备上文本可能会显得更加清晰。
- `Class.SurfaceGui.LightInfluence|LightInfluence` 视为 `0`。
- `Class.SurfaceGui.Brightness|Brightness` 没有影响。


SurfaceGui.AlwaysOnTop

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


此属性确定当 `Class.SurfaceGui.LightInfluence|LightInfluence` 为 `0` 时，`Class.SurfaceGui` 容器的光照如何缩放的因子。默认情况下，此属性为 `1`，可以设置为 `0` 到 `1000` 之间的任何数字。通过修改此属性，可以使 `Class.SurfaceGui` 的显著亮度更好地与其环境匹配。例如，可以通过将 `Class.SurfaceGui.Brightness|Brightness` 增加到 `10`，在黑暗房间内使视频广告牌更亮。

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


SurfaceGui.Brightness

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


在 "虚拟像素" 中定义的 "虚拟屏幕" 的大小，使得 `Class.SurfaceGui|SurfaceGuis` 可以逐像素与 `Class.ScreenGui|ScreenGuis` 兼容。


SurfaceGui.CanvasSize

当设置为 `true`（默认）时，在 `Class.SurfaceGui` 画布边界之外的 `Class.GuiObject|GuiObjects` 的部分将不会被绘制。

即使当此属性为 `false`，如果 `Class.GuiObject|GuiObjects` 完全位于画布之外，也不会被渲染。


SurfaceGui.ClipsDescendants

确定在 `Class.SurfaceGui` 画布边界之外的 `Class.GuiObject|GuiObjects` 的部分是否会被绘制。


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


SurfaceGui.LightInfluence

控制 `Class.SurfaceGui` 受到环境光照影响的程度。


此属性控制 `Class.SurfaceGui` 在停止渲染之前离摄像机的距离。值为 `0` 意味着没有限制，将无限远地渲染。对于大多数情况，默认值 `1000` 是合适的。

对于出现在户外的 `Class.SurfaceGui|SurfaceGuis`，建议将 `Class.SurfaceGui.MaxDistance|MaxDistance` 设置得足够高，以确保容器的 UI 在出现或消失时在屏幕上的尺寸足够小，从而最小化突然的弹入/弹出效果。


SurfaceGui.MaxDistance

控制 `Class.SurfaceGui` 在停止渲染之前可以显示的距离。


此属性确定用于渲染 `Class.SurfaceGui` 内容的每个世界空间 Stud 的像素密度。更高的值将导致其中的各种 `Class.GuiObject|GuiObjects` 显得更小（如果保持相同大小）。相反，较低的值将导致对象看起来更大。然而，如果通过使用 `Class.UIScale`、`Class.GuiObject.Size`、`Class.TextLabel.TextSize` 或类似的方法按比例缩放 `Class.GuiObject|GuiObjects`，则此属性允许使用更高的分辨率。

重要的是，选择一个基于您预期玩家查看 `Class.SurfaceGui` 的距离的值。还要注意，如果装饰的零件的表面足够大，较大的像素密度可能会对性能产生负面影响。


SurfaceGui.PixelsPerStud

确定用于渲染 `Class.SurfaceGui` 内容的每个世界空间 Stud 的像素密度。


当设置为 `Enum.SurfaceGuiSizingMode.PixelsPerStud`（默认），`Class.SurfaceGui` 的渲染大小是基于 `Class.SurfaceGui.PixelsPerStud|PixelsPerStud` 和表面的 Stud 大小的可变大小。

当设置为 `Enum.SurfaceGuiSizingMode.FixedSize` 时，`Class.SurfaceGui` 渲染为通过 `Class.SurfaceGui.CanvasSize|CanvasSize` 设置的固定大小。


SurfaceGui.SizingMode

确定 `Class.SurfaceGui` 是以固定大小渲染还是随其在 Stud 中的大小缩放。


设置开始在 `Class.SurfaceGui` 上左键单击而不是在持有的 `Class.Tool` 上执行的距离。如果角色在此距离内，则在单击时 `Class.Tool` 将不会激活。


SurfaceGui.ToolPunchThroughDistance

设置开始在 `Class.SurfaceGui` 上左键单击而不是在持有的 `Class.Tool` 上执行的距离。


将此 `Class.SurfaceGui` 层叠在同一面上的其他对象上（更改此属性不会在视觉上 "提升" 或 "沉没" 一 `Class.SurfaceGui`）。


SurfaceGui.ZOffset

将此 `Class.SurfaceGui` 层叠在同一面上的其他 `Class.SurfaceGui|SurfaceGuis` 之上。


用于在零件表面上渲染的 GuiObjects 的容器。


`Class.SurfaceGuiBase` 是用于将其 `Class.GuiObject` 后代渲染到3D世界中 `Class.BasePart` 的一个面的 `Class.LayerCollector` 基类。 `Class.SurfaceGui` 和 `Class.AdGui` 继承自它。

目标部件通过 `Class.SurfaceGuiBase.Adornee|Adornee` 属性设置；如果未指定 adornee，当父级是 `Class.BasePart` 时，容器将在其父级上渲染。 `Class.SurfaceGuiBase.Face|Face` 属性选择UI投影到部件的哪个表面。


SurfaceGuiBase

此属性决定 `Class.SurfaceGui` 是否会接收输入，
例如如果父级或 `Class.SurfaceGuiBase.Adornee|Adornee` 部件
包含像 `Class.ClickDetector` 这样的 `Class.DragDetector` 类。

请注意，像 `Class.ImageButton|ImageButtons`
和 `Class.TextButton|TextButtons` 这样的交互式 UI 元素
仅在它们被附加到 `Class.PlayerGui` 时才会接收用户输入（
`Class.SurfaceGui.Adorneee` 属性可以用于定位 3D 世界中的部件，而
`Class.SurfaceGui` 本身仍保持在 `Class.PlayerGui` 中）。此外，部件的
`Class.BasePart.CanQuery|CanQuery` 属性必须为 `true`，以便交互式 UI 元素可以接收输入。

SurfaceGuiBase.Active

确定 `Class.SurfaceGui` 是否接收用户输入；默认值为 `true`。


`Class.BasePart`，用于应用 `Class.SurfaceGui`，覆盖默认的父级关联。

SurfaceGuiBase.Adornee

`Enum.NormalId` 面的 `Class.SurfaceGui` 父级（或其
`Class.SurfaceGuiBase.Adornee|Adornee`），用于应用 `Class.SurfaceGui`。

SurfaceGuiBase.Face

`Enum.NormalId` 面，适用于应用 `Class.SurfaceGui`。

用于在3D世界中将 `Class.GuiObject|GuiObjects` 渲染到 `Class.BasePart` 的一个面的容器的基类。


**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.GuiObject.ZIndex` 在此 `Class.LayerCollector` 的所有子孙的行为。

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

`Enum.ZIndexBehavior.Global` 根据 `Class.GuiObject.ZIndex|ZIndex` 对所有子孙进行排序，
然后使用层级顺序打破平局。因此，`Class.GuiObject` 的子孙需要有一个
至少与父对象相同的 `Class.GuiObject.ZIndex|ZIndex` 值，否则它们将渲染在父对象之下。


LayerCollector.ZIndexBehavior

控制 `Class.GuiObject.ZIndex` 在此 `Class.LayerCollector` 的所有子孙的行为。


渲染 `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 匹配，则为 true。


previousSelection

在选择更改之前之前选择的 `Class.GuiObject`，如果没有选择则为 nil。


newSelection

在选择更改后现在选择的 `Class.GuiObject`，如果没有选择则为 nil。


当游戏手柄选择移动到、离开或在连接的 `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` 属性将本地化所有作为根实例后代的 `Class.TextLabel.TextButton`。


GuiBase2d.Localize

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


引用一个 `Class.LocalizationTable`，用于对该 `Class.GuiBase2d` 及其后代应用自动本地化。`Class.GuiBase2d.AutoLocalize|AutoLocalize` 必须在 `Class.GuiBase2d` 及其祖先上设置为 `true`，以便应用自动本地化。

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

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

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


GuiBase2d.RootLocalizationTable

引用一个 `Class.LocalizationTable`，用于对该 `Class.GuiBase2d` 及其后代应用自动本地化。


`Class.GuiBase2d.SelectionBehaviorDown|SelectionBehaviorDown` 自定义游戏手柄选择在选择组中向下移动的方式。它仅在 `Class.GuiBase2d.SelectionGroup|SelectionGroup` 为 `true` 时有效；`SelectionGroup` 默认值为 `false`，当它保持为 `false` 时，此属性无效。

其默认值为 `Enum.SelectionBehavior.Escape`，优先选择选择组内的按钮，但如果在组内找不到合适的按钮，则允许选择向下移动到组外的 `Class.GuiObject`。将其设置为 `Enum.SelectionBehavior.Stop` 则限制选择在组内，防止其向下移动出组。

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


GuiBase2d.SelectionBehaviorDown

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


`Class.GuiBase2d.SelectionBehaviorLeft|SelectionBehaviorLeft` 自定义游戏手柄选择在选择组中向左移动的方式。它仅在 `Class.GuiBase2d.SelectionGroup|SelectionGroup` 为 `true` 时有效；`SelectionGroup` 默认值为 `false`，当它保持为 `false` 时，此属性无效。

其默认值为 `Enum.SelectionBehavior.Escape`，优先选择选择组内的按钮，但如果在组内找不到合适的按钮，则允许选择向左移动到组外的 `Class.GuiObject`。将其设置为 `Enum.SelectionBehavior.Stop` 则限制选择在组内，防止其向左移动出组。

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


GuiBase2d.SelectionBehaviorLeft

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


`Class.GuiBase2d.SelectionBehaviorRight|SelectionBehaviorRight` 自定义游戏手柄选择在选择组中向右移动的方式。它仅在 `Class.GuiBase2d.SelectionGroup|SelectionGroup` 为 `true` 时有效；`SelectionGroup` 默认值为 `false`，当它保持为 `false` 时，此属性无效。

其默认值为 `Enum.SelectionBehavior.Escape`，优先选择选择组内的按钮，但如果在组内找不到合适的按钮，则允许选择向右移动到组外的 `Class.GuiObject`。将其设置为 `Enum.SelectionBehavior.Stop` 则限制选择在组内，防止其向右移动出组。

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


GuiBase2d.SelectionBehaviorRight

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


`Class.GuiBase2d.SelectionBehaviorUp|SelectionBehaviorUp` 自定义游戏手柄选择在选择组中向上移动的方式。它仅在 `Class.GuiBase2d.SelectionGroup|SelectionGroup` 为 `true` 时有效；`SelectionGroup` 默认值为 `false`，当它保持为 `false` 时，此属性无效。

其默认值为 `Enum.SelectionBehavior.Escape`，优先选择选择组内的按钮，但如果在组内找不到合适的按钮，则允许选择向上移动到组外的 `Class.GuiObject`。将其设置为 `Enum.SelectionBehavior.Stop` 则限制选择在组内，防止其向上移动出组。

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


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: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()` 被销毁之前立即触发（或延迟到之后）。

演示 `Class.Instance.StyledPropertiesChanged`。


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

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` 则为 `nil`。

创建实例及其所有后代的副本，忽略不为 `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` 的第一个祖先，`Class.Object:IsA()` 对于给定的 className 返回 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` 的第一个祖先，`Class.Object:IsA()` 对于给定的 className 返回 true。

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

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

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

如果您需要在继续之前验证对象是否存在，则需要使用 `FindFirstChild()`。尝试使用点运算符按名称索引子对象，如果子对象不存在，将引发错误。

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

-- 如果部件在工作区中不存在，以下行将引发错误
Workspace.Part.Transparency = 0.5
```
更好的方法是使用 `FindFirstChild()` 首先检查 `Part`，然后使用 `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` 的属性相同。当使用点运算符时，如果它们共享名称，属性优先于子对象。

在以下示例中，添加到 `Class.Part` 的名为 `Color` 的 `Class.Folder`，它也具有 `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`。如果可选的递归参数为 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("Attribute changed")
end

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

Instance:GetAttributeChangedSignal

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

在给定属性更改时触发的事件。

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

此方法返回每个属性的键值对字典，其中键是属性名称，值是非 `nil` 值。

例如，以下代码片段输出实例的属性和值：

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

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

for name, value in part:GetAttributes() do
	print(name .. " = " .. value)
end
```
另请参见 `Class.Instance:GetAttribute()`，它返回分配给给定属性名称的值。

Instance:GetAttributes

每个属性的字符串 → 变体对的字典，其中字符串是属性名称，变体是非 `nil` 值。

Instance

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

/reference/engine/classes/SurfaceGui.yaml

摘要