此代码示例包含了一个简单的例子，展示了如何在 `LocalScript` 中使用 `Class.Player:GetMouse()` 函数获取本地玩家的 `PlayerMouse`。此代码应放置在 `StarterPlayerScripts` 中的 `LocalScript` 中。


PlayerMouse 的行为与通过 `Class.Tool.Equipped` 获得的 `Class.Mouse` 对象完全相同。可以通过 `Class.LocalScript|LocalScripts` 中的本地玩家的 `Class.Player:GetMouse()` 方法来访问它。PlayerMouse 和 `Class.Mouse` 都是遗留 API，已被 `Class.UserInputService` 取代。

PlayerMouse 和 `Class.Mouse` 对象之间唯一的区别是 PlayerMouse 可以通过 `Class.Player:GetMouse()` 方法获得。

在大多数情况下，建议开发者使用新的 `Class.UserInputService`。然而，出于多种原因，PlayerMouse 和 Mouse 对象仍然受到支持。有关在您的体验中自定义输入的更多信息，请参见 [Input and Camera](/input)。


PlayerMouse

PlayerMouse 的行为与通过 `Class.Tool.Equipped` 获得的 `Class.Mouse` 对象完全相同。PlayerMouse 和 `Class.Mouse` 都是遗留 API，已被 `Class.UserInputService` 取代。


**Mouse** 已被 `Class.UserInputService` 和 `Class.ContextActionService` 取代，这两个类覆盖了更广泛的范围，更具功能性，并且更好地支持 **跨平台** 模式。它仍然被支持，因为它被广泛使用，但您应该强烈考虑使用这些替代方案。

**Mouse** 对象提供了各种指针的 API，主要用于按钮和射线检测。可以通过在 `Class.Players.LocalPlayer` 的 `Class.LocalScript` 中调用 `Class.Player:GetMouse()` 来访问它。它也会通过 `Class.Tool.Equipped` 事件传递。

- 它最显著的特性是 `Class.Mouse.Icon|Icon` 属性，可以更改光标的外观。
- 它不断将屏幕鼠标位置的射线投射到 3D 世界中，使用 `Class.Mouse.TargetFilter|TargetFilter` 属性，将射线检测结果存储在 `Class.Mouse.Hit|Hit`、`Class.Mouse.Target|Target` 和 `Class.Mouse.TargetSurface|TargetSurface` 属性中。这些对于简单情况可能有用，但在更复杂的 [射线检测](/workspace/raycasting) 场景中应使用 `Class.WorldRoot:Raycast()`。
- `Class.Plugin|Plugins` 可以使用 `Class.Plugin:GetMouse()` 获取一个 `Class.PluginMouse`，其行为类似。

```lua
-- 来自 LocalScript：
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local mouse = player:GetMouse()
-- 设置鼠标图标
mouse.Icon = "rbxasset://SystemCursors/Wait"
```
注意：

- 该对象不控制/限制指针移动。有关此内容，请参见 `Class.UserInputService.MouseBehavior` 和 `Class.UserInputService.MouseDeltaSensitivity`。
- 如果两个函数连接到同一输入事件，例如 `Class.Mouse.Button1Down|Button1Down`，**两个** 函数将在事件触发时运行。没有传递/传递输入的概念，因为事件不支持此行为。然而，`Class.ContextActionService` 通过 `Class.ContextActionService:BindAction()|BindAction` 确实具有此行为。
- 虽然并非所有平台都有鼠标，但 Mouse 仍然会在移动设备（触摸）和控制台（游戏手柄）上正常工作，这些设备通常没有鼠标或指针硬件。要实现明确的跨平台行为，请使用 `Class.UserInputService` 和 `Class.ContextActionService`。

有关自定义您体验中的输入的更多信息，请参见 [输入和相机](/input)。

当玩家按下左键时触发此事件。请注意，可以从 `Class.Tool` 访问此事件；例如，当放置在 `Class.LocalScript` 中时，以下代码会在每次按下左键时打印 `Button1Down`。

```lua
local tool = script.Parent  -- 确保这是一个 Tool 对象

tool.Equipped:Connect(function(mouse)
	mouse.Button1Down:Connect(function()
		print("Button1Down")
	end)
end)
```
您可以使用 `Class.Mouse.Hit|Hit` 和 `Class.Mouse.Target|Target` 属性来查找鼠标在世界空间中的位置以及它是否指向任何 `Class.BasePart`。

Mouse.Button1Down

当玩家释放左键时触发此事件。请注意，可以从 `Class.Tool` 访问此事件；例如，当放置在 `Class.LocalScript` 时，以下代码会在每次释放左键时打印 `Button1Up`。

```lua
local tool = script.Parent  -- 确保这是一个 Tool 对象

tool.Equipped:Connect(function(mouse)
	mouse.Button1Up:Connect(function()
		print("Button1Up")
	end)
end)
```
您可以使用 `Class.Mouse.Hit|Hit` 和 `Class.Mouse.Target|Target` 属性来查找鼠标在世界空间中的位置以及它是否指向任何 `Class.BasePart`。

Mouse.Button1Up

当玩家按下右键时触发此事件。请注意，可以从 `Class.Tool` 访问此事件；例如，当放置在 `Class.LocalScript` 中时，以下代码会在每次按下右键时打印 `Button2Down`。

```lua
local tool = script.Parent  -- 确保这是一个 Tool 对象

tool.Equipped:Connect(function(mouse)
	mouse.Button2Down:Connect(function()
		print("Button2Down")
	end)
end)
```
您可以使用 `Class.Mouse.Hit|Hit` 和 `Class.Mouse.Target|Target` 属性来查找鼠标在世界空间中的位置以及它是否指向任何 `Class.BasePart`。

Mouse.Button2Down

当玩家释放右键时触发此事件。请注意，可以从 `Class.Tool` 访问此事件；例如，当放置在 `Class.LocalScript` 中时，以下代码会在每次释放右键时打印 `Button2Up`。

```lua
local tool = script.Parent  -- 确保这是一个 Tool 对象

tool.Equipped:Connect(function(mouse)
	mouse.Button2Up:Connect(function()
		print("Button2Up")
	end)
end)
```
您可以使用 `Class.Mouse.Hit|Hit` 和 `Class.Mouse.Target|Target` 属性来查找鼠标在世界空间中的位置以及它是否指向任何 `Class.BasePart`。

Mouse.Button2Up

此示例演示了鼠标事件如何在每一帧中传递


当鼠标未被传递到另一个鼠标事件时，在每个心跳期间触发。

注意，此事件不应用于确定鼠标何时静止。由于它在每个心跳中触发，它将在 `Class.Mouse.Move` 事件之间触发。

有关如何获取 `Class.Mouse` 对象的信息，请参见 `Class.Mouse` 页面。

开发者可以使用 `Class.Mouse.Hit` 和 `Class.Mouse.Target` 属性查找鼠标在世界空间中的位置，看看它是否指向任何 `Class.BasePart`。

注意，开发者建议在新工作中使用 `Class.UserInputService`，而不是 `Class.Mouse` 对象。

Mouse.Idle

当鼠标未被传递到另一个鼠标事件时，在每个心跳期间触发。

下面的示例假设 'mouse' 已被定义，将打印被按下的键（例如 "q"）以及该键的 ASCII 值（例如 113）。


当按下某个键时触发此事件，传递的参数是被按下的键。

注意：

- 并非所有键都会产生此事件。然而，您可以使用一些键（例如"/"），通过使用 `Class.Mouse.KeyUp` 事件来解决此问题。
- 某些键会产生与其他键相同的字符串。
- 字符串可能为空（可能是由于"\\0"键代码）。

Mouse.KeyDown

Mouse.keyDown

下面的示例假设 'mouse' 已被定义，将打印释放的键（例如 "q"）以及该键的 ASCII 值（例如 113）。


当键被释放时将触发此事件，传递的参数为被释放的键。

注意：

- 并不是所有键都生成此事件。然而，您可以通过少数几个键来绕过此限制，例如使用 `[[API:Class/Mouse/KeyUp|KeyUp]]` 事件的"/"。
- 一些键生成与其他键相同的字符串。
- 字符串可能为空（可能由于 "\\0" 键代码）。

Mouse.KeyUp

下面的示例允许 `Class.Players.LocalPlayer|本地玩家` 用他们的鼠标移动
部件。

当玩家在一个部件上按下左鼠标按钮时，该部件就是
`Class.Mouse.Target|鼠标的目标`，并成为 _点_。在玩家
释放左鼠标按钮之前，该部件将移动到鼠标的世界
位置，当玩家移动鼠标时。

请注意，`Class.Mouse.TargetFilter` 属性允许代码在确定鼠标的世界位置时忽略
被移动的部件。

将代码放置在 `LocalScript` 中时，应该按预期工作。


当鼠标移动时触发此事件。

注意，此事件在鼠标位置更新时触发，因此在移动时会重复触发。

有关如何获取 `Class.Mouse` 对象的信息，请参见 `Class.Mouse` 页面。

开发人员可以找到鼠标在世界空间中的位置，如果它指向任何 `Class.BasePart`，可以使用 `Class.Mouse.Hit` 和 `Class.Mouse.Target` 属性。

```
mouse.Move:Connect(function()
	local position = mouse.Hit.p
	local target = mouse.Target
	print(target, position)
end)
```
注意，建议开发人员在新工作中使用 `Class.UserInputService` 而不是 `Class.Mouse` 对象。

Mouse.Move

下面的示例假设您已经获取了玩家的鼠标（并将其设置为名为 'mouse' 的变量），无论是通过使用 `Class.Tool`、`Class.HopperBin` 还是 `Class.Player:GetMouse()` 方法。当玩家向后滚动时，它将打印 "轮子向后转动！"。

当鼠标滚轮向后滚动时触发 WheelBackward 事件。此事件的可能用法包括在第一人称射击 (FPS) 游戏中切换枪的瞄准镜或缩放玩家的相机。

这可以与向前滚动事件 `Class.Mouse.WheelForward` 一起使用。

有关如何获取 `Class.Mouse` 对象的信息，请参见 `Class.Mouse` 页面。

注意，建议开发人员在新工作中使用 `Class.UserInputService` 而不是 `Class.Mouse` 对象。

Mouse.WheelBackward

下面的示例假设您已经获取了玩家的鼠标（并将其设置为名为 'mouse' 的变量），无论是通过使用 `Tool`、`HopperBin` 还是 `Class.Player:GetMouse()` 方法。当玩家向前滚动时，它将打印 "轮子向前转动！"

当鼠标滚轮向前滚动时触发 WheelForward 事件。此事件的可能用法包括在第一人称射击 (FPS) 游戏中切换枪的瞄准镜或缩放玩家的相机。

这可以与向后滚动事件 `Class.Mouse.WheelBackward` 一起使用。

有关如何获取 `Class.Mouse` 对象的信息，请参见 `Class.Mouse` 页面。

注意，建议开发人员在新工作中使用 `Class.UserInputService` 而不是 `Class.Mouse` 对象。

Mouse.WheelForward

Mouse

此示例中的代码，当放置在 `LocalScript` 中的 `StarterPlayerScripts` 内时，将在角色的头部与 `Class.Mouse.Hit` 之间绘制一条红色激光束。

请注意，这条激光束在第三人称视角下会直接穿过障碍物，因为 `Mouse` 的射线投射是从 `Class.Workspace.CurrentCamera` 而不是头部进行的。


下面的代码可视化了 `Class.Mouse.Hit` 和 `Class.Mouse.Origin` 之间的区别。
为了做到这一点，代码使用了击中和原点的 `Datatype.Vector3` 位置 `Datatype.CFrame` 值
使用 `.p`。

区别在于，原点是"鼠标来自哪里"（它的原点），而击中是鼠标击中的位置（即玩家按下鼠标时的位置）。

这个示例还可视化了鼠标原点与 `CurrentCamera` 的位置非常相似，通过打印这两个位置之间的大小（距离）。


该属性指示鼠标在 3D 空间中的位置的 `Datatype.CFrame`。请注意，`Class.Mouse.TargetFilter` 及其后代将被忽略。

开发者可以这样获取 Hit 的位置：

```
local position = mouse.Hit.Position
```
Hit 通常用于 `Class.Tool|Tools` 向鼠标发射武器，以便在第三人称视角中使用。

开发者要寻找鼠标所指向的 `Class.BasePart` 应使用 `Class.Mouse.Target`。

#### Mouse.Hit 是如何计算的？

Hit CFrame 的位置是通过鼠标内部的 `Datatype.Ray`（是 `Class.Mouse.UnitRay` 的扩展版本）与 3D 空间中的对象（例如零件）的交点计算得出的。

Hit CFrame 的朝向与 `Class.Mouse.UnitRay` 的方向对应。

```
local unitRayDirection = mouse.UnitRay.Direction
local mouseHitDirection = mouse.Hit.lookVector
-- unitRayDirection ≈ mouseHitDirection
-- 这两个向量大致相等
```
注意，当计算 Hit `Datatype.CFrame` 的朝向时，不会使用 `Class.Workspace.CurrentCamera` 的滚动值。

鼠标内部的射线延伸 1,000 个 studs。如果鼠标没有指向 3D 空间中的对象（例如，当它指向天空时），该属性将为 1,000 个 studs，距离 `Class.Workspace.CurrentCamera`。

Mouse.Hit

鼠标在 3D 空间中的位置的 `Datatype.CFrame`。

Mouse.hit

此示例将 `Class.Players.LocalPlayer` 的鼠标图标更改为龙的图像。


**图标** 是一个决定作为指针使用的图像的属性。如果为空，则使用默认箭头。当光标悬停在 `Class.GuiButton` 上时，此属性会被临时忽略。

要完全隐藏光标，**不要** 使用透明图像 &ndash; 而是将 `Class.UserInputService.MouseIconEnabled` 设置为 false。

在体验中获取/设置用户鼠标图标时，您应该使用 `Class.UserInputService.MouseIcon`。`Class.Mouse.Icon` 在为插件设置鼠标光标的新 API 发布后将被弃用。

##### 设计光标

创建自己的鼠标光标时，以下指南可能会很有用：

- 使用的图像的尺寸决定了光标的大小。
- 图像的尺寸不得超过任一轴上的 256 像素。
- 图像的 **中心** 是鼠标输入发出的地方。
- 默认鼠标图像为 64x64 像素，鼠标占据 17x24 像素的空间。

##### 系统光标

当使用从 `Class.Plugin:GetMouse()` 获取的 `Class.PluginMouse` 时，您可以使用以下图标，类似于系统的默认光标，如手、箭头、I beam 等。您可以将这些与 GUI 事件一起使用，如 `Class.GuiObject.MouseEnter|MouseEnter`、`Class.GuiObject.MouseLeave|MouseLeave` 和 `Class.GuiButton.MouseButton1Down|MouseButton1Down`，以在与某些类型的 GUI 组件交互时提供一致的 Studio 体验。请注意，这些仅适用于 Studio 插件；它们不适用于其他 `Class.Mouse` 对象。

<table>
    <thead>
        <tr>
            <th>外观*</th>
            <th>资源</th>
            <th>建议用途</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Pointer.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Arrow</code></td>
            <td>默认点击和选择。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-PointingHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/PointingHand</code></td>
            <td>悬停在活动链接/按钮上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-OpenHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/OpenHand</code></td>
            <td>悬停在可拖动项上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-GrabbingHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/ClosedHand</code></td>
            <td>拖动项。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-IBeam.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/IBeam</code></td>
            <td>悬停在文本框中。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNS.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNS</code></td>
            <td>悬停在垂直调整手柄上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeEW.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeEW</code></td>
            <td>悬停在水平调整手柄上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNESW.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNESW</code></td>
            <td>悬停在角落调整手柄上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNWSE.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNWSE</code></td>
            <td>悬停在角落调整手柄上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeAll.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeAll</code></td>
            <td>悬停在多方向调整手柄上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeSplitV.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SplitNS</code></td>
            <td>悬停在垂直"分割"手柄上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeSplitH.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SplitEW</code></td>
            <td>悬停在水平"分割"手柄上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Forbidden.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Forbidden</code></td>
            <td>悬停在锁定/禁止项上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Wait.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Wait</code></td>
            <td>指示操作正在进行中。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Busy.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Busy</code></td>
            <td>指示系统繁忙。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Crosshair.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Cross</code></td>
            <td>悬停在精确选择区域。</td>
        </tr>
    </tbody>
</table>

<figcaption>* 这些外观是近似值 &mdash; 实际外观取决于您的操作系统。</figcaption>

Mouse.Icon

作为 `Class.Mouse` 图标使用的图像的内容 ID。

**图标** 是一个决定作为指针使用的图像的属性。如果为空，则使用默认箭头。当光标悬停在 `Class.GuiButton` 上时，此属性会被临时忽略。此属性仅支持资产 URI。

要完全隐藏光标，**不要** 使用透明图像 &ndash; 而是将 `Class.UserInputService.MouseIconEnabled` 设置为 false。

在体验中获取/设置用户鼠标图标时，您应该使用 `Class.UserInputService.MouseIcon`。`Class.Mouse.Icon` 在为插件设置鼠标光标的新 API 发布后将被弃用。

##### 设计光标

创建自己的鼠标光标时，以下指南可能会很有用：

- 使用的图像的尺寸决定了光标的大小。
- 图像的尺寸不得超过任一轴上的 256 像素。
- 图像的 **中心** 是鼠标输入发出的地方。
- 默认鼠标图像为 64x64 像素，鼠标占据 17x24 像素的空间。

##### 系统光标

当使用从 `Class.Plugin:GetMouse()` 获取的 `Class.PluginMouse` 时，您可以使用以下图标，类似于系统的默认光标，如手、箭头、I beam 等。您可以将这些与 GUI 事件一起使用，如 `Class.GuiObject.MouseEnter|MouseEnter`、`Class.GuiObject.MouseLeave|MouseLeave` 和 `Class.GuiButton.MouseButton1Down|MouseButton1Down`，以在与某些类型的 GUI 组件交互时提供一致的 Studio 体验。请注意，这些仅适用于 Studio 插件；它们不适用于其他 `Class.Mouse` 对象。

<table>
    <thead>
        <tr>
            <th>外观*</th>
            <th>资源</th>
            <th>建议用途</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Pointer.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Arrow</code></td>
            <td>默认点击和选择。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-PointingHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/PointingHand</code></td>
            <td>悬停在活动链接/按钮上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-OpenHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/OpenHand</code></td>
            <td>悬停在可拖动项上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-GrabbingHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/ClosedHand</code></td>
            <td>拖动项。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-IBeam.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/IBeam</code></td>
            <td>悬停在文本框中。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNS.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNS</code></td>
            <td>悬停在垂直调整手柄上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeEW.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeEW</code></td>
            <td>悬停在水平调整手柄上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNESW.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNESW</code></td>
            <td>悬停在角落调整手柄上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNWSE.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNWSE</code></td>
            <td>悬停在角落调整手柄上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeAll.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeAll</code></td>
            <td>悬停在多方向调整手柄上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeSplitV.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SplitNS</code></td>
            <td>悬停在垂直"分割"手柄上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeSplitH.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SplitEW</code></td>
            <td>悬停在水平"分割"手柄上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Forbidden.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Forbidden</code></td>
            <td>悬停在锁定/禁止项上。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Wait.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Wait</code></td>
            <td>指示操作正在进行中。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Busy.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Busy</code></td>
            <td>指示系统繁忙。</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Crosshair.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Cross</code></td>
            <td>悬停在精确选择区域。</td>
        </tr>
    </tbody>
</table>

<figcaption>* 这些外观是近似值 &mdash; 实际外观取决于您的操作系统。</figcaption>

Mouse.IconContent

作为 `Class.Mouse` 图标使用的图像的内容。仅支持资产 URI。

原始的 `Class.Mouse` 属性是一个 `Datatype.CFrame`，指示鼠标的原始位置。它位于 `Class.Workspace.CurrentCamera` 处并朝向鼠标的 3D 位置。

`Class.Mouse.UnitRay` 从与Origin相同的位置开始，并在相同的方向上延伸 1 个 Stud。

```lua
local unitRay = mouse.UnitRay
local origin = mouse.Origin
-- unitRay.Direction = origin.p
-- unitRay.Direction ≈ origin.lookVector
```
有关 `Class.Mouse` 在 3D 空间中的位置，请参见 `Class.Mouse.Hit`。

Mouse.Origin

定位在 `Class.Workspace.CurrentCamera` 处并朝向鼠标的 3D 位置的 `Datatype.CFrame`。

当放置在 `StarterPlayerScripts` 中的 `LocalScript` 时，以下代码
会改变玩家点击的每个 `BasePart` 的 `Class.BasePart.BrickColor`，
例如生成位置或基础板。


鼠标 `Class.Mouse|mouse` 指向的 3D 空间中的对象。

注意：

- 如果设置了 `Class.Mouse.TargetFilter`，则将忽略目标过滤器及其后代。
- 当鼠标不指向 `Class.BasePart` 时，例如当它指向天空时，目标将为 `nil`。
- 寻找鼠标在 3D 空间中的位置的开发人员应该使用 `Class.Mouse.Hit`。

Mouse.Target

鼠标 `Class.Mouse|mouse` 指向的 3D 空间中的对象。

Mouse.target

此属性确定在计算 `Class.Mouse.Hit` 和 `Class.Mouse.Target` 时要被鼠标忽略的对象。该对象的后代也会被忽略，因此只要它们是设置此属性的对象的后代，就可以忽略多个对象。此属性在过滤包含不应影响 `Class.Mouse.Hit` 或 `Class.Mouse.Target` 的特殊效果或装饰的模型时很有用。

此属性可以设置为任何 `Class.Instance` 或 `nil`，例如：

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

local player = Players.LocalPlayer
local mouse = player:GetMouse()
mouse.TargetFilter = Workspace.Model
```
请注意，`Class.Player.Character|Character` 的 `Class.Players.LocalPlayer` 会被鼠标自动忽略。

Mouse.TargetFilter

确定在确定 `Class.Mouse.Hit` 和 `Class.Mouse.Target` 时要忽略的对象（及其后代）。

此示例中的代码，当放置在 `LocalScript` 中的 `StarterPlayerScripts` 内部时，将会把任何被点击的 `BasePart` 的表面设置为随机表面。


此属性指示鼠标指向的 `Class.BasePart` 表面的 `Enum.NormalId`。
该属性源自鼠标的世界位置 (`Class.Mouse.Hit`) 和鼠标指向的部分 (`Class.Mouse.Target`)。

当鼠标未指向任何部分时，例如当鼠标指向天空时，此属性没有意义。
在这种情况下，此属性被设置为 'Right'。在使用此属性之前，请检查鼠标的目标是否为 `nil`。


Mouse.TargetSurface

指示鼠标指向的 `Class.BasePart` 表面的 `Enum.NormalId`。

UnitRay 属性是一个指向鼠标在 3D 空间中位置的 `Datatype.Ray`（由 `Class.Mouse.Hit` 描述）。它起源于 `Class.Workspace.CurrentCamera` 的 `Class.Camera.CFrame|CFrame`。
像所有单位射线一样，它的距离为 1。


Mouse.UnitRay

从 `Class.Workspace.CurrentCamera` 世界位置向鼠标的世界位置指向的 `Datatype.Ray`。

此代码示例展示了如何创建一个 `Datatype.Vector2`，表示
`Mouse` 对象在屏幕上的位置（`Class.Mouse.X|X()` 和
`Class.Mouse.Y|Y()`）以及屏幕本身的大小
（`Class.Mouse.ViewSizeX|ViewSizeX()` 和 `Class.Mouse.ViewSizeY|ViewSizeY()`）。
使用这些，你可以标准化鼠标在屏幕上的位置，使得
顶部左侧刚好在顶部栏下方映射到 (0, 0)，而底部右侧映射到
(1, 1)。这个标准化位置是在鼠标移动时计算并打印的，
使用 `Class.Mouse.Move|Move()` 事件。


ViewSizeX 属性描述游戏窗口大小的水平分量（以像素为单位）。

Mouse.ViewSizeX

描述游戏窗口的宽度（以像素为单位）。

ViewSizeY 属性描述游戏窗口大小的垂直分量（以像素为单位）。此长度包括顶部区域占用的空间。

Mouse.ViewSizeY

描述游戏窗口的高度（以像素为单位）。

在检测鼠标在屏幕上的位置变化时，建议使用 `Class.ContextActionService:BindAction()` 与 `Enum.UserInputType.MouseMovement` 或 `Class.UserInputService.InputChanged`，它们均使用鼠标的 `Class.InputObject.Position|Position`（一个 `Datatype.Vector3`）描述鼠标的位置，而不是使用此属性和相关属性。

X 属性描述鼠标在屏幕上的水平分量。该位置是相对于顶部左角（即顶部区域下方）的像素测量的。此属性可以与 `Class.Mouse.Y` 一起使用，以生成表示鼠标位置的 `Datatype.Vector2`：

```lua
local position = Vector2.new(mouse.X, mouse.Y)
```
此属性不会触发 `Class.Object.Changed|Changed` 或返回的信号
`Class.Object:GetPropertyChangedSignal()|GetPropertyChangedSignal`。请使用 `Class.Mouse.Move` 事件。

Mouse.X

描述鼠标在屏幕上的 X（水平）分量。

在检测鼠标在屏幕上的位置变化时，建议使用 `Class.ContextActionService:BindAction()` 与 `Enum.UserInputType.MouseMovement` 或 `Class.UserInputService.InputChanged`，它们均使用鼠标的 `Class.InputObject.Position|Position`（一个 `Datatype.Vector3`）描述鼠标的位置，而不是使用此属性和相关属性。

Y 属性描述鼠标在屏幕上的垂直分量。该位置是相对于顶部左角（即顶部区域下方）的像素测量的。此属性可以与 `Class.Mouse.X` 一起使用，以生成表示鼠标位置的 `Datatype.Vector2`：

```lua
local position = Vector2.new(mouse.X, mouse.Y)
```
此属性不会触发 `Class.Object.Changed|Changed` 或返回的信号
`Class.Object:GetPropertyChangedSignal()|GetPropertyChangedSignal`。请使用 `Class.Mouse.Move` 事件。

Mouse.Y

描述鼠标屏幕位置的 Y（垂直）分量。

遗留对象，包含用于指针输入的有用成员。

`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: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.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` 则为 `nil`。


创建实例及其所有后代的副本，忽略不为 `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` 的名为 `Color` 的 `Class.Folder`，
它也具有 `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

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


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

返回一个数组（一个数字索引的表），包含实例的所有直接子级，
或每个 `Class.Instance`，其 `Class.Instance.Parent|Parent` 等于该对象。可以使用数字或通用 `for` 循环对数组进行迭代：

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

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

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

-- 通用循环示例
local children = Workspace:GetChildren()
for i, child in children do
	print(child.Name .. " is child number " .. i)
end
```
请注意，返回的数组 **未** 按任何特定顺序排序，因此建议手动排序（例如使用 `Library.table.sort()`）
以对该方法返回的子级进行排序。

另请参见 `Class.Instance:GetDescendants()|GetDescendants()` 方法。


Instance:GetChildren

返回包含实例所有子级的数组。


Instance:getChildren

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

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


Instance:GetDebugId

scopeLength

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


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

此对象方法返回一个数组，包含该对象的所有后代。
与 `Class.Instance:GetChildren()` 不同，
该方法查找对象的每个子级、每个子级的每个子级，依此类推。

请注意，返回的数组 **未** 按任何特定顺序排序，因此建议手动排序（例如使用 `Library.table.sort()`）
以对该方法返回的后代进行排序。还可以考虑使用 `Class.Instance:QueryDescendants()|QueryDescendants()` 方法通过选择器和组合器的组合查询后代。


Instance:GetDescendants

返回包含实例所有后代的数组。


此代码示例演示了 `Class.Instance:GetFullName()` 的行为。
它显示了在非 `DataModel` 层次结构上的对象调用该函数时的行为，
还展示了返回值如何不转义特殊字符。

此代码示例在 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`，它返回属性的默认值或修改值。


Instance:GetStyled

selector

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


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


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


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


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

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


Instance:GetStyledPropertyChangedSignal

返回在实例上给定样式属性更改时触发的事件。


Instance

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


/reference/engine/classes/PlayerMouse.yaml

摘要