一個 Accoutrement 將其子 `Class.Part|part` 叫做 "Handle" 的部件焊接到
玩家的角色上。您可以使用 `Class.Accoutrement.AttachmentPos|AttachmentPos`、
`Class.Accoutrement.AttachmentRight|Right`、
`Class.Accoutrement.AttachmentForward|Forward` 和
`Class.Accoutrement.AttachmentUp|Up` 屬性來更改 Handle 部件的
位置和旋轉。

當 Accoutrement 附加到其他部件時，其衍生部件是無質量的
（例如，使用 Weld），只要它們不是 `Class.BasePart:GetRootPart()|GetRootPart()` 返回的
組件的根部件。此時，`Class.BasePart:GetMass()|GetMass()` 返回 0，並且它
不會增加組件的總質量或轉動慣量。

這不適用於當一個 Accoutrement 焊接到另一個無質量部件上，或其
一個部件變為根部時，從 Accoutrement 衍生的部件。此外，這也不適用於根部件，
根部件的質量與普通部件相同。


Accoutrement

設置物體在玩家身上的偏移位置。


Accoutrement.AttachmentForward

Accoutrement.AttachmentPoint

Accoutrement.AttachmentPos

Accoutrement.AttachmentRight

Accoutrement.AttachmentUp

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

無法直接創建根 `Instance` 對象，但特殊的 `Datatype.Instance.new()` 構造函數通過代碼創建對象，並以類別的名稱作為參數，返回創建的對象。


演示如何通過連接到 `Class.Instance.AncestryChanged` 事件來檢測實例的祖先變化。

ChangingPart 的 Parent 隨著時間的推移而設置為不同的值。部分的父級是該部分的祖先，因此每當它變更時，`Class.Instance.AncestryChanged` 事件就會觸發。

當對象的 `Class.Instance.Parent` 屬性或其祖先之一被更改時觸發。

此事件包括兩個參數：`child` 指的是實際上 `Class.Instance.Parent` 被更改的 `Class.Instance`，而 `parent` 指的是此實例的新 `Class.Instance.Parent`。

你可以使用此事件追蹤在 Studio 中實例的刪除，例如通過 Explorer 手動刪除或通過插件。如果你需要檢測一個實例使用 `Class.Instance:Destroy()` 被銷毀的時機，請使用 `Class.Instance.Destroying` 事件。


Instance.AncestryChanged

child

已更改其 `Class.Instance.Parent` 的 `Class.Instance`。


parent

被更改的 `Class.Instance` 的新 `Class.Instance.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("Styled properties changed")
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.BasePart|BaseParts` 的所有後代，這些後代來自 `Class.Model`：

```
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()` 函數銷毀一個零件。

這個函數是正確處理不再需要的物件的方法。

將 `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` 的第一個祖先，`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` 也具有 `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()` 上的遞歸參數。


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 值。


下面的代碼會在執行時打印出當前在工作區中的所有物件名稱。

返回一個數組（數字索引表）包含所有實例的直接子項，或所有 `Class.Instance` 其 `Class.Instance.Parent|Parent` 等於該對象。可以使用數字或通用 `for` 循環進行迭代：

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

-- 數字循環範例
local children = Workspace:GetChildren()
for i = 1, #children do
	local child = children[i]
	print(child.Name .. " is child number " .. i)
end
```

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

-- 通用循環範例
local children = Workspace:GetChildren()
for i, child in children do
	print(child.Name .. " is child number " .. i)
end
```
請注意，返回的數組 **不** 以任何特定順序排序，因此建議手動排序（例如使用 `Library.table.sort()`）以排序通過此方法返回的子項。

另請參見 `Class.Instance:GetDescendants()|GetDescendants()` 方法。


Instance:GetChildren

返回包含所有實例子項的數組。


Instance:getChildren

返回 Roblox 內部使用的調試 ID 的編碼字符串。請注意：

- 此項是受保護的。在 `Class.Script` 或 `Class.LocalScript` 中嘗試使用它將導致錯誤。
- 調試 ID 是在調試過程中使用的 ID。它允許調試器在應用程序處理之前讀取每個指令。Roblox 中的所有對象都像進程一樣運行，每次運行的指令（或者"代碼"）在需要時都可以進行調試。
- 這對於需要區分彼此相似對象的插件可能會有幫助（例如，共享相同名稱的對象）。


Instance:GetDebugId

scopeLength

返回 Roblox 內部使用的調試 ID 的編碼字符串。


GetDescendants 通常用於對所有子孫物件進行某些操作，這些物件是特定類型的物件。這個示例中的程式碼使用 GetDescendants 和 `Class.Instance:IsA()` 來找到工作區中的所有部件並將它們變成綠色。

此對象方法返回一個數組，包含該對象的所有後代。與 `Class.Instance:GetChildren()` 不同，該方法僅返回對象的直接子項，此方法查找對象的每個子項、每個子項的子項，依此類推。

請注意，返回的數組 **不** 以任何特定順序排序，因此建議手動排序（例如使用 `Library.table.sort()`），以便按組合子項返回的後代進行排序。此外考慮使用 `Class.Instance:QueryDescendants()|QueryDescendants()` 方法，以用選擇器和組合器的組合查詢後代。


Instance:GetDescendants

返回包含實例所有後代的數組。


此代碼範例演示了 `Class.Instance:GetFullName()` 的行為。

它展示了當在不在 `DataModel` 階層中的物件上調用該函數時的行為，
並且還顯示了返回值如何不轉義特殊字符。

'此代碼範例重新實作了`Class.Instance:GetFullName()`函數
    在
    Lua。'

返回描述實例祖先的字符串。該字符串是 `Class.Instance.Name|Name` 的串聯以及其祖先，用句點分隔。`Class.DataModel`（`game`）不被考慮。例如，位於 `Class.Workspace` 中的 `Class.Part` 可能返回 `Class.Workspace.Part`。

當在不是 `Class.DataModel` 的後代上調用此方法時，此方法考慮所有祖先，最高的一個沒有 `Class.Instance.Parent|Parent`。

此方法對於日誌記錄和調試非常有用。您不應嘗試對返回的字符串進行解析以執行任何有用的操作；此方法不會轉義對象名稱中的句點（或任何其他符號）。換句話說，儘管其輸出通常看起來是一個有效的 Luau 標識符，但這並不保證。


Instance:GetFullName

返回描述實例的祖先的字符串。


此方法返回指定屬性的樣式或明確修改的值，或者如果尚未樣式/修改，則返回屬性的默認值。這與直接訪問屬性值有所不同，例如 `[GuiObject].Rotation`，該方法返回屬性的默認值或修改值。

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

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

local coreSheet = ReplicatedStorage:FindFirstChild("CoreSheet")
local rule = coreSheet:FindFirstChildWhichIsA("StyleRule")
rule.Selector = "TextButton"

-- 對按鈕的引用
local button = HUDContainer:FindFirstChildWhichIsA("TextButton")

print(button:GetStyled("Rotation")) --> 0 (默認值)
print(button.Rotation) --> 0 (默認值)

-- 通過樣式規則屬性應用旋轉
rule:SetProperty("Rotation", 30)

print(button:GetStyled("Rotation")) --> 30 (基於規則的樣式值)
print(button.Rotation) --> 0 (默認值)

-- 明確修改/覆蓋樣式屬性
button.Rotation = 45

print(button:GetStyled("Rotation")) --> 45 (修改值)
print(button.Rotation) --> 45 (修改值)
```


Instance:GetStyled

指定屬性的樣式或明確修改的值，或者如果尚未樣式/修改，則返回屬性的默認值。


返回指定屬性的樣式或明確修改的值，或者如果尚未樣式/修改，則返回屬性的默認值。


此方法返回一個事件，該事件的行為完全類似於 `Class.Instance.StyledPropertiesChanged|StyledPropertiesChanged` 事件，只不過它僅在給定的樣式屬性更改時被觸發。通常建議使用此方法，而不是連接到 `Class.Instance.StyledPropertiesChanged|StyledPropertiesChanged` 的函數，來檢查樣式屬性名稱。對於同一對象的後續調用該方法，同樣的屬性名稱返回相同的事件。

注意，此事件不會將任何參數傳遞給連接的函數，因此更改屬性的值必須在腳本內直接讀取。

```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:GetStyledPropertyChangedSignal("AnchorPoint"):Connect(stylePropertyChanged)
```


Instance:GetStyledPropertyChangedSignal

property

當指定樣式屬性更改時觸發的事件。


此方法返回應用於給定實例的標籤數組，作為字符串。您可以在 Studio 的 [屬性](/studio/properties) 窗口中或在運行時使用 `Class.Instance:AddTag()|AddTag()` 添加標籤。

此方法在您希望同時執行多個標籤的操作時很有用。但是，使用此方法檢查單個標籤的存在效率低；應改用 `Class.Instance:HasTag()|HasTag()` 來檢查特定標籤。


Instance:GetTags

獲取所有應用於實例的標籤的數組。


此方法返回 `true`，如果提供的標籤已被添加到對象。您可以在 Studio 的 [屬性](/studio/properties) 窗口中或在運行時使用 `Class.Instance:AddTag()|AddTag()` 添加標籤。


Instance:HasTag

演示如何確定一個實例是否是另一個實例的祖先，使用 `Class.Instance:IsAncestorOf()`

Workspace 和 SpawnLocation 是 SpawnLocation 的貼圖的祖先。

Workspace 是 SpawnLocation 的祖先。

SpawnLocation 及其貼圖是 Workspace 的後裔，而不是祖先。

Decal 是 SpawnLocation 的後裔，而不是祖先。

如果 `Class.Instance` 是給定後代的祖先，則返回 true。

如果對象的 `Class.Instance.Parent` 或其父對象的 `Class.Instance.Parent` 設置為 `Class.Instance`，則認為 `Class.Instance` 是該對象的祖先。

另請參見 `Class.Instance:IsDescendantOf()`。


Instance:IsAncestorOf

如果 `Class.Instance` 是給定後代的祖先，則為真。


如果 `Class.Instance` 是給定後代的祖先，則返回 true。


如果 `Class.Instance` 是給定祖先的後代，則返回 `true`。

注意，`IsDescendantOf()` 不能與 `nil` 的參數一起使用來檢查對象是否被移除。

另請參見 `Class.Instance:IsAncestorOf()`。


Instance:IsDescendantOf

ancestor

如果 `Class.Instance` 是給定祖先的後代，則為真。


如果 `Class.Instance` 是給定祖先的後代，則返回 `true`。


Instance:isDescendantOf

此方法指示特定屬性是否已從代碼實例的默認值進行修改。如果在通過代碼新創建的實例上調用此方法（`Datatype.Instance.new()`），則此方法將返回 `false`。如果在透過 Studio 工作流程插入的目標，例如 [Explorer](/studio/explorer) 窗口上調用，結果可能會有所不同。

例如，查詢 `Class.TextLabel.BackgroundColor3|BackgroundColor3` 屬性從 [Explorer](/studio/explorer) 插入的 `Class.TextLabel` 將返回 `true`，但查詢通過 `Datatype.Instance.new()` 創建的 `Class.TextLabel` 的相同屬性將返回 `false`，假設沒有對其 `Class.TextLabel.BackgroundColor3|BackgroundColor3` 屬性進行其他更改。

注意，如果此方法返回 `true`，則樣式將 **不** 影響該屬性，因為明確修改屬性將優先於樣式。要將屬性重置為其代碼實例的默認設置並允許樣式作用於該屬性，請使用 `Class.Instance:ResetPropertyToDefault()|ResetPropertyToDefault()`。


Instance:IsPropertyModified

布爾值，指示該屬性是否從其代碼實例的默認值進行了修改。


如果存儲在指定屬性中的值不等於代碼實例的默認值，則返回 `true`。


此對象方法返回一個數組，該數組包含匹配提供的 `selector` 字符串的對象的後代。`selector` 字符串可以包含多個選擇器和組合器，以匹配對象的特徵，例如類名、實例名、層次關係以及實例屬性和屬性的特定值。`selector` 語法類似於 `Class.StyleRule` 中使用的語法，但對於支持或不支持語法的某些部分有少數差異。

##### 選擇器

<table>
<thead>
  <tr>
    <th>選擇器</th>
    <th>描述</th>
    <th>示例</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td><code>ClassName</code></td>
    <td>匹配指定類別的實例在 `<code>Class.Object:IsA()</code>` 關係中。</td>
    <td><code>SpotLight</code><br /><code>ImageButton</code><br /><code>Part</code></td>
  </tr>
  <tr>
    <td><code>.Tag</code></td>
    <td>匹配帶有 `<code>Class.CollectionService</code>` 標籤的實例。</td>
    <td><code>.Fruit</code><br /><code>.IntenseLight</code></td>
  </tr>
  <tr>
    <td><code>#Name</code></td>
    <td>匹配特定 `<code>Class.Instance.Name</code>` 的實例。</td>
    <td><code>#RedTree</code><br /><code>#CloseButton</code></td>
  </tr>
  <tr>
    <td><code>[property = value]</code></td>
    <td>匹配具有指定屬性的實例，並且該屬性具有指定的值。支持布爾值、數字和字符串值。字母、數字、<code>_</code> 和 <code>-</code> 可以在不使用引號的情況下使用。
    </td>
    <td><code>[CanCollide = false]</code><br />
    <code>[Brightness = "0.5"]</code><br />
    <code>[Name = Folder10]</code><br />
    <code>[Name = "Part.10"]</code></td>
  </tr>
  <tr>
    <td width="30%"><code>[$attribute = value]</code></td>
    <td>匹配具有指定屬性的實例，並且該屬性具有指定的值。與屬性選擇器一樣適用於相同的限制。</td>
    <td width="30%"><code>[$MyAttribute = 10]</code></td>
  </tr>
</tbody>
</table>

請注意，可以組合選擇器。例如，`Model.Apple[$Kind = "Red"][$State = 4]` 將匹配 `Class.Model` 的實例，該實例設置有 `Apple` 標籤，並具有 `Kind` 屬性等於字符串 `"Red"`，以及 `State` 屬性等於 `4`。

##### 組合器

<table>
<thead>
  <tr>
    <th>組合器</th>
    <th>描述</th>
    <th>示例</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td><code>&gt;</code></td>
    <td>匹配是先前過濾器匹配的 <b>直接子項</b> 的實例。</td>
    <td><code>Part &gt; .SwordHandle</code></td>
  </tr>
  <tr>
    <td><code>&gt;&gt;</code></td>
    <td>匹配是先前過濾器匹配的 <b>後代</b> 的實例。</td>
    <td><code>Model &gt;&gt; .TreeOnFire</code></td>
  </tr>
  <tr>
    <td width="10%"><code>,</code></td>
    <td>指定一組多個獨立選擇器的後代查詢。</td>
    <td width="50%"><code>Part.TagA, Part[$UseForce = true]</code></td>
  </tr>
</tbody>
</table>

請注意，默認的第一過濾器是一個後代組合器 `>>`。如果選擇器以 `>` 開頭，只訪問子項；例如 `>Part.Apple` 選擇所有是 `Class.Part` 的直接子項，並且具有 `Apple` 標籤。

默認組合器也可以明確指定，例如 `>>SpotLight.Red` 和 `SpotLight.Red` 是相同的。

只有匹配過濾器的元素才會放入數組。例如，`>#ExistingChild, >#MissingChild, >#AnotherExistingChild` 將返回一個包含兩個元素的數組，缺失的子項將不會為 `nil`。


Instance:QueryDescendants

selector

用於過濾元素的選擇器字符串。


實例的數組（如果沒有匹配選擇器，則為空）。


以下代碼示範了如何在被移除後，將一個部件重新添加到數據模型中：

此方法將對象的 `Class.Instance.Parent` 設置為 `nil`，並對所有後代執行相同操作。

如果在移除之前引用該對象，可以稍後檢索該對象。


Instance:Remove

將對象的 `Parent` 設置為 `nil`，並對所有後代執行相同操作。


Instance:remove

此方法從實例中移除標籤。如果對象沒有該標籤，則不會引發錯誤。成功移除標籤將觸發由 `Class.CollectionService:GetInstanceRemovedSignal()` 創建的信號，並傳入該標籤。

請注意，在標記實例時，通常會使用一些資源來提供該標籤的功能，例如事件連接或表格。為了防止內存泄漏，最好在不再需要標籤時清理這些資源（斷開連接、設置為 `nil` 等）。


Instance:RemoveTag

將屬性重置為其默認值。例如，在 `Class.TextLabel` 上調用 `ResetPropertyToDefault("Rotation")` 相當於將其 `Class.TextLabel.Rotation|Rotation` 設置為 `0`（屬性的默認值）。此方法可用於確保樣式將覆蓋此屬性的默認值。


Instance:ResetPropertyToDefault

此方法將給定名稱的屬性設置為給定值。如果給定的值為 `nil`，則將刪除該屬性，因為默認返回的值是 `nil`。

例如，以下代碼片段將實例的 `InitialPosition` 屬性設置為 `Datatype.Vector3|Vector3.new(0, 10, 0)`：

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

local part = Workspace.Part
part:SetAttribute("InitialPosition", Vector3.new(0, 10, 0))
```

##### 限制條件

命名要求和限制：

- 名稱只能使用字母數字字符。
  - 您還可以包含句點、連字符、斜杠和下劃線。
- 不允許空格或唯一符號（例如 @、~、!）。
- 字符串必須少於 100 個字符。
- 除非調用方是 Roblox 核心腳本（保留給 Roblox），否則不允許以 **RBX** 開頭的名稱。

嘗試將屬性設置為不支持的類型時，將引發錯誤。

##### 另請參見

- `Class.Instance:GetAttribute()`，返回分配給給定屬性名稱的值。
- `Class.Instance:GetAttributes()`，返回實例屬性的鍵值對字典。


Instance:SetAttribute

value

將給定名稱的屬性設置為給定值。


以下代碼會等待一個名為 "Part" 的實例被添加到

    Workspace。

返回具有指定名稱的 `Class.Instance` 的子項。如果子項不存在，它將使當前線程暫停，直到它存在。如果指定了 `timeOut` 參數，則此方法將在指定的秒數後超時並返回 `nil`。

##### 主要使用

`Class.Instance:WaitForChild()|WaitForChild()` 在為 `Class.LocalScript` 中運行的客戶端代碼時極其重要。Roblox 引擎不保證物件從伺服器到客戶端的複製時間或順序。此外，如果一個體驗的 `Class.Workspace.StreamingEnabled` 設置為 true，距玩家角色較遠的 `Class.BasePart|BaseParts` 可能不會被串流到客戶端，這可能會導致腳本在索引客戶端上尚不存在的物件時崩潰。

##### 注意事項

- 如果在呼叫時具有指定名稱的子項存在，則此方法不會暫停。
- `Class.Instance:FindFirstChild()` 是對於被假設存在的物件來說，比 `Class.Instance:WaitForChild()|WaitForChild()` 更有效的替代方案。
- 如果此方法的呼叫超過 5 秒而未返回，且未指定 `timeOut` 參數，則將在輸出中打印警告，提示該線程可能永遠暫停。


Instance:WaitForChild

childName

timeOut

返回具有給定名稱的 `Class.Instance` 的子項。如果子項不存在，將使當前線程等待，直到其存在。


Instance

此屬性確定當經驗被發佈或保存時，實例是否應包括在內，或者當 `Class.Instance:Clone()|Clone()` 在其中一個實例的祖先上被調用時。直接在實例上調用 `Class.Instance:Clone()|Clone()` 如果該實例 **不是** `Class.Instance.Archivable|Archivable`，將返回 `nil`。

在 Studio 中使用 **複製** 或 **複製**/**粘貼** 選項複製對象將忽略其自身的 `Class.Instance.Archivable|Archivable` 屬性，並將 `Class.Instance.Archivable|Archivable` 設置為 `true`。

```
local part = Instance.new("Part")
print(part:Clone())  --> Part
part.Archivable = false
print(part:Clone())  --> nil
```


Instance.Archivable

確定 `Class.Instance` 及其後代是否可以使用 `Class.Instance:Clone()` 複製，並且可以被保存/發佈。


Instance.archivable

允許在此實例內使用的功能集。要使功能生效，必須啟用 `Class.Instance.Sandboxed` 屬性。

此屬性由實驗性功能使用。請參閱 [腳本功能](/scripting/capabilities) 以獲取更多詳細信息。


Instance.Capabilities

允許在此容器內使用的功能集。


`Class.Instance` 的非唯一標識符。名稱用於保持對象層次結構的組織，以及允許腳本訪問特定對象。實例的名稱不能超過 100 個字符。

對象的名稱通常用於通過數據模型層次結構訪問該對象，使用以下方法：

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

local baseplate = Workspace.Baseplate
local baseplate = Workspace["Baseplate"]
local baseplate = Workspace:FindFirstChild("BasePlate")
```
為了使對象可以使用點運算符 (`.`) 訪問，其名稱必須以下劃線或字母開頭，名稱的其餘部分只能包含字母、數字或下劃線（不能有其他特殊字符）。如果對象的名稱不遵循此語法，則無法使用點運算符訪問，Luau 也不會將其名稱解析為標識符。

如果有多個同名的對象是兄弟，任何試圖按該名稱索引對象的操作將僅返回其中一個對象，類似於 `Class.Instance:FindFirstChild()`，但不一定是所需的對象。如果需要通過代碼訪問特定對象，建議為其使用唯一名稱或確保沒有兄弟對象共享相同名稱。

另請參見 `Class.Instance:GetFullName()` 以獲取包括對象層次結構的完整名稱。


Instance.Name

`Class.Instance` 的非唯一標識符。


`Parent` 屬性確定 `Class.Instance` 的層級父項。以下術語在談論此屬性如何設置時常用：

- 當對象的 `Parent` 設置為該對象時，該對象是另一對象的 **子** 對象，或者稱為 **有父類關係**。

- `Class.Instance` 的 **後代** 是該對象的子對象，以及子對象的後代。

- `Class.Instance` 的 **祖先** 是所有該實例的祖先對象。

正是通過 `Parent` 屬性，許多其他 API 成員獲得其名稱，例如 `Class.Instance:GetChildren()|GetChildren()` 和 `Class.Instance:FindFirstChild()|FindFirstChild()`。此屬性還用於管理對象是否存在於經驗中或需要被移除。只要對象的父級在 `Class.DataModel` 中，存儲在變量中，或由另一對象的屬性引用，該對象就會保持在經驗中；否則，該對象將自動被移除。

調用 `Class.Instance:Destroy()|Destroy()` 將會將 `Class.Instance` 和所有後代的 `Parent` 設置為 `nil`，並且也會 **鎖定** `Parent` 屬性。對於被銷毀對象的 `Parent` 設置會引發錯誤。

使用 `Datatype.Instance.new()` 創建的新對象將沒有父項，通常在沒有設置前將不可見或無法運作。

##### 對象複製

由服務器創建的對象在沒有依附於某個被複製的對象之前不會複製給客戶端。創建對象並設置多個屬性時，建議 **最後** 設置 `Parent` 屬性。這確保對象僅複製一次，而不是多次複製許多屬性更改。

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

-- 最後設置新實例的父項（建議）
local part = Instance.new("Part")
part.Position = Vector3.new(0, 10, 0)
part.Parent = Workspace
```
但是，如果將部件附加到尚未設置父項的 `Class.Model`，將每個部件附加到該模型是可以接受的，因為該模型不會被複製。


Instance.Parent

確定 `Class.Instance` 的層級父項。


此屬性曾用於保護 `Class.CoreGui` 服務中的對象免受用戶未經授權的更改。它已被淘汰，現在未執行任何操作。


Instance.RobloxLocked

一個已被淘汰的屬性，曾用於保護 `Class.CoreGui` 對象。


將實例轉變為 **沙盒容器**，這是一個實驗性功能，限制特定容器內的腳本可以執行的行動。請參閱 [腳本功能](/scripting/capabilities) 以獲取更多詳細信息。


Instance.Sandboxed

該實例的唯一標識符，與可能不唯一的 `Class.Instance.Name` 不同。


Instance.UniqueId

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


`Object` 是 Roblox 類別層級中所有類別的基礎類別。
所有 Roblox 引擎定義的其他類別都繼承了 `Object` 的所有成員。
無法直接創建 `Object`。


此範例展示了普通物件和 `Value` 物件上 `Changed` 事件的細微差別。

此範例代碼演示了父物件中的 Changed 事件觸發。

此事件在物件屬性被更改後立即觸發，具有一些例外情況（見下文）。更改後屬性的的新值不會作為參數傳遞。相反，你可以使用 `object[property]` 來訪問它：

```
object.Changed:Connect(function(property)
	print("新屬性的值是", object[property])
end)
```

- 如果你只對監聽特定屬性的變更感興趣，建議使用
  `Class.Object:GetPropertyChangedSignal()|GetPropertyChangedSignal()`
  方法。
- 要監聽屬性中的變化，請參見
  `Class.Instance:GetAttributeChangedSignal()` 和
  `Class.Instance.AttributeChanged`。
- 要檢測子物件的添加或移除，請參見
  `Class.Instance.ChildAdded` 和 `Class.Instance.ChildRemoved`。

對於像 `Class.IntValue` 和 `Class.StringValue` 這樣的 `Class.ValueBase` 物件，
此事件僅在物件的 `Value` 屬性變更時觸發。要檢測在 `Class.ValueBase` 物件中的其他變更，
使用 `Class.Object:GetPropertyChangedSignal()|GetPropertyChangedSignal()`。

#### 限制

此事件對於與物理相關的變更**不**會觸發，例如當 `Class.BasePart.CFrame|CFrame`、
`Class.BasePart.AssemblyLinearVelocity|AssemblyLinearVelocity`、
`Class.BasePart.AssemblyAngularVelocity|AssemblyAngularVelocity`、
`Class.BasePart.Position|Position` 或
`Class.BasePart.Orientation|Orientation` 的屬性因重力而改變。要檢測這些屬性的變更，
考慮使用基於物理的事件，如 `Class.RunService.PreSimulation`。
類似地，當 `Class.BasePart.AssemblyMass|AssemblyMass` 由於材料、大小或密度的變化而更新時，`Changed` 事件不會觸發（但如果你修改了部件的大小，則 `Class.BasePart.Mass|Mass` 的事件會觸發）。

對於頻繁變化的屬性，`Changed` 事件可能不會為每次修改觸發，或者根本不會觸發。**如果屬性改變影響你的遊戲邏輯，請仔細測試**以確保事件按你預期觸發。


Object.Changed

在物件的屬性更改後立即觸發，但有一些限制。


Object

`Object` 是 Roblox 類別層級中所有類別的基礎類別。


/reference/engine/classes/Accoutrement.yaml

Accoutrement

概要

屬性

方法

活動

屬性

方法

活動

此頁面