此示例演示了普通对象和 `Value` 对象上 `Changed` 事件的细微差别。


存储一个单一的 [Luau 数字](https://luau.org/syntax#number-literals)，定义为
[双精度浮点数](https://en.wikipedia.org/wiki/Double-precision_floating-point_format)，
或更常见地称为 **double**。这会在 64 位（8 字节）中使用 IEEE 754 表示法存储一个数字（1 个符号位，11 个指数位和 52 个小数位）。最大值和最小值为
&PlusMinus;1.7976931348623157e+308，范围为 &PlusMinus;2^53 以精确表示整数。

像所有的 `Class.ValueBase` 对象一样，这个单一值存储在
`Class.NumberValue.Value|Value` 属性中。`Changed` 事件在对象中存储新值时触发，而不是表示属性变化的字符串。


此示例在每次 `NumberValue` 更改时打印其新值。
这里打印 20。


每当 `Class.NumberValue.Value` 变化时触发。它运行时，将用新的值存储在参数对象中，而不是一个表示被更改属性的字符串。

在使用 `NumberValues` 跟踪排行榜统计数据或物品价格等值的游戏中，监听 `Changed` 信号是很有用的。


NumberValue.Changed

value

每当 `Class.NumberValue.Value` 被更改时触发。


NumberValue.changed

NumberValue

NumberValue.Value

一个用于存储单个双精度浮点数的容器对象。


ValueBase

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

无法直接创建根 `Instance` 对象，但特殊的
`Datatype.Instance.new()` 构造函数通过代码创建对象，
以类的名称作为参数并返回创建的对象。


演示通过连接到
`Class.Instance.AncestryChanged` 事件来检测实例祖先的变化。

ChangingPart 的父级随着时间的推移而设置为不同的值。该零件的父级是该零件的祖先，因此
`Class.Instance.AncestryChanged` 事件将在每次变化时触发。

当此实例被重新归属或其任何祖先被重新归属时触发。

您可以使用此事件跟踪 Studio 中实例的删除，例如在资源管理器中手动删除或通过插件删除。如果您需要检测实例何时使用 `Class.Instance:Destroy()` 被销毁，请使用 `Class.Instance.Destroying` 事件。


Instance.AncestryChanged

child

其 `Class.Instance.Parent|Parent` 属性已更改的实例，可以是此实例或更远的祖先，**不**一定是处理程序连接的实例。


parent

当此对象或其祖先的 `Class.Instance.Parent` 属性更改时触发。


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

例如，以下代码片段连接 `attributeChanged()` 函数，以便每当部件的属性之一更改时触发：

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

local part = Workspace.Part

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

part.AttributeChanged:Connect(attributeChanged)
```
另请参见 `Class.Instance:GetAttributeChangedSignal()`，它返回一个在特定给定属性更改时触发的事件。


Instance.AttributeChanged

attribute

每当 `Class.Instance` 上的属性更改时触发。


此代码段打印添加到工作区的对象名称：

在对象被归属到此 `Class.Instance` 之后触发。

注意，当在客户端使用此方法检测由服务器创建的对象时，在索引这些对象的后代时必须使用 `Class.Instance:WaitForChild()`。这是因为对象及其后代不保证同时从服务器复制到客户端。例如：

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

Workspace.ChildAdded:Connect(function(child)
	-- 使用 WaitForChild() 因为后代可能尚未复制
	local head = child:WaitForChild("Head")
end)
```
注意，此事件仅适用于 `Class.Instance` 的直接子对象。要捕获所有后代的事件，请使用 `Class.Instance.DescendantAdded`。

另请参见 `Class.Instance.ChildRemoved`。


Instance.ChildAdded

在对象被归属到此 `Class.Instance` 之后触发。


Instance.childAdded

这个代码片段会在对象从工作区中移除时打印它们的名称：

在子对象从此 `Class.Instance` 中移除后触发。

移除是指对象的父级从此 `Class.Instance` 更改为其他非此 `Class.Instance` 的对象。注意，当子对象被销毁（使用 `Class.Instance:Destroy()`）时，此事件也会触发，因为销毁函数将对象的父级设置为 `nil`。

此事件仅适用于 `Class.Instance` 的直接子对象。要捕获所有后代的事件，请使用 `Class.Instance.DescendantRemoving`。

另请参见 `Class.Instance.ChildAdded`。


Instance.ChildRemoved

在子对象从此 `Class.Instance` 中移除后触发。


以下示例将打印添加到
工作区的任何对象的名称：

此事件在后代被添加到 `Class.Instance` 之后触发。

由于它对每个后代触发，将对象归属到 `Class.Instance` 将单独触发此对象及其所有后代的事件。

如果您只关心 `Class.Instance` 的 **直接子对象**，请使用 `Class.Instance.ChildAdded`。

另请参见 `Class.Instance.DescendantRemoving`。


Instance.DescendantAdded

descendant

在后代被添加到 `Class.Instance` 之后触发。


以下示例在一个后代被移除时打印其名称
从工作区:

此事件在父级 `Class.Instance` 更改之前立即触发，以至于 **后代** 实例将不再是后代。`Class.Instance:Destroy()|Destroy()` 将实例的 `Class.Instance.Parent|Parent` 更改为 `nil`，因此在父级的后代上调用该方法将导致此事件触发。

由于此事件在后代移除 **之前** 触发，因此在此事件触发时，后代的父级将保持不变。如果后代也是父级的 **直接子对象**，则此事件将在 `Class.Instance.ChildRemoved` 之前触发。

如果后代有子对象，此事件将首先与后代一起触发，然后是其后代。

#### 警告

此事件与正在被移除的后代对象一起触发。尝试将后代的 `Class.Instance.Parent|Parent` 设置为其他对象将失败。以下是一个演示此情况的示例：

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

Workspace.DescendantRemoving:Connect(function(descendant)
	-- 不要在此函数中操作后代的父级！
	-- 此事件触发是因为父级被操作，而更改尚未发生
	-- 因此，像这样更改父级是有问题的：
	descendant.Parent = game
end)

local part = Instance.new("Part")
part.Parent = Workspace
part.Parent = nil
```
另请参见 `Class.Instance.DescendantAdded|DescendantAdded`。


Instance.DescendantRemoving

在 `Class.Instance` 的后代被移除之前立即触发。


此示例演示了当使用即时信号行为时，
实例被销毁时仍保持在原位，直到连接的函数挂起。

此示例演示了如何在使用推迟信号行为时，在信号触发之前销毁实例。

当连接的函数仍在使用时，`Class.Instance` 将永远不会从内存中删除。然而，如果函数在任何时候挂起，`Class.Instance` 及其后代将被归属到 `nil`。

如果 `Class.Workspace.SignalBehavior` 属性设置为 `Enum.SignalBehavior.Immediate`，则此事件将在 `Class.Instance` 或其祖先通过 `Class.Instance:Destroy()` 被销毁之前立即触发。

如果 `Class.Workspace.SignalBehavior` 属性设置为 `Enum.SignalBehavior.Deferred`，则此事件将在下一个恢复点触发，即在 `Class.Instance` 或其祖先通过 `Class.Instance:Destroy()` 被销毁之后。

使用 `Enum.SignalBehavior.Deferred|Deferred` 行为，将脚本连接到其自己的 `Class.Instance.Destroying` 事件是有问题的，因为脚本将在回调被调用之前被销毁（这意味着它不会执行）。

在 Studio 中删除 `Class.Instance`，例如通过 [Explorer](/studio/explorer) 手动删除或通过插件删除时，`Class.Instance` 不会被销毁。相反，父级被设置为 `nil`，您可以通过 `Class.Instance.AncestryChanged` 跟踪。


Instance.Destroying

在实例通过 `Class.Instance:Destroy()` 被销毁之前立即触发（或延迟到之后）。


演示 `Class.Instance.StyledPropertiesChanged`。


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


Instance.StyledPropertiesChanged

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


此方法将标签应用于实例，如果标签已应用，则没有效果。
成功添加标签将触发由 `Class.CollectionService:GetInstanceAddedSignal()` 创建的信号，
并带有给定标签。

#### 警告

- 如果服务器稍后在该实例上添加或删除标签，
  客户端添加的实例标签将被丢弃，因为服务器
  一起复制所有标签并覆盖先前的标签。

- 在标记实例时，通常会使用一些资源来
  赋予标签其功能，例如事件连接或表。
  为了防止内存泄漏，最好在不再需要标签时清理这些资源（断开连接，
  设置为 `nil` 等）。在调用 `Class.Instance:RemoveTag()`、调用
  `Class.Instance:Destroy()` 或在连接到由
  `Class.CollectionService:GetInstanceRemovedSignal()` 返回的信号的函数中执行此操作。


Instance:AddTag

子级函数返回对象的子级数组。


Instance:children

此方法销毁实例的所有子级和后代。

```
local part = Instance.new("Part")

-- 添加一些闪光
for i = 1, 3 do
	local sparkles = Instance.new("Sparkles")
	sparkles.Parent = part

  local sc = Instance.new("Sparkles")
  sc.Parent = sparkles
end

print("Children:", #part:GetChildren())  --> Children: 3

part:ClearAllChildren()

print("Children:", #part:GetChildren())  --> Children: 0
```
如果您不希望销毁 **所有** 子级和后代，请使用 `Class.Instance:GetChildren()` 或 `Class.Instance:GetDescendants()` 循环遍历这些子级/后代并选择要销毁的对象。例如，以下代码示例将销毁所有
`Class.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()` 函数销毁一个 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` 的第一个祖先，
其 `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` 的 `Class.Folder` 名为 `Color`，
它也具有 `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()` 上使用 `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

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


下面代码将在运行时打印当前在工作区中的所有对象的名称。

返回一个数组（一个数字索引的表），包含实例的所有直接子级，
或每个 `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` 层次结构上的对象调用该函数时的行为，
还展示了返回值如何不转义特殊字符。

此代码示例在 Lua 中重新实现了 `Class.Instance:GetFullName()` 函数。


返回描述实例祖先的字符串。该字符串是 `Class.Instance.Name|Name` 的连接，
以及其祖先，用句点分隔。`Class.DataModel`（`game`）不被考虑。例如，位于 `Class.Workspace` 中的 `Class.Part` 可能返回 `Class.Workspace.Part`。

当在不是 `Class.DataModel` 的后代的 `Class.Instance` 上调用此方法时，
此方法考虑所有祖先，直到包括没有 `Class.Instance.Parent|Parent` 的最上层祖先。

此方法对于日志记录和调试很有用。您不应尝试解析返回的字符串以进行任何有用的操作；此方法不会转义对象名称中的句点（或任何其他符号）。换句话说，尽管其输出通常看起来像有效的 Luau 标识符，但并不保证。


Instance:GetFullName

此方法返回指定属性的样式或显式修改值，
如果未样式/修改，则返回默认属性值。这与直接访问属性值略有不同，
例如 `[GuiObject].Rotation`，它返回属性的默认值或修改值。


Instance:GetStyled

selector

您在实例上要定位的伪实例的可选选择器。


指定属性的样式或显式修改值，
如果未样式/修改，则返回默认属性值。


返回指定属性的样式或显式修改值，
如果未样式/修改，则返回默认属性值。


演示 `Class.Instance:GetStyledPropertyChangedSignal()`。


此方法返回一个事件，该事件的行为与
`Class.Instance.StyledPropertiesChanged|StyledPropertiesChanged` 事件完全相同，
只是在给定样式属性更改时触发。通常，使用此方法而不是连接到
`Class.Instance.StyledPropertiesChanged|StyledPropertiesChanged` 的函数来检查属性名称是个好主意。
对同一对象的后续调用将返回相同的事件。

请注意，此事件不会将任何参数传递给连接的函数，
因此必须在脚本中直接读取更改的属性值。


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` 是给定后代的祖先，则为 true。


如果 `Class.Instance` 是给定后代的祖先，则返回 true。


如果 `Class.Instance` 是给定祖先的后代，则返回 `true`。

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

另请参见 `Class.Instance:IsAncestorOf()`。


Instance:IsDescendantOf

ancestor

如果 `Class.Instance` 是给定祖先的后代，则为 true。


如果 `Class.Instance` 是给定祖先的后代，则返回 `true`。


Instance:isDescendantOf

此方法指示特定属性是否已从代码实例化的默认值进行修改。如果在通过代码新创建的实例上调用（`Datatype.Instance.new()`），此方法将返回 `false`。如果在通过 Studio 工作流（例如
[Explorer](/studio/explorer) 窗口插入）新创建的对象上调用，结果可能会有所不同。

例如，查询通过 [Explorer](/studio/explorer) 插入的 `Class.TextLabel.BackgroundColor3|BackgroundColor3` 属性将返回 `true`，但查询通过 `Datatype.Instance.new()` 创建的相同属性将返回 `false`，假设没有对其
`Class.TextLabel.BackgroundColor3|BackgroundColor3` 进行其他更改。

请注意，此方法仅对服务和用户可创建的实例返回有用的结果。对于实例的系统填充属性（如 `Class.PackageLink`），返回值是未定义的行为。

还请注意，如果此方法返回 `true`，样式将 **不** 影响该属性，因为显式修改属性优先于样式。要将属性重置为其代码实例化的默认值并允许对其进行样式设置，请使用
`Class.Instance:ResetPropertyToDefault()|ResetPropertyToDefault()`。


Instance:IsPropertyModified

布尔值，指示属性是否已从其代码实例化的默认值进行修改。


如果存储在指定属性中的值不等于代码实例化的默认值，则返回 `true`。


此对象方法返回一个数组，包含所有与提供的 `selector` 字符串匹配的对象的后代。`selector` 可以包括多个选择器和组合器，以匹配类名、实例名称和层次关系等特征，以及实例属性和属性的特定值。`selector`
语法与 `Class.StyleRule` 中使用的语法相似，仅在支持或不支持的语法部分方面存在少数差异。

#### 选择器

- `ClassName` — 匹配指定类的实例，
  在 `Class.Object:IsA()` 关系中。
- `.Tag` — 匹配带有 `Class.CollectionService` 标签的实例。
- `#Name` — 匹配特定 `Class.Instance.Name` 的实例。
- `[property = value]` — 匹配具有指定属性且该属性具有指定值的实例。支持布尔值、数字和字符串值。字母、数字、`_` 和 `-` 可以在不加引号的情况下使用。
- `[$attribute]` — 匹配具有指定
  [属性](/studio/properties#instance-attributes) 的实例。
- `[$attribute = value]` — 匹配具有指定属性 **且** 该属性具有指定值的实例。与属性选择器相同的限制适用。如果要检查属性的缺失，请不要将其查询为 `nil`；相反，使用 `:not` 伪类，例如 `:not([$attribute])`。

选择器也可以组合。例如，
`Model.Apple[$Variety = Fuji][$Flavor = 4]` 将匹配标记为 `Apple` 的 `Class.Model`，并且具有 `Variety` 属性等于 `Fuji` 以及 `Flavor` 属性等于 `4` 的实例。

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

-- 获取所有 MeshPart 后代
print(Workspace:QueryDescendants("MeshPart"))

-- 获取所有标记为 "Fruit" 的后代
print(Workspace:QueryDescendants(".Fruit"))

-- 获取所有名称为 "RedTree" 的后代
print(Workspace:QueryDescendants("#RedTree"))

-- 获取所有 CanCollide 属性设置为 false 的后代
print(Workspace:QueryDescendants("[CanCollide = false]"))

-- 获取所有分配了 "FuelCapacity" 属性的后代
print(Workspace:QueryDescendants("[$FuelCapacity]"))
-- 获取所有 "FuelCapacity" 属性设置为 75 的后代
print(Workspace:QueryDescendants("[$FuelCapacity = 75]"))
```

#### 组合器

组合器允许您混合基本选择器以匹配更深层次的层次关系。

- `>` — 匹配前一个过滤器匹配的 **直接子级**。

- `>>` — 匹配前一个过滤器匹配的 **后代**。这是默认的第一个过滤器，意味着 `SpotLight.Red`
  与 `>> SpotLight.Red` 是相同的。

- `,` — 指定多个独立选择器的列表以进行后代查询。仅匹配过滤器的元素被放置在返回的数组中；对于查询列表中的不匹配，`nil` 将不包括在内。

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

-- 获取标记为 "SwordPart" 的任何模型的直接子级
print(Workspace:QueryDescendants("Model > .SwordPart"))

-- 获取直接子级为部件且标记为 "Apple" 的子级
print(Workspace:QueryDescendants("> Part.Apple"))

-- 获取任何模型的后代，其属性 "OnFire" 设置为 true
print(Workspace:QueryDescendants("Model >> [$OnFire = true]"))

-- 获取标记为 "SwordPart" 的 MeshPart 后代或其属性 "OnFire" 设置为 true 的后代
print(Workspace:QueryDescendants("MeshPart.SwordPart, MeshPart[$OnFire = true]"))
```

#### 伪类选择器

- `:not(complex-selector-list)` — 允许选择 **不** 匹配内部任何选择器的实例，
  有效地执行选择器的否定。由于内部是复杂选择器的列表，因此可以根据多个条件进行过滤。

- `:has(relative-selector-list)` — 允许根据实例内部包含的实例选择实例。
选择器列表相对于每个实例进行评估。

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

-- 获取所有不是 SpotLight 类的后代
print(Workspace:QueryDescendants(":not(SpotLight)"))
-- 获取所有不是 SpotLight 或 PointLight 类的后代
print(Workspace:QueryDescendants(":not(SpotLight, PointLight)"))
-- 获取所有没有属性 "OnFire" 的后代
print(Workspace:QueryDescendants(":not([$OnFire])"))
-- 获取所有后代，除了标记为 "SwordPart" 的模型的子级
print(Workspace:QueryDescendants(":not(Model > .SwordPart)"))

-- 获取包含工具实例作为其后代的后代
print(Workspace:QueryDescendants(":has(Tool)"))
-- 获取标记为 "SwordPart" 的 MeshPart 后代
print(Workspace:QueryDescendants("MeshPart:has(> .SwordPart)"))

-- 获取 MeshPart 后代，直接子级不是 SurfaceAppearance 或 Texture 类
print(Workspace:QueryDescendants("MeshPart:has(> :not(SurfaceAppearance, Texture))"))
```


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 个字符。
- 名称不允许以 **RBX** 开头，除非调用者是
  Roblox 核心脚本（保留给 Roblox）。

当尝试将属性设置为不支持的类型时，将引发错误。

#### 另请参见

- `Class.Instance:GetAttribute()`，返回分配给给定属性名称的值。
- `Class.Instance:GetAttributes()`，返回每个实例属性的键值对字典。


Instance:SetAttribute

将具有给定名称的属性设置为给定值。


以下代码等待名为 "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()` 将返回 `nil`
如果该实例 **不是** `Class.Instance.Archivable|Archivable`。

在 Studio 中使用 **Duplicate** 或 **Copy**/**Paste** 选项复制对象
将忽略其自身的 `Class.Instance.Archivable|Archivable`
属性，并将 `Class.Instance.Archivable|Archivable` 设置为 `true`。


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` 的 **祖先** 是该实例的所有对象。

许多其他 API 成员的名称来自 `Parent` 属性，
例如 `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` 的层次父级。


Instance.PredictionMode

此属性曾用于保护 `Class.CoreGui` 服务中的对象，
以防止用户以未经授权的方式进行更改。它已被弃用，
并且不执行任何操作。


Instance.RobloxLocked

一个已弃用的属性，曾用于保护 `Class.CoreGui` 对象。


将实例转换为 **沙盒容器**，这是一项实验性
功能，限制特定容器内脚本可以执行的操作。有关更多详细信息，请参见
[脚本能力](/scripting/capabilities)。


Instance.Sandboxed

启用时，实例只能访问其 `Capabilities`
列表中的能力。


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


/reference/engine/classes/NumberValue.yaml