现代控制器和设备内置了马达以提供触觉反馈。添加震动和振动可以提供微妙的反馈，这在视觉或音频上很难表达。

Roblox 支持以下设备的触觉反馈：

- 包括大多数 iPhone、Pixel 和三星 Galaxy 设备在内的支持触觉反馈的 Android 和 iOS 手机
- PlayStation 手柄
- Xbox 手柄
- Quest Touch 控制器

当 `Class.HapticEffect` 播放完成并停止时触发。
请注意，对于设置为 `true` 的 `Class.HapticEffect.Looped|Looped` 的振动，此事件将**不会**触发，因为它们在到达结束时会继续播放。此事件也**不会**在振动在播放完成之前被停止时触发。

此事件通常用于在 `Class.HapticEffect` 播放完成后销毁它。


HapticEffect.Ended

当 `Class.HapticEffect` 完成播放并停止时触发。

播放触觉效果。

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

local effect = Instance.new("HapticEffect")
effect.Type = Enum.HapticEffectType.GameplayExplosion
effect.Parent = Workspace

-- 播放触觉效果
effect:Play()
```

HapticEffect:Play

此方法允许您将自定义波形定义为表并将其应用于触觉。

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

local effect = Instance.new("HapticEffect")

-- 将效果类型设置为自定义以定义波形
effect.Type = Enum.HapticEffectType.Custom
effect.Parent = Workspace

-- 通过表定义自定义波形曲线
local rampUpWaveform = {
	FloatCurveKey.new(0, 0.3),
	FloatCurveKey.new(100, 0.4),
	FloatCurveKey.new(300, 0.8),
	FloatCurveKey.new(400, 1.0)
}

-- 通过效果的方法设置波形
effect:SetWaveformKeys(rampUpWaveform)
```

HapticEffect:SetWaveformKeys

keys

用于定义自定义波形的表并将其应用于触觉的 methods。

停止触觉效果。

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

local effect = Instance.new("HapticEffect")
effect.Type = Enum.HapticEffectType.GameplayExplosion
effect.Looped = true
effect.Parent = Workspace

-- 启动触觉效果
effect:Play()
-- 两秒后停止效果
task.wait(2)
effect:Stop()
```

HapticEffect:Stop

HapticEffect

触觉效果是否循环播放。

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

local effect = Instance.new("HapticEffect")
effect.Type = Enum.HapticEffectType.GameplayExplosion
effect.Looped = true
effect.Parent = Workspace

-- 启动触觉效果
effect:Play()
-- 两秒后停止效果
task.wait(2)
effect:Stop()
```

HapticEffect.Looped

与 `Class.HapticEffect.Radius|Radius` 一起，指定相对于输入设备的冲击位置，以及该冲击对附近电机影响的广度。请注意，某些手柄可能没有 "小" 和 "大" 马达，且 "游戏手柄大左/右" 在 PC 上不受支持。

<img src="/assets/engine-api/classes/HapticEffect/Position-Radius.png" width="780" />

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

local effect = Instance.new("HapticEffect")

-- 设置冲击的位置和半径
effect.Position = Vector3.new(0.5, 0.5, 0)
effect.Radius = 1
effect.Parent = Workspace

effect:Play()
```

HapticEffect.Position

与 `Class.HapticEffect.Radius|Radius` 一起，指定相对于输入设备的冲击位置，以及该冲击对附近电机影响的广度。

与 `Class.HapticEffect.Position|Position` 一起，指定相对于输入设备的冲击半径，以及该冲击对附近电机影响的广度。请注意，某些手柄可能没有 "小" 和 "大" 马达，且 "游戏手柄大左/右" 在 PC 上不受支持。

<img src="/assets/engine-api/classes/HapticEffect/Position-Radius.png" width="780" />

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

local effect = Instance.new("HapticEffect")

-- 设置冲击的位置和半径
effect.Position = Vector3.new(0.5, 0.5, 0)
effect.Radius = 1
effect.Parent = Workspace

-- 播放触觉效果
effect:Play()
```

HapticEffect.Radius

与 `Class.HapticEffect.Position|Position` 一起，指定相对于输入设备的冲击半径，以及该冲击对附近电机影响的广度。

触觉类型，例如 `Enum.HapticEffectType.GameplayCollision` 表示一种快速消失的大型立即震动。
`Enum.HapticEffectType.Custom` 值允许您通过 `Class.HapticEffect:SetWaveformKeys()|SetWaveformKeys()` 指定具有自定义波形键的触觉。

HapticEffect.Type

`Enum.HapticEffectType` 描述触觉类型。

HapticEffect.Waveform

`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 中实例的删除，例如在资源管理器中手动删除或通过插件删除。如果您需要检测实例通过 `Class.Instance:Destroy()` 被销毁的情况，请使用 `Class.Instance.Destroying` 事件。


Instance.AncestryChanged

child

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


parent

其 `Class.Instance.Parent` 被更改的新 `Class.Instance.Parent`。


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


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

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

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

local part = Workspace.Part

local function attributeChanged(attributeName)
	print(attributeName, "已更改")
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` 后触发。


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

在子级从此 `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`，因此对父实例的子实例调用该方法将导致此事件触发。

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

如果子实例有子项，则此事件首先对子实例触发，然后对其子实例触发。

##### 警告

此事件发生在正在移除的子实例对象上。尝试将子实例的`Class.Instance.Parent|Parent`设置为其他内容将会失败。下面是一个演示此点的示例：

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

Workspace.DescendantRemoving:Connect(function(descendant)
	-- 不要在此函数中操作子实例的父实例！
	-- 此事件因父实例被操作而触发，且更改尚未发生
	-- 因此，以这种方式更改父实例是有问题的：
	descendant.Parent = game
end)

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


Instance.DescendantRemoving

在`Class.Instance`的一个子实例被移除之前立即触发。


此示例演示了在使用即时信号行为时，正在销毁的实例会保持原位，直到连接的函数暂停。

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

在连接的函数仍在使用时，`Class.Instance`将不会从内存中删除。然而，如果函数在任何时刻暂停，`Class.Instance`及其子项将被设置父类为`nil`。

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

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

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

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


Instance.Destroying

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


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

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

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

local function stylePropertyChanged()
	print("样式属性已更改")
end

meterBar:StyledPropertiesChanged():Connect(stylePropertyChanged)
```


Instance.StyledPropertiesChanged

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


Instance.childAdded

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

##### 警告

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

- 在标记实例时，通常会使用一些资源来赋予标签功能，例如事件连接或 tables。
为了防止内存泄漏，当标签不再需要时，最好清理这些资源（断开连接、设置为 `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.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` 的第一个子级，找到给定名称的子级。


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


Instance:FindFirstChildOfClass

返回 `Class.Instance` 的第一个子级，其 `Class.Object.ClassName|ClassName` 等于给定类名。


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

如果未找到匹配的子级，此函数返回 `nil`。如果可选的递归参数为 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.Object.ClassName`。


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


返回具有给定 `Class.Instance.Name` 的第一个后代。

此方法已禁用，无法使用。要查找实例的第一个后代，请考虑使用 `Class.Instance:FindFirstChild()` 上的 `recursive` 参数。


Instance:FindFirstDescendant

返回具有给定 `Class.Instance.Name` 的第一个后代。


如果 `Class.Instance` 是 `Class.Actor`，则返回 `Class.Actor` 本身。否则，返回其最近的祖先 `Class.Actor`。如果没有祖先是 `Class.Actor`，结果为 `nil`。


Instance:GetActor

返回与实例相关的 `Class.Actor`（如果有）。


此方法返回已分配给给定属性名称的值。如果没有分配任何属性，则返回 `nil`。

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

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

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

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

##### 另请参见

- `Class.Instance:SetAttribute()` 将具有给定名称的属性设置为给定值。
- `Class.Instance:GetAttributes()` 返回实例的每个属性的键值对字典。


Instance:GetAttribute

已分配给给定属性名称的值。如果没有分配任何属性，则返回 `nil`。


返回已分配给给定属性名称的值。


此函数返回一个事件，该事件的行为完全类似于 `Class.Object.Changed|Changed` 事件，
但是它仅在特定给定属性更改时触发；
有效地它类似于 `Class.Object:GetPropertyChangedSignal()|GetPropertyChangedSignal()`，但用于属性。

通常最好使用此方法，而不是连接到 `Class.Object.Changed|Changed` 并使用检查属性名称的函数。
对同一对象后续调用此方法并使用相同属性名称返回相同事件。

以下代码示例返回一个信号，当该部分的 `InitialPosition` 属性发生变化时调用函数 `attributeChanged()`：

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

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

local function attributeChanged()
	print("属性已更改")
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")

-- 数字 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 是在调试过程中使用的 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` 上调用此函数时，
此函数考虑所有祖先直到包括最上面的没有 `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 中的 [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` 属性的 `Class.TextLabel` 表示 `8`，
那么在标签上调用 `IsPropertyModified("TextSize")` 将返回 `false`，因为 `8` 是当通过 `Instance.new("TextLabel")` 创建标签时的 `Class.TextLabel.TextSize` 的默认值，而不是通过 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` 的子级。如果子级不存在，它将使当前线程暂停，直到它存在。


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


Instance:children

Instance:clone

Instance:destroy

Instance:findFirstChild

Instance:getChildren

Instance:isDescendantOf

Instance:remove

Instance

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

使用 **Duplicate** 或 **Copy**/**Paste** 选项在 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()` 进行克隆，并且可以被保存/发布。


实例内允许用于脚本的能力集。要使这些能力生效，必须启用 `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` 属性。
这确保对象仅复制一次，而不是复制许多属性更改。

```
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` 是 Roblox 类层次结构中所有类的基础类，可以是 `Class.DataModel` 树的一部分。


/reference/engine/classes/HapticEffect.yaml

HapticEffect

概要

属性

方法

活动

属性

方法

活动

在此页面