`Class.SurfaceGui` 允許將 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="在一個 3D 部件上使用 SurfaceGui 並帶有 ImageLabel 子元素以描繪屏幕控制台的圖示。" />

請注意，像 `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 元素可以接收輸入。

請參閱 [體驗中的 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` 來在黑暗的房間裡提高視頻廣告牌的亮度。

請注意，`Class.SurfaceGui.Brightness|Brightness` 在 Studio 中不可訪問，並在 `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` 的內容。如果保持相同大小，則較高的值將導致其中的各種 `Class.GuiObject|GuiObjects` 顯得較小。相反，較低的值將導致物體顯得較大。然而，如果通過使用 `Class.UIScale`、`Class.GuiObject.Size`、`Class.TextLabel.TextSize` 或類似的方式進行了比例縮放，則此屬性允許使用更高的定義。

根據您預期的玩家觀察 `Class.SurfaceGui` 的距離選擇值是很重要的。請注意，較大的像素密度可能會對性能產生負面影響，尤其是在裝飾的部件表面足夠大時。


SurfaceGui.PixelsPerStud

決定用於每個世界空間螺栓的像素密度，以渲染 `Class.SurfaceGui` 的內容。


當設置為 `Enum.SurfaceGuiSizingMode.PixelsPerStud`（默認值）時，`Class.SurfaceGui` 根據 `Class.SurfaceGui.PixelsPerStud|PixelsPerStud` 與表面的大小在螺栓中進行變量大小渲染。

當設置為 `Enum.SurfaceGuiSizingMode.FixedSize` 時，`Class.SurfaceGui` 通過 `Class.SurfaceGui.CanvasSize|CanvasSize` 設置固定大小。


SurfaceGui.SizingMode

決定 `Class.SurfaceGui` 是固定大小渲染還是隨著其在螺栓中的大小進行縮放。


設置左鍵單擊開始作用於 `Class.SurfaceGui` 而不是持有的 `Class.Tool` 的距離。如果角色位於 `Class.SurfaceGui` 的這個距離內，則 `Class.Tool` 將不會在單擊時激活。


SurfaceGui.ToolPunchThroughDistance

設置左鍵單擊開始作用於 `Class.SurfaceGui` 而不是持有的 `Class.Tool` 的距離。


將這個 `Class.SurfaceGui` 與同一面上的其他對象進行層次化（更改這個不會視覺上將 `Class.SurfaceGui` "提升" 或 "沉沒" 從表面）。


SurfaceGui.ZOffset

將此 `Class.SurfaceGui` 與同一面上的其他 `Class.SurfaceGui|SurfaceGuis` 進行層次化。


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


`Class.SurfaceGuiBase` 是容器的 `Class.LayerCollector` 基類，這些容器
將其 `Class.GuiObject` 後代渲染到 3D 世界中 `Class.BasePart` 的一個面上。 `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** 是 2D UI 容器的基類，這些容器渲染 `Class.GuiObject` 的子類，
例如 `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` 的子代上的行為。


2D UI 容器的基類，該容器在層中渲染 `Class.GuiObject|GuiObjects`

`Class.GuiBase2d` 是由 2D `Class.GuiObject|GuiObjects` 繼承的抽象類別。


當遊戲手柄選擇移動到、離開或在連接的 `Class.GuiBase2d` 或任何後代 `Class.GuiObject|GuiObjects` 中變更時，會觸發此事件。當選擇高亮移動到 `Class.GuiObject` 時，事件會從該 `Class.GuiObject` 冒泡到其所有祖先，通知他們選擇已變更/進入/退出其後代樹中的 `Class.GuiObject`。


GuiBase2d.SelectionChanged

amISelected

如果新選擇與附加的 GuiBase2d 匹配，則為真。


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` 及其祖先上將 `Class.GuiBase2d.AutoLocalize|AutoLocalize` 設置為 `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 的 Parent 隨著時間設置為不同的值。部分的父項是該部分的祖先，因此每當發生變化時，`Class.Instance.AncestryChanged` 事件將被觸發。

當此實例被重新父級化或其任何祖先被重新父級化時觸發。

您可以使用此事件來跟踪 Studio 中實例的刪除，
例如在 Explorer 中手動刪除或通過插件刪除。如果您需要
檢測使用 `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` 之後觸發。


以下範例在任何後代被移除時打印其名稱

從 Workspace 中：

此事件在父級 `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.Object.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
```
更好的方法是使用 `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` 的屬性相同。使用點運算符時，如果它們共享名稱，則屬性優先於子物件。

在以下示例中，將一個名為 `Color` 的 `Class.Folder` 添加到 `Class.Part`，該 `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` 的第一個子物件，對於給定的 className，`Class.Object:IsA()` 返回 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` 的第一個子物件，對於給定的 className，`Class.Object:IsA()` 返回 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

Instance

`Instance` 是 Roblox 類別層級中所有類別的基礎類別
可以成為 `Class.DataModel` 樹的一部分。


/reference/engine/classes/SurfaceGui.yaml

概要