孔是一种未使用的表面接头类型。它可以通过使用 `Class.VelocityMotor` 连接到 `Class.MotorFeature` 对象。

Hole

Feature

设置对象相对于父对象的位置。

Feature.FaceId

控制特征在其父表面上的位置， 
相应于特征的 `Class.Feature.LeftRight` 和 
`Class.Feature.TopBottom` 属性。

Feature.InOut

控制特征在表面上向左、居中或向右的偏移。

Feature.LeftRight

控制特征在表面上向上、居中或向下的偏移。

Feature.TopBottom

`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` 的 `Class.Instance.Parent` 被更改的对象。

parent

该 `Class.Instance` 的新 `Class.Instance.Parent`。

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

此事件在实例的任何属性发生更改时触发，\n包括当属性被设置为 `nil` 时。更改的属性名称作为参数传递给连接的函数。\n\n例如，以下代码片段连接了 `attributeChanged()` 函数，当部件的属性发生变化时触发：\n\n```lua\nlocal Workspace = game:GetService(\"Workspace\")\n\nlocal part = Workspace.Part\n\nlocal function attributeChanged(attributeName)\n\tprint(attributeName, \"changed\")\nend\n\npart.AttributeChanged:Connect(attributeChanged)\n```\n\n另请参阅 `Class.Instance:GetAttributeChangedSignal()`，其返回一个在特定给定属性发生变化时触发的事件。

Instance.AttributeChanged

attribute

当 `Class.Instance` 上的任意属性被更改时触发。

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

在对象被父级附加到该 `Class.Instance` 后触发。\n\n注意，当使用此函数在客户端检测服务器创建的对象时，应用 `Class.Instance:WaitForChild()` 来索引这些对象的后代是必要的。这是因为对象及其后代不保证同时从服务器复制到客户端。例如：\n\n```\nlocal Workspace = game:GetService(\"Workspace\")\n\nWorkspace.ChildAdded:Connect(function(child)\n\t-- 使用 WaitForChild() 由于后代可能尚未复制\n\tlocal head = child:WaitForChild(\"Head\")\nend)\n```\n\n注意，此函数仅适用于该 `Class.Instance` 的直接子对象。要获取所有后代的函数，请使用 `Class.Instance.DescendantAdded`。\n\n另请参阅 `Class.Instance.ChildRemoved`。

Instance.ChildAdded

在对象被父级附加到该 `Class.Instance` 后触发。

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

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

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

此函数仅适用于该 `Class.Instance` 的直接子对象。要获取所有后代的函数，请使用 `Class.Instance.DescendantRemoving`。

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

Instance.ChildRemoved

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

下面的示例将打印任何添加到 Workspace 的对象的名称：

此事件在后代被添加到 `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`，因此一旦调用该方法在父级的后代上，也会触发此事件。\n\n由于此事件在后代移除 **之前** 触发，因此在此事件触发时，后代的父级将保持不变。如果后代也是父级的 **直接子对象**，则此事件将在 `Class.Instance.ChildRemoved` 之前触发。\n\n如果后代有子级，此事件将首先触发后代，然后是它的后代。\n\n##### 警告\n\n此事件会为正在移除的后代对象触发。\n尝试将后代的 `Class.Instance.Parent|Parent` 设置为其他内容将失败。以下示例演示了这一点：\n\n```\nlocal Workspace = game:GetService(\"Workspace\")\n\nWorkspace.DescendantRemoving:Connect(function(descendant)\n\t-- 请勿在此函数中操作后代的父级！\n\t-- 此事件在父级被操作时触发，并且更改尚未发生\n\t-- 因此，像这样更改父级是有问题的：\n\tdescendant.Parent = game\nend)\n\nlocal part = Instance.new(\"Part\")\npart.Parent = Workspace\npart.Parent = nil\n```\n\n另请参阅 `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`。\n\n```lua\nlocal Players = game:GetService(\"Players\")\n\nlocal player = Players.LocalPlayer\nlocal playerGui = player.PlayerGui\nlocal HUDContainer = playerGui:WaitForChild(\"HUDContainer\")\nlocal meterBar = HUDContainer.MeterBar\n\nlocal function stylePropertyChanged()\n\tprint(\"样式属性已更改\")\nend\n\nmeterBar:StyledPropertiesChanged():Connect(stylePropertyChanged)\n```     

Instance.StyledPropertiesChanged

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

Instance.childAdded

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

##### 警告

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

- 标记实例时，通常会使用一些资源来提供标签的功能，例如事件连接或表。当不再需要标签时，清理这些资源（断开连接，设置为 `nil` 等）是个好主意。在调用 `Class.Instance:RemoveTag()`、调用 `Class.Instance:Destroy()` 或在连接到 `Class.CollectionService:GetInstanceRemovedSignal()` 返回的信号的函数中执行此操作。

Instance:AddTag

此函数销毁实例的所有子对象和后代。

```
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` 的实例。

演示如何使用 `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()`。

返回 `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()` 对给定的 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` 的属性相同。当使用点运算符时，属性优先于子对象，如果它们共享名称。

例如，在以下示例中，添加一个名为 `Color` 的 `Class.Folder` 到 `Class.Part`，同时 `Class.Part` 也有 `Class.Part.Color` 属性。注意，`part.Color` 是指 `Datatype.Color3` 属性值，而不是子对象实例的指针。使用 `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` 的第一个子对象，找到的名称与给定名称匹配。

返回 `Class.Instance` 的第一个子对象，其 `Class.Object.ClassName|ClassName` 等于给定的 `className`。与 `Class.Instance:FindFirstChildWhichIsA()` 不同，此函数仅返回类与 `className` 匹配的对象，忽略类继承。如果未找到匹配的子对象，则此函数返回 `nil`。

Instance:FindFirstChildOfClass

返回 `Class.Instance` 的第一个子对象，其 `Class.Object.ClassName|ClassName` 等于给定 class name。

返回 `Class.Instance` 的第一个子对象，其中 `Class.Object:IsA()` 对给定的 className 返回 true。

如果未找到匹配的子对象，则此函数返回 `nil`。如果可选的递归参数为 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("属性已更改")
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\")

-- 数字 for 循环示例
local children = Workspace:GetChildren()
for i = 1, #children do
    local child = children[i]
    print(child.Name .. " 是第 " .. i .. " 个子对象")
end
```

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

-- 通用 for 循环示例
local children = Workspace:GetChildren()
for i, child in children do
    print(child.Name .. " 是第 " .. i .. " 个子对象")
end
```

子对象按其 `Class.Instance.Parent|Parent` 属性设置到对象的顺序排序。

另见 `Class.Instance:GetDescendants()|GetDescendants` 函数。

Instance:GetChildren

返回包含该实例所有子对象的数组。

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

- 该项是受保护的。尝试在 `Class.Script` 或 `Class.LocalScript` 中使用它将导致错误。
- 调试 ID 用于调试过程中。它允许调试器在应用程序处理之前读取每条指令。Roblox 中的所有对象都充当进程，每个运行指令（或“代码”）可以在需要时进行调试。
- 这对于需要区分彼此相似对象的插件非常有帮助（例如共享相同名称的对象）。

Instance:GetDebugId

scopeLength

返回 Roblox 内部使用的调试 ID 的编码字符串。

GetDescendants 通常用于对特定类型的对象的所有后代执行某些操作。此示例中的代码使用 GetDescendants 和
`Class.Instance:IsA()` 来查找工作区中的所有部件并将它们变为绿色。

此对象方法返回一个数组，其中包含该对象的所有后代。与仅返回对象直接子对象的 `Class.Instance:GetChildren()` 不同，此方法查找对象的每个子对象及其每个子对象的子对象，等等。

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.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 的 [Properties](/studio/properties) 窗口中或在运行时使用 `Class.Instance:AddTag()|AddTag()` 添加标签。

当您希望一次性处理实例上的多个标签时，此方法非常有用。然而，使用此方法检查单个标签的存在性效率不高；相反，请使用 `Class.Instance:HasTag()|HasTag()` 检查特定标签。

Instance:GetTags

获取应用于实例的所有标签的数组。

此方法如果提供的标签已被添加到对象，则返回 `true`。您可以在 Studio 的 [Properties](/studio/properties) 窗口中或在运行时使用 `Class.Instance:AddTag()|AddTag()` 添加标签。

Instance:HasTag

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

Workspace 和 SpawnLocation 是 SpawnLocation 的贴花的祖先。
Workspace 是 SpawnLocation 的祖先。

SpawnLocation 和它的贴花是 Workspace 的后代，而不是祖先。
贴花是 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。

如果存储在指定属性中的值等于代码实例化的默认值，则返回 true。例如，如果输出 `Class.TextLabel.TextSize|TextSize` 属性显示 `8`，则在标签上调用 `IsPropertyModified("TextSize")` 将返回 `false`，因为 `8` 是 `Class.TextLabel.TextSize` 的默认值，当标签通过 `Instance.new("TextLabel")` 创建，而不是通过 Studio 插入工作流程插入时。

请注意，如果此方法返回 `true`，则样式将**不**影响该属性，因为显式修改属性优先于样式。

Instance:IsPropertyModified

指示属性是否被修改的布尔值。

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

以下代码演示了一个零件如何在被移除后重新添加到数据模型中：

此函数将对象的 `Class.Instance.Parent` 设置为 `nil`，并对其所有后代执行相同操作。

如果在移除之前引用了该对象，则可以在稍后检索该对象。

Instance:Remove

将对象的 `Parent` 设置为 `nil`，并对其所有后代执行相同操作。

此方法从实例中移除标签。如果对象没有该标签，则不会引发错误。成功移除标签将触发由 `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

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` 的子对象。如果该子对象不存在，将使当前线程等待直到它存在。

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

Instance:children

Instance:clone

Instance:destroy

Instance:findFirstChild

Instance:getChildren

Instance:isDescendantOf

Instance:remove

Instance

此属性确定实例在体验发布或保存时，或者在其某个祖先上调用 `Class.Instance:Clone()|Clone()` 时是否应包含。直接在一个实例上调用 `Class.Instance:Clone()|Clone()` 如果该实例 **不** 是 `Class.Instance.Archivable|Archivable` ，将返回 `nil`。

在 Studio 中使用 **Duplicate** 或 **Copy**/**Paste** 选项复制一个对象将忽略其自身 `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()` 被克隆，并且可以被保存/发布。

允许在此实例内用于脚本的一组功能。为了使功能生效，必须启用 `Class.Instance.Sandboxed` 属性。

此属性由实验性功能使用。有关更多细节，请参阅 [script capabilities](/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` 对象。

将实例转换为一个**沙盒容器**，这是一个实验性功能，它限制该特定容器内的脚本能执行的操作。有关更多细节，请参阅 [script capabilities](/scripting/capabilities).

Instance.Sandboxed

实例的唯一标识符，与 `Class.Instance.Name` 不同，后者不一定是唯一的。

Instance.UniqueId

Instance.archivable

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

Object 是 Roblox 类层次结构中所有类的基础类。每个
Roblox 引擎定义的其他类都继承了 Object 的所有成员。
不能直接创建 Object。

此示例演示了普通对象和 "-Value" 对象上变更事件的细微差别。

此代码示例演示了父对象中 Changed 事件的触发。

此事件在对象属性更改后立刻触发，适用于大多数使用情况（见下文的限制）。
更改属性的新值**不会**作为参数传递，因此必须使用
`object[property]` 访问。例如：

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

如果您只希望监听某个特定属性的变化，考虑使用
`Class.Object:GetPropertyChangedSignal()|GetPropertyChangedSignal()` 方法。

对于 `Class.ValueBase` 对象，例如 `Class.IntValue` 和
`Class.StringValue`，此事件仅在对象的 `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`。

此外，此事件可能不会在属性频繁更改的每次修改上触发，且/或可能根本不会对这样的属性触发。
建议您仔细测试影响游戏逻辑的属性变化。

Object.Changed

在对象的一个属性变化后立即触发，但有一些限制。

这段代码示例演示了如何在变更事件触发之前保存一个值，以便获得更多关于更改的信息。

此方法返回一个事件，该事件的行为与
`Class.Object.Changed|Changed` 事件完全相同，只是它
仅在给定属性变化时触发。通常建议使用此方法，
而不是将函数连接到 `Class.Object.Changed|Changed` 并检查
属性名称。对同一对象同一属性名称的后续调用
将返回相同的事件。

`Class.ValueBase` 对象，例如 `Class.IntValue` 和
`Class.StringValue`，使用修改过的 `Class.Object.Changed|Changed` 事件，
该事件随其 `Value` 属性的内容触发。因此，此方法提供了一种
检测这些对象其他属性变化的方法。

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

#### 限制

此方法返回的事件**不会**因物理相关更改而触发，例如：
当 `Class.BasePart.CFrame|CFrame`、`Class.BasePart.AssemblyLinearVelocity|AssemblyLinearVelocity`、`Class.BasePart.AssemblyAngularVelocity|AssemblyAngularVelocity`、`Class.BasePart.Position|Position` 或
`Class.BasePart.Orientation|Orientation` 属性因重力而改变时。要检测这些属性的变化，请考虑使用基于物理的事件，例如 `Class.RunService.PreSimulation`。

此外，返回的事件可能不会因频繁变化的属性的每次修改而触发，或者根本不触发。建议您仔细测试影响游戏逻辑的属性变化。

Object:GetPropertyChangedSignal

获取在给定属性变化时触发的事件。

Object

Object 是 Roblox 类层次结构中所有类的基础类。

Hole

概要

属性

属性

方法

活动

属性

方法

活动

在此页面