這段程式碼範例包含了一個簡單的範例，說明如何使用 `Class.Player:GetMouse()` 函數在
`LocalScript` 中獲取本地玩家的 `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.Player:GetMouse()` 在 `Class.Players.LocalPlayer` 的 `Class.LocalScript` 中訪問。它也被通過 `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` 具有此行為。
- 雖然在所有平台上可能無法使用滑鼠，但滑鼠仍會在行動裝置（觸控）和遊戲主機（遊戲手柄）上正常運作，這些設備通常不具備滑鼠或指標硬體。要實現明確的跨平台行為，請使用 `Class.UserInputService` 和 `Class.ContextActionService`。

  有關自定義輸入的更多信息，請參見 [輸入與攝影機](/input)。

當玩家按下滑鼠的左鍵時觸發此事件。請注意此事件可以在 `Class.Tool` 中訪問；例如，當放置在 `Class.LocalScript` 中時，下面的代碼會在每次按下左鍵時打印 `Button1Down`。

```lua
local tool = script.Parent  -- 確保這是工具對象

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.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.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.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

此範本中的程式碼，當放置在 `StarterPlayerScripts` 中的 `LocalScript` 時，將在角色的頭部與 `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` 用於將武器朝著滑鼠發射，以便從第三人稱視角來看。

開發者尋找滑鼠在 3D 空間中指向的 `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 點。如果滑鼠未指向 3D 空間中的物體（例如，當指向天空時），則此屬性的距離將是距離 `Class.Workspace.CurrentCamera` 1,000 點。

Mouse.Hit

滑鼠在 3D 空間中的位置的 `Datatype.CFrame`。

Mouse.hit

這個範例將 `Class.Players.LocalPlayer` 的滑鼠圖示更改為像是一個
dragon 圖像。


**圖示** 是決定用作指針的圖像的屬性。如果為空，則使用默認箭頭。當游標懸停在 `Class.GuiButton` 上時，會暫時忽略此屬性。

要完全隱藏游標，**不**要使用透明圖像 &ndash; 而是將 `Class.UserInputService.MouseIconEnabled` 設置為 false。

要在經驗中獲取/設置用戶鼠標圖示，應使用 `Class.UserInputService.MouseIcon`。 `Class.Mouse.Icon` 將在新 API 發佈後被棄用，該 API 允許插件設置鼠標光標。

##### 設計游標

以下準則在創建自己的鼠標游標時可能會有所幫助：

- 使用的圖像的尺寸決定游標的大小。
- 圖像的尺寸在任何軸上均不應超過 256 像素。
- 圖像的 **中心** 是鼠標輸入發出的地方。
- 默認的鼠標圖像為 64x64 像素，鼠標佔用 17x24 像素的空間。

##### 系統游標

當使用從 `Class.Plugin:GetMouse()` 獲取的 `Class.PluginMouse` 時，可以使用以下圖標，這些圖標類似於系統的默認游標，如手、箭頭、I 形光標等。您可以在 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 發佈後被棄用，該 API 允許插件設置鼠標光標。

##### 設計游標

以下準則在創建自己的鼠標游標時可能會有所幫助：

- 使用的圖像的尺寸決定游標的大小。
- 圖像的尺寸在任何軸上均不應超過 256 像素。
- 圖像的 **中心** 是鼠標輸入發出的地方。
- 默認的鼠標圖像為 64x64 像素，鼠標佔用 17x24 像素的空間。

##### 系統游標

當使用從 `Class.Plugin:GetMouse()` 獲取的 `Class.PluginMouse` 時，可以使用以下圖標，這些圖標類似於系統的默認游標，如手、箭頭、I 形光標等。您可以在 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` 從與原始位置相同的位置開始，並沿相同方向延伸一個 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

一個 `Datatype.CFrame`，位於 `Class.Workspace.CurrentCamera` 並面向鼠標的 3D 位置。


當放置在 `StarterPlayerScripts` 的 `LocalScript` 中時，以下代碼
會更改玩家點擊的每個 `BasePart` 的 `Class.BasePart.BrickColor`，
例如出生位置或基板。


位於鼠標所指向的 3D 空間中的對象。

注意：

- 如果已設置 `Class.Mouse.TargetFilter`，則會忽略目標過濾和其子項。
- 當鼠標不指向 `Class.BasePart` 時，例如當它指向天空時，目標將為 `nil`。
- 開發者尋找鼠標在 3D 空間中的位置應使用 `Class.Mouse.Hit`。


Mouse.Target

位於鼠標所指向的 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`。

```lua
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local mouse = player:GetMouse()
-- 檢查鼠標指向的部件是否存在
if mouse.Target then
	print("鼠標指向的部件是 " .. mouse.TargetSurface.Name .. " 側面 " .. mouse.Target.Name)
else
	print("鼠標不指向任何東西。")
end
```


Mouse.TargetSurface

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


UnitRay 屬性是一個 `Datatype.Ray`，指向鼠標在 3D 空間中的位置（由 `Class.Mouse.Hit` 描述）。它源自 `Class.Workspace.CurrentCamera` 的 `Class.Camera.CFrame|CFrame`。
如所有單位光線一樣，它的距離為 1。

```lua
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local mouse = player:GetMouse()
print(mouse.UnitRay.Direction.Magnitude) -- 始終為 1
```


Mouse.UnitRay

一個指向鼠標的世界位置，源自 `Class.Workspace.CurrentCamera` 世界位置的 `Datatype.Ray`。


此範例程式碼展示了如何創建一個 `Datatype.Vector2` 來表示

滑鼠物件在螢幕上的位置 (`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 的 Parent 隨著時間設置為不同的值。部分的父項是該部分的祖先，因此每當發生變化時，`Class.Instance.AncestryChanged` 事件將被觸發。


當此實例被重新父級化或其任何祖先被重新父級化時觸發。

您可以使用此事件來跟踪 Studio 中實例的刪除，例如在 Explorer 中的手動刪除或通過插件。如果您需要檢測實例是否使用 `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` 後觸發。

以下範例在任何後代被移除時打印其名稱

從 Workspace 中：

這個事件在父項 `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` 時，都會觸發。

此方法為實例應用標籤，如果標籤已經應用則不會有任何效果。成功添加標籤將觸發由 `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` 的實例。

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.Instance` 的第一個祖先，其 `Class.Object.ClassName` 等於給定的 className。

返回 `Class.Instance` 的第一個祖先，該祖先對應於 `Class.Object:IsA()` 返回 true 的給定 className。

此方法向上工作，意味著它從實例的直接 `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()` 返回 true 的給定 className。

以下將在工作區中尋找名為"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()` 返回 true 的給定 className。

如果未找到匹配子物件，則此方法返回 `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()` 返回 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("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 .. " 是子物件號 " .. i)
end
```

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

-- 通用循環示例
local children = Workspace:GetChildren()
for i, child in children do
	print(child.Name .. " 是子物件號 " .. 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`，這返回屬性的默認或修改值。

```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

selector

要針對實例中定位的伪實例的可選選擇器。

指定屬性樣式或明確修改的值，否則返回屬性的默認值（如果沒有樣式/修改）。

返回指定屬性樣式或明確修改的值，否則返回屬性的默認值（如果沒有樣式/修改）。

此方法返回一個事件，該事件的行為與 `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

Instance

`Instance` 是 Roblox 類別階層中所有類別的基礎類別，可以是 `Class.DataModel` 樹的一部分。

/reference/engine/classes/PlayerMouse.yaml