`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` 的工作方式略有不同。雖然 **偏移** 組件的工作方式相同，但 **縮放** 組件作為 3D 空間中的學分大小。

在創建包含 `Class.TextLabel` 的大小縮放的 `Class.BillboardGui` 時，啟用的標籤的 `Class.TextLabel.TextScaled|TextScaled` 屬性會很有用，這樣當相機距離變化時，它的文字與公告牌畫布一起縮放。

請注意，像 `Class.ImageButton|ImageButtons` 和 `Class.TextButton|TextButtons` 這樣的互動式 UI 元件在 `Class.BillboardGui` 中只能接收用戶輸入，前提是它們的父級在 `Class.PlayerGui` 中，通常是通過將 `Class.BillboardGui` 放入 `Class.StarterGui` 中來實現。`Class.BillboardGui.Adornee|Adornee` 屬性可以用來針對 3D 世界中的部件或附件，而 `Class.BillboardGui` 本身仍然保留在 `Class.PlayerGui` 中。

請參見 [體驗內 UI](/ui/in-experience-containers#billboard-ui) 以獲得有關使用 `Class.BillboardGui` 容器的指南。

##### 緩存行為

為了幫助提高性能，`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.BillboardGui` 中只能接收用戶輸入，前提是它們的父級在 `Class.PlayerGui` 中，通常是通過將 `Class.BillboardGui` 放入 `Class.StarterGui` 中來實現。`Class.BillboardGui.Adornee|Adornee` 屬性可以用來針對 3D 世界中的部件或附件，而 `Class.BillboardGui` 本身仍然保留在 `Class.PlayerGui` 中。


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.GuiObject|GuiObjects` 的部分在 `Class.BillboardGui` 畫布邊界之外將不被繪製。

即使該屬性為 `false`，**完全** 在畫布之外的 `Class.GuiObject|GuiObjects` 仍然不會進行渲染。


BillboardGui.ClipsDescendants

確定 `Class.GuiObject|GuiObjects` 的哪些部分在 `Class.BillboardGui` 畫布邊界之外將被繪製。


當前 `Class.BillboardGui` 與玩家的相機之間的距離（以學分為單位）。除非 `Class.BillboardGui.DistanceStep|DistanceStep` 大於 `0`，否則此屬性不會觸發更改事件。


BillboardGui.CurrentDistance

當前 `Class.BillboardGui` 與玩家的相機之間的距離（以學分為單位）。


確定 `Class.BillboardGui` 停止以較大尺寸縮放的距離（以學分為單位），相對於玩家當前的相機，默認為 `0`。如果 `Class.BillboardGui.CurrentDistance|CurrentDistance` 低於此值，它將不會縮放到比在該距離時更大。


BillboardGui.DistanceLowerLimit

確定 `Class.BillboardGui` 停止以較大尺寸縮放的距離（以學分為單位）。


確定玩家的相機靠近或遠離 `Class.BillboardGui` 時，`Class.BillboardGui.CurrentDistance|CurrentDistance` 的增量和減量（以學分為單位）。該屬性默認為 `0`。


BillboardGui.DistanceStep

確定玩家的相機靠近或遠離 `Class.BillboardGui` 時，`Class.BillboardGui.CurrentDistance|CurrentDistance` 的增量和減量（以學分為單位）。


確定 `Class.BillboardGui` 停止以較小尺寸縮放的距離（以學分為單位），相對於玩家當前的相機。如果 `Class.BillboardGui.CurrentDistance|CurrentDistance` 高於此值，它將不會縮放到比在該距離時更小。

如果該值小於 `0`，則將忽略此屬性。默認值為 `-1`，這意味著此屬性默認被忽略。


BillboardGui.DistanceUpperLimit

確定 `Class.BillboardGui` 停止以較小尺寸縮放的距離（以學分為單位）。


此屬性確定 `Class.BillboardGui` 相對於其 `Class.BillboardGui.Adornee|Adornee` 的偏移量，與 `Class.Camera` 取向相關，以模型 `Class.Camera` 對齊邊界框的一半尺寸單位。

另請參見 `Class.BillboardGui.StudsOffset|StudsOffset`，其類似工作但使用學分單位，或 `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`，其類似工作但使用學分單位，或 `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` 不同，此屬性的[縮放](/ui/position-and-size#size)組件設置公告牌在 3D 空間中的學分大小。


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` 的偏移量（以學分為單位），相對於 `Class.Camera` 取向。

另請參見 `Class.BillboardGui.StudsOffsetWorldSpace|StudsOffsetWorldSpace`，其類似工作，但偏移方向相對於全局軸。


BillboardGui.StudsOffset

確定 `Class.BillboardGui` 相對於其 `Class.BillboardGui.Adornee|Adornee` 的偏移量（以學分為單位），相對於 `Class.Camera` 取向。


此屬性確定 `Class.BillboardGui` 相對於其 `Class.BillboardGui.Adornee|Adornee` 的偏移量（以學分為單位），相對於全局軸。

另請參見 `Class.BillboardGui.StudsOffset|StudsOffset`，其類似工作，但偏移方向相對於 `Class.Camera`。


BillboardGui.StudsOffsetWorldSpace

確定 `Class.BillboardGui` 相對於其 `Class.BillboardGui.Adornee|Adornee` 的偏移量（以學分為單位），相對於全局軸。


一個容器，用於 `Class.GuiObject|GuiObjects`，在 3D 空間中面向
相機進行渲染。


**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.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` 如何行為。


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 匹配，則為 true。


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.Root` 屬性指向實例的 `Class.LocalizationTable|LocalizationTables` 將對根實例的所有 `Class.TextLabel.TextButton` 子代進行本地化。


GuiBase2d.Localize

當本地化表格的 `Class.LocalizationTable.Root` 針對此物件或其祖先時，自動設置為 true。


引用要用於對本 `Class.GuiBase2d` 及其子代進行自動化本地化的 `Class.LocalizationTable`。`Class.GuiBase2d.AutoLocalize|AutoLocalize` 必須在 `Class.GuiBase2d` 及其祖先上設置為 `true`，以應用自動化本地化。

您可以在 `Class.DataModel` 中的任何位置設置此引用，以引用 `Class.LocalizationTable`。`Class.GuiBase2d` 物件及其所有子女將嘗試使用該特定的 `Class.LocalizationTable` 及其祖先進行自動文本替換，然後使用 `Class.LocalizationService` 下的表格，順序不定，然後使用雲表格。

如果在引用的表格中沒有可用的翻譯，它會查找該表格的父級中是否也有 `Class.LocalizationTable`，以此類推。

另請參考 `Class.LocalizationService:GetTableEntries()`，該方法解釋了 `Class.GuiBase2d.RootLocalizationTable|RootLocalizationTable` 如何用於自動化本地化。


GuiBase2d.RootLocalizationTable

引用要用於對本 `Class.GuiBase2d` 及其子代進行自動化本地化的 `Class.LocalizationTable`。


自定義遊戲手柄在向下方向的選擇行為。


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 的 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()` 被銷毀之前立即觸發（或推遲到之後）。

此事件每當實例的任何樣式屬性發生變更時觸發，包括當屬性被設置為 `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` 的第一個祖先，該祖先對應於 `Class.Object:IsA()` 返回 true 的給定 className。

此方法向上工作，意味著它從實例的直接 `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()` 返回 true 的給定 className。

以下將在工作區中尋找名為"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()` 返回 true 的給定 className。

如果未找到匹配子物件，則此方法返回 `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()` 返回 true 的給定 className。

返回第一個後代，該後代符合給定 `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

返回在給定屬性更改時引發的事件。

Instance

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

/reference/engine/classes/BillboardGui.yaml