Instance

该属性决定是否在发布或保存体验时将实例包含在内，或当在实例祖先中调用 Clone() 时是否包含实例。直接调用实例将返回，如果该实例不是不的话。

使用 复制 或 复制 / 粘贴 选项复制工作室中的对象将忽略其自己的 属性并将 设置为 对复制进行粘贴。

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

允许在此实例内使用的脚本功能集。要使能力生效，Instance.Sandboxed属性必须启用。

该属性由实验精选能使用。请参阅脚本功能获取更多详情。

不唯一标识符 Instance 。名称用于保持对象层次结构有序，同时允许脚本访问特定对象。实例名称不能超过 100 个字符的长度。

对象名称经常用于通过数据模型层次访问对象，使用以下方法：

local Workspace = game:GetService("Workspace")

local baseplate = Workspace.Baseplate
local baseplate = Workspace["Baseplate"]
local baseplate = Workspace:FindFirstChild("BasePlate")

为了使用 dot 运营符访问对象（.），其名称必须以下划线或字母开头，其余名称只能包含字母、数字或下划线（没有其他特殊字符）如果对象的名称不遵循此语法，它将无法使用 dot 运营符访问，Luau也不会将其名称解释为标识符。

如果同一个名称的多个对象是兄弟姐妹，通过该名称索引一个对象的任何尝试都会返回仅一个对象，类似于 Instance:FindFirstChild() ，但并不总是所需的对象。如果特定对象需要通过验证码访问，建议给予它一个唯一名称或保证其兄弟之一没有相同的名称。

还可以参阅Instance:GetFullName()以获得包含对象层次的全名。

Parent 属性决定了 Instance 的层次上级。以下术语在讨论如何设置此属性时常用：

• 一个对象是 孩子 的,或是 被父辈化 的,当其 Parent 设置为该对象时,另一个对象。

• 一个 下一代 的子孙是该对象的子孙，加上孩子的后代也是子孙。

• 一个 Instance 的祖先的 **** 都是实例的子孙。

它来自 Parent 属性，许多其他 API 成员从中获得名称，例如 GetChildren() 和 FindFirstChild() .该属性也用于管理对象是否存在于体验中或需要删除。只要对象的父级在 DataModel 中，被存储在变量中，或被另一个对象的属性引用，对象就会留在体验中；否则，对象将自动被删除。

调用 Destroy() 将设置 Parent 的 Instance 和所有其子孙的 nil 为 **** ,还将 Parent 属性。当设置已删除对象的 Parent 时，出现错误。

使用 Instance.new() 创建的新对象不会有父元素级，通常在设置一个父级之前不会可见或功能。

对象复制

服务器创建的对象在复制到某个被复制的对象之前不会复制到客户端。当创建对象并设置许多属性时，建议设置 Parent 属性 last 。这可以确保对象只复制一次，而不是复制许多属性变更。

local Workspace = game:GetService("Workspace")

-- 设置新实例的父最后（推荐）
local part = Instance.new("Part")
part.Position = Vector3.new(0, 10, 0)
part.Parent = Workspace

然而，如果父辈部分还没有设置到 Model 的父辈，将每个部分都设置为该模型是可接受的，因为模型不会复制。

此属性用于保护 CoreGui 服务中的对象免受未经授权的用户更改。它已经过时且不做任何事情。

将实例转换为 沙盒容器 ,一个实验功能，限制特定容器内的脚本可以执行的操作。请参阅脚本功能获取更多详情。

与 Instance.Name 不同的实例标识符，不一定是独一无二的。

该方法对实例应用标签，如果标签已应用，没有效果。成功添加标签会触发由 CollectionService:GetInstanceAddedSignal() 创建的信号，其标签与指定的标签相同。

警告

• 服务器稍后添加或移除了该实例上的标签，客户端添加的标签将被丢弃，因为服务器复制所有标签并覆盖以前的标签。

• 当标记实例时，常见的是一些资源被用来给标签提供功能，例如事件连接或表。为了防止内存泄漏，清理这些（断开、设置为 nil 等）当标签不再需要时是个好主意。在调用 Instance:RemoveTag() 、调用 Instance:Destroy() 或在与 CollectionService:GetInstanceRemovedSignal() 返回的信号连接的函数中执行时，执行此操作。

参数

返回

此函数摧毁所有实例的子女和后裔。

如果你不想摧毁所有 孩子和后裔 ，使用 Instance:GetChildren() 或 Instance:GetDescendants() 循环那些孩子/后裔并选择要摧毁的内容例如，以下代码示例将摧毁所有 BaseParts 从一个 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

返回

local part = Instance.new("Part")

-- add some sparkles
for _ = 1, 3 do
	local sparkles = Instance.new("Sparkles")
	sparkles.Parent = part
end

print("Part has", #part:GetChildren(), "children")
--> Part has 3 children

part:ClearAllChildren()

print("Part has", #part:GetChildren(), "children")
--> Part has 0 children

Clone() 创建一个实例的副本和所有其子孙，忽略所有不是 Archivable 的实例。根实例的副本由此方法返回，其 Parent 设置为 nil 。请注意，如果实例本身设置为 Archivable 设置为 false ，该函数将返回 nil 。

如果引用属性，例如 ObjectValue.Value 在克隆实例中设置，复制属性的值取决于原始值：

• 如果参考属性指向复制了 也 的实例，复制将指向复制。
• 如果参考属性指向未被复制的对象，复制中保留相同的值。

返回

local Workspace = game:GetService("Workspace")

-- Get a reference to an existing object
local model = script.Parent.Model

-- Create a clone of the model
local clone = model:Clone()

-- Move the clone so it's not overlapping the original model
clone:PivotTo(model.PrimaryPart.CFrame - (Vector3.xAxis * 10))

-- Add the clone to the Workspace
clone.Parent = Workspace

将 Instance.Parent 属性设置为 nil , 锁定 Instance.Parent 属性，断开所有连接，并在所有子级上调用 Destroy() 。这个函数是丢弃不再需要的对象的正确方法。

卸下不需要的对象很重要，因为在一个地方不需要的对象和连接会使用掉记忆，从而导致随着时间的推移出现严重的性能问题。

在调用 Destroy() 对象后，将对象（或其子对象）的任何变量设置为 nil 。这防止您的代码访问与对象有关的任何东西。

local part = Instance.new("Part")
part.Name = "Hello, world"
part:Destroy()
-- 不要这样做：
print(part.Name) --> “你好，世界”
-- 这样做可以防止上面的线工作：
part = nil

一旦使用此方法摧毁了 Instance ，由于 Instance.Parent 属性被锁定，无法重复使用。要 暂时 取消对象的破坏，设置 Parent 为 nil。例如：

local Workspace = game:GetService("Workspace")

object.Parent = nil
task.wait(2)
object.Parent = Workspace

要在一定时间后摧毁一个对象，请使用 Debris:AddItem() 。

返回

local part = script.Parent.Part

part:Destroy()

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

这个函数向上工作，意味着它从实例的即时 Instance.Parent 开始工作，并向 DataModel 工作。如果未找到匹配的祖先，它将返回 nil。

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

local car = object:FindFirstAncestor("Car")

对于这个函数的变体，找到特定类别的祖先，请参阅 Instance:FindFirstAncestorOfClass() 和 Instance:FindFirstAncestorWhichIsA() 。

参数

返回

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

这个函数向上工作，意味着它从实例的即时 Instance.Parent 开始工作，并向 DataModel 工作。如果未找到匹配的祖先，它将返回 nil。

这个函数的常见使用是找到 Model 一个 BasePart 属于。例如：

local model = part:FindFirstAncestorOfClass("Model")

该函数是 Instance:FindFirstAncestor() 的变体，检查 Object.ClassName 属性而不是 Instance.Name 。Instance:FindFirstAncestorWhichIsA() 也存在，使用 Object:IsA() 方法来尊重类继承。

参数

返回

返回第一个祖先的 Instance 为谁 Object:IsA() 返回给定类别的真实。

这个函数向上工作，意味着它从实例的即时 Instance.Parent 开始工作，并向 DataModel 工作。如果未找到匹配的祖先，它将返回 nil。

与 Instance:FindFirstAncestorOfClass() 不同，此函数使用 Object:IsA() ，这与类继承有关。例如：

print(part:IsA("Part"))  --> true
print(part:IsA("BasePart"))  --> true
print(part:IsA("Instance"))  --> true

因此，以下代码示例将返回第一个 BasePart 祖先，无论是 WedgePart 、 MeshPart 还是 Part 。

local part = object:FindFirstAncestorWhichIsA("BasePart")

还见 Instance:FindFirstAncestor() 。

参数

返回

返回 Instance 的第一个孩子以指定的名称，或 nil 如果没有这样的孩子存在。如果可选的 recursive 参数是 true , 这个函数搜索所有子孙，而不仅限于 Instance 的直接子女。

检查对象的存在

FindFirstChild() 必须如果你需要在继续前验证对象存在。尝试使用 dot 运营符索引子女按名称索引时，如果子女不存在，将抛出错误。

local Workspace = game:GetService("Workspace")

-- 如果零件不存在工作区，以下行错误
Workspace.Part.Transparency = 0.5

使用 FindFirstChild() 首先检查 Part ,然后使用 if 声明运行需要它的代码。

local Workspace = game:GetService("Workspace")

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

找到一个名称与属性匹配的孩子

有时一个对象的 Name 与其属性的 Parent 相同。当使用点运营符时，如果属性共享名称，它们会在孩子之前占据优先权。

在下面的例子中，一个 Folder 称为“颜色”的被添加到 Part ，这也有 Part.Color 属性。Part.Color 指的是 Color3 ，而不是文件夹。

local part = Instance.new("Part")
local folder = Instance.new("Folder")
folder.Name = "Color"
folder.Parent = part
local c = part.Color --> 颜色 3
local c2 = part:FindFirstChild("Color") --> The Folder

使用 FindFirstChild() 的好处之一是，引入新属性不会对您的验证码造成风险。

性能说明

FindFirstChild() 使用点运营符比使用 dot 运营符多花费约 20% 时间，几乎是存储对象引用的 8 倍。因此，您应该避免在紧密循环或连接到 RunService.Heartbeat 和 RunService.PreRender 的函数中调用它。相反，将结果存储在变量中，或考虑使用 ChildAdded 或 WaitForChild() 来检测给定名称的子域何时可用。

参数

返回

local found = workspace:FindFirstChild("Brick")

if found then
	found.Name = "Foo"
end

返回 Instance 的第一个孩子，其 ClassName 与给定的 className 相等。与 Instance:FindFirstChildWhichIsA() 不同，这个函数只返回那些类匹配 className 的对象，忽略了类继承。如果未找到匹配的子，该函数返回 nil 。

参数

返回

local Players = game:GetService("Players")

local player = Players.LocalPlayer
local character = player.Character or player.CharacterAdded:Wait()

local humanoid

while not humanoid do
	humanoid = character:FindFirstChildOfClass("Humanoid")
	if not humanoid then
		character.ChildAdded:Wait()
	end
end

返回 Instance 为谁 Object:IsA() 返回真实给定类别的第一个孩子。

如果未找到匹配的子，该函数返回 nil 。如果可选递归性参数为真值，此函数搜索所有子孙，而不仅限于 Instance 的直接子女。

与 Instance:FindFirstChildOfClass() 不同，此函数使用 Object:IsA() ，这与类继承有关。例如：

print(part:IsA("Part")) --> 真实
print(part:IsA("BasePart")) --> 真实
print(part:IsA("Instance")) --> true

因此，以下代码示例将返回第一个 BasePart 子，无论是 WedgePart 、 MeshPart 还是 Part 。

local part = object:FindFirstChildWhichIsA("BasePart")

寻找名称的孩子的开发人员应该使用 Instance:FindFirstChild() 而不是。

参数

返回

返回找到的第一个子孙，使用给定的 Instance.Name 。

该方法已禁用且无法使用。要找到实例的第一个后裔，请考虑使用 recursive 参数在 Instance:FindFirstChild() 上。

参数

返回

如果 Instance 是一个 Actor，那么 Actor 本身就会返回。否则，其最近的祖先 Actor 将被返回。如果没有祖先是 Actor , 结果是 nil .

返回

该方法返回被分配给指定属性名称的值。如果没有分配属性，nil 将返回。

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

local Workspace = game:GetService("Workspace")

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

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

还看到也看到

• Instance:SetAttribute() 将带有给定名称的属性设置为给定值。
• Instance:GetAttributes() 返回每个实例属性的键值对词典。

参数

返回

此函数返回与 Changed 事件相似的事件，除了它仅在特定给定属性发生变化时发射外，实际上与 GetPropertyChangedSignal() 类似，但仅适用于属性。

一般来说，使用此方法取代连接到 Changed 以检查属性名称的函数是一个好主意。对同一个对象上的相同属性名称的后续调用此方法返回相同的事件。

以下代码示例返回一个信号，该信号会在零件的 InitialPosition 属性发生变更时触发函数 attributeChanged()：

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)

还请注意 Instance.AttributeChanged ，它会在实例上更改任何属性时触发。

参数

返回

这个方法返回每个属性中键是属性名称，值是非 nil 值的键值对的词典。

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

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

还看到 Instance:GetAttribute() ，它返回被指定给给定属性名称的值。

返回

返回一个阵列（数字索引的表），包含所有实例的直接子女，或每个 Instance 其 Parent 与对象相等。使用数字或通用循环进行遍历时，阵列可以被遍历：

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

local Workspace = game:GetService("Workspace")

-- 通用循环示例
local children = Workspace:GetChildren()
for i, child in children do
	print(child.Name .. " is child number " .. i)
end

孩子们按其 Parent 属性设置到对象的顺序排序。

还看到 GetDescendants 函数。

返回

local children = workspace:GetChildren()

for i = 1, #children do
	print(i, children[i].Name)
end

返回由 Roblox 内部使用的调试 ID 编码的字符串。请注意：

• 该项目受到保护。尝试在 Script 或 LocalScript 中使用将导致错误。
• 调试ID是用于调试过程的ID。它允许调试器在应用程序处理之前阅读每个指令。Roblox 中的所有对象都像过程一样，每个运行验证码令（或“代码”）都可以在需要时进行调试。
• 这可能对需要区分相似对象的插件（例如共享相同名称的对象）有帮助。

参数

返回

print(workspace:GetDebugId()) --> 39FA_12
print(workspace:GetDebugId(10)) --> 39FA2FEF4D_12
print(workspace:GetDebugId(math.huge)) --> 12

这个对象方法返回包含该对象所有子对象的阵列。与 Instance:GetChildren() 不同，这个方法找到了对象的即时子女，那些子女的每个子女，以及如此等等。

返回

local descendants = workspace:GetDescendants()

-- Loop through all of the descendants of the Workspace. If a
-- BasePart is found, the code changes that parts color to green
for _, descendant in pairs(descendants) do
	if descendant:IsA("BasePart") then
		descendant.BrickColor = BrickColor.Green()
	end
end

返回描述实例祖先的字符串。字符串是对象和其祖先的 Name 的连接，用逗号分开。不考虑 DataModel （ game ）。例如，一个 Part 在 Workspace 中可能返回 Workspace.Part。

当调用到一个 Instance 这不是DataModel 的子孙时，这个函数会考虑所有祖先，直到最高一个没有 Parent 。

该函数对于记录和调试有用。你不应该尝试解析返回的字符串以进行任何有用的操作；该函数不会逃避对象名称中的时间符号（或任何其他符号）。换言之，尽管其输出经常看起来是一个有效的 Luau 标识符，但它不是保证的。

返回

-- Create a simple hierarchy
local model = Instance.new("Model")
local part = Instance.new("Part")
part.Parent = model
local fire = Instance.new("Fire")
fire.Parent = part

print(fire:GetFullName()) --> Model.Part.Fire

model.Parent = workspace

print(fire:GetFullName()) --> Workspace.Model.Part.Fire

part.Name = "Hello, world"

print(fire:GetFullName()) --> Workspace.Model.Hello, world.Fire

local function getFullName(object)
	local result = object.Name
	object = object.Parent
	while object and object ~= game do
		-- Prepend parent name
		result = object.Name .. "." .. result
		-- Go up the hierarchy
		object = object.Parent
	end
	return result
end

print(getFullName(workspace.Camera)) --> Workspace.Camera

参数

返回

参数

返回

该方法返回给定实例应用的标签的阵列，作为字符串。您可以在 Studio 的 属性 窗口或在运行时添加标签 AddTag() .

当您想要一次使用多个标签对实例进行操作时，此方法很有用。然而，使用此方法检查单个标签的存在是不高效的；相反，使用 HasTag() 检查特定标签。

返回

该方法返回 true 如果提供的标签已添加到对象。您可以在 Studio 的 属性 窗口或运行时添加标签 AddTag()。

参数

返回

返回 true 如果 Instance 是指定后后代的祖先。

一个 Instance 被视为对象的祖先，如果对象的 Instance.Parent 或其父元素系中的一个 Instance.Parent 被设置为 Instance 。

还见，Instance:IsDescendantOf()。

参数

返回

local Workspace = game:GetService("Workspace")
local spawnLocation = Workspace.SpawnLocation
local decal = spawnLocation.Decal

-- These statements are true
print(Workspace:IsAncestorOf(spawnLocation))
print(Workspace:IsAncestorOf(decal))
print(spawnLocation:IsAncestorOf(decal))

-- These statements are false
print(spawnLocation:IsAncestorOf(Workspace))
print(decal:IsAncestorOf(Workspace))
print(decal:IsAncestorOf(spawnLocation))

返回 true 如果 Instance 是指定祖先的后裔。

请注意，IsDescendantOf() 不能与 nil 的参数一起使用，以检查对象是否已删除。

还见 Instance:IsAncestorOf() 。

参数

返回

local part = Instance.new("Part")
print(part:IsDescendantOf(game))
--> false

part.Parent = workspace
print(part:IsDescendantOf(game))
--> true

part.Parent = game
print(part:IsDescendantOf(game))
--> true

返回 true 如果指定属性中存储的值不是默认值。例如，如果输出 Rotation 属性的 TextLabel 表示 0 ，那么调用 IsPropertyModified("Rotation") 标签将返回 false 因为 0 是默认值为 TextLabel.Rotation 的。

参数

返回

该方法从实例中移除标签。如果对象没有标签，它不会抛出错误。成功删除标签会触发由 CollectionService:GetInstanceRemovedSignal() 创建的信号，其标签与指定的标签相同。

请注意，标记实例时，常见的是某些资源被用来提供标签其功能，例如事件连接或表。为了防止内存泄漏，清理这些（断开、设置为 nil 等）当标签不再需要时是个好主意。

参数

返回

将属性重置为默认值。例如，调用 ResetPropertyToDefault("Rotation") 在 TextLabel 上与将其 Rotation 设置为 0 (属性的默认值) 相等。

参数

返回

该方法将带有给定名称的属性设置为给定值。如果给出的值是 nil , 特性将被移除，因为 nil 默认返回。

例如，以下代码片段将实例的 InitialPosition 属性设置为 Vector3.new(0, 10, 0) :

local Workspace = game:GetService("Workspace")

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

限制

命名要求和限制：

• 名称只能使用字母数字字符和斜线。
• 不允许使用空格或独特符号。
• 字符串必须少于 100 个字符或更少。
• 名称不允许以 RBX 开始，除非调用者是 Roblox 核心脚本（仅用于 Roblox）。

当尝试将属性设置为未支持类输入时，将抛出错误。

还看到也看到

• Instance:GetAttribute() 返回被分配给给定属性名称的值。
• Instance:GetAttributes() 返回每个实例属性的键值对词典。

参数

返回

返回 Instance 的孩子与给定的名称。如果孩子不存在，它将生成当前线程直到它存在。如果指定了 timeOut 参数，该方法将在指定的秒数后过期并返回 nil 。

主要用途

WaitForChild() 在 LocalScript 中运行的客户端代码时工作时，与运行代码息息相关。Roblox 引擎不保证对象从服务器复制到客户端的时间或顺序。此外，如果体验设置为真实，那么远离玩家角色的 可能不会被传送到客户端，可能会导致客户端上的对象索引时出现错误，导致尚未存在的对象破坏脚本。

注释

• 该函数在调用时如果存在指定名称的孩子不会返回。
• Instance:FindFirstChild() 是对假设存在的对象的更高效的替代WaitForChild()。
• 如果调用此方法超过 5 秒而未返回，且未指定任何 timeOut 参数，将在输出上打印警告，说明线程可能无限期生成。

参数

返回

local part = workspace:WaitForChild("Part")
print(part.Name .. " has been added to the Workspace")

当对象或其祖先的 Instance.Parent 属性发生更改时，触发火焰。

该事件包含两个参数：指向了具有>的》的》，其中》实际上已更改，而》指向了这个实例的新》。

您可以使用此事件来跟踪 Studio 中实例的删除，例如手动删除在 Explorer 或通过插件进行。如果需要检测实例是否使用 Instance:Destroy() 被摧毁，请使用 Instance.Destroying 事件。

参数

local Workspace = game:GetService("Workspace")

local redPart = script.Parent.RedPart
local bluePart = script.Parent.BluePart
local changingPart = script.Parent.ChangingPart

-- Change the color of changingPart based on it's Parent
local function onAncestryChanged(part: Part, parent: Instance)
	if parent == redPart then
		changingPart.Color = Color3.new(1, 0, 0)
	elseif parent == bluePart then
		changingPart.Color = Color3.new(0, 0, 1)
	else
		changingPart.Color = Color3.new(1, 1, 1)
	end
	print(`{part.Name} is now parented to {parent.Name}`)
end

changingPart.AncestryChanged:Connect(onAncestryChanged)

-- Set changingPart's Parent property to different instances over time
while true do
	task.wait(2)
	changingPart.Parent = redPart

	task.wait(2)
	changingPart.Parent = bluePart

	task.wait(2)
	changingPart.Parent = Workspace
end

此事件在实例上发生任何属性更改时触发，包括当属性设置为 nil 时。更改的属性名称传递到连接的函数。

例如，以下代码片段将 attributeChanged() 函数连接到发射，每当零件属性之一发生变化时：

local Workspace = game:GetService("Workspace")

local part = Workspace.Part

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

part.AttributeChanged:Connect(attributeChanged)

还看到 Instance:GetAttributeChangedSignal() ，它返回一个事件，当特定给定属性发生变更时触发。

参数

在对象被父辈到这个 Instance 之后发生火焰。

注意，当在客户端使用此函数检测服务器创建的对象时，必须使用 Instance:WaitForChild() 索引这些对象的子集。这是因为对象和其子孙不保证同时从服务器复制到客户端。例如：

local Workspace = game:GetService("Workspace")

Workspace.ChildAdded:Connect(function(child)
	-- Use WaitForChild() since descendants may not have replicated yet
	local head = child:WaitForChild("Head")
end)

注意，此函数仅适用于 Instance 的即时子女。对于捕获所有后裔的函数，请使用 Instance.DescendantAdded 。

还见 Instance.ChildRemoved 。

参数

local function onChildAdded(instance)
	print(instance.Name .. " added to the workspace")
end

workspace.ChildAdded:Connect(onChildAdded)

local part = Instance.new("Part")
part.Parent = workspace --> Part added to the Workspace

在孩子被从此 Instance 移除后发生火焰。

删除指的是当对象的父从这 更改为另一些东西时。注意，此事件也会在孩子被销毁时触发（使用 Instance:Destroy()），因为摧毁函数将父对象设置为 nil。

此函数仅适用于 Instance 的即时子女。对于捕获所有后裔的函数，请使用 Instance.DescendantRemoving 。

还见 Instance.ChildAdded 。

参数

local function onChildRemoved(instance)
	print(instance.Name .. " removed from the workspace")
end

workspace.ChildRemoved:Connect(onChildRemoved)

local part = Instance.new("Part")
part.Parent = workspace

task.wait(2)

part:Destroy()

此事件在添加子孙到 Instance 后发生。

每次发射到每个后后代时，将对象父辈到 Instance 将会独立地发射该对象和所有其子对象的事件。

如果您仅关心 直接子女 的 Instance , 请使用 Instance.ChildAdded 。

还见 Instance.DescendantRemoving 。

参数

local function onDescendantAdded(descendant)
	print(descendant)
end

workspace.DescendantAdded:Connect(onDescendantAdded)

local part = Instance.new("Part")
part.Parent = workspace

此事件在父变更之前立即触发，使子孙实例不再是子后代。Destroy() 修改了实例的 Parent 到 nil ,因此调用父辈的子孙方法会导致此事件发生。

由于此事件在后后代移除之前触发 ，因此在此事件发射时，后裔的父将不会发生变化 如果后裔也是父元素辈的直接子孙，此事件将在 之前发射。

如果后裔有孩子，该事件首先发生在后裔上，然后是其后裔。

警告

这个事件发生在正在被移除的子对象上。尝试将后裔的 Parent 设置为其他东西将失败。以下是一个示例，展示这一点：

local Workspace = game:GetService("Workspace")

Workspace.DescendantRemoving:Connect(function(descendant)
	-- Do not manipulate the parent of the descendant in this function!
	-- This event fires BECAUSE the parent was manipulated, and the change hasn't happened yet
	-- Therefore, it is problematic to change the parent like this:
	descendant.Parent = game
end)

local part = Instance.new("Part")
part.Parent = Workspace
part.Parent = nil

还见 DescendantAdded 。

参数

workspace.DescendantRemoving:Connect(function(descendant)
	print(descendant.Name .. " is currently parented to " .. tostring(descendant.Parent))
end)
local part = Instance.new("Part")
part.Parent = workspace
part.Parent = nil
--> Part is currently parented to Workspace
print(part.Parent)
--> nil

连接的函数仍在使用它时，Instance 将永远不会从内存中删除。然而，如果函数在任何时候返回，其子孙 Instance 和其子孙将被父辈到 nil。

如果 Workspace.SignalBehavior 属性设置为 Enum.SignalBehavior.Immediate ,此事件在 Instance 或其祖先被摧毁之前立即发生，使用 Instance:Destroy() 摧毁。

如果 Workspace.SignalBehavior 属性设置为 Enum.SignalBehavior.Deferred ,该事件将在下一次恢复点触发,这将是在 Instance 或其祖先之一被摧毁后,用 Instance:Destroy() 删除。

使用 Deferred 行为连接脚本到自己的 Instance.Destroying 事件是有问题的，因为脚本在调用回调之前将被摧毁（即不会执行）。

当在 Studio 中删除 Instance 时，例如通过手动删除通过 Explorer 或通过插件来删除， Instance 不会被摧毁。相反，父级被设置为 nil ，您可以通过 Instance.AncestryChanged 跟踪。

local part = Instance.new("Part", workspace)

local function onPartDestroying()
	print("Before yielding:", part:GetFullName(), #part:GetChildren())
	task.wait()
	print("After yielding:", part:GetFullName(), #part:GetChildren())
end

part.Destroying:Connect(onPartDestroying)

part:Destroy()

local part = Instance.new("Part", workspace)

local function onPartDestroying()
	print("In signal:", part:GetFullName(), #part:GetChildren())
end

part.Destroying:Connect(onPartDestroying)

print("Before destroying:", part:GetFullName(), #part:GetChildren())
part:Destroy()
print("After destroying:", part:GetFullName(), #part:GetChildren())