Mẫu mã này bao gồm một ví dụ đơn giản về cách lấy `PlayerMouse` của người chơi địa phương bằng cách sử dụng hàm `Class.Player:GetMouse()` trong một `LocalScript`. Mã này nên được đặt trong một `LocalScript` trong `StarterPlayerScripts`.

PlayerMouse hoạt động giống hệt như đối tượng `Class.Mouse` mà bạn có được từ `Class.Tool.Equipped`. Nó có thể được truy cập từ `Class.LocalScript|LocalScripts` thông qua phương thức `Class.Player:GetMouse()` của người chơi địa phương. Cả PlayerMouse và `Class.Mouse` đều là API cũ, đã được thay thế bởi `Class.UserInputService`.

Điểm khác biệt duy nhất giữa PlayerMouse và đối tượng `Class.Mouse` là PlayerMouse có thể được lấy thông qua phương thức `Class.Player:GetMouse()`.

Trong hầu hết các trường hợp, các nhà phát triển được khuyên nên sử dụng `Class.UserInputService` mới. Tuy nhiên, các đối tượng PlayerMouse và Mouse vẫn được hỗ trợ vì một số lý do. Xem [Input and Camera](/input) để biết thêm thông tin về việc tùy chỉnh đầu vào trong trải nghiệm của bạn.


PlayerMouse

PlayerMouse hoạt động giống hệt như đối tượng `Class.Mouse` mà bạn có được từ `Class.Tool.Equipped`. Cả PlayerMouse và `Class.Mouse` đều là API cũ, đã được thay thế bởi `Class.UserInputService`.


**Chuột** đã bị thay thế bởi `Class.UserInputService` và
`Class.ContextActionService`, có phạm vi rộng hơn, phong phú hơn về tính năng
và hỗ trợ các mẫu **chéo nền tảng** tốt hơn. Nó vẫn được hỗ trợ
do sự phổ biến của nó, nhưng bạn nên cân nhắc sử dụng các tùy chọn này.

Đối tượng **Chuột** chứa nhiều API cho các con trỏ, chủ yếu dành cho nút
và raycasting. Nó có thể được truy cập thông qua `Class.Player:GetMouse()` gọi trên
`Class.Players.LocalPlayer` trong một `Class.LocalScript`. Nó cũng được truyền bởi
event `Class.Tool.Equipped`.

- Nó đặc biệt nổi bật với thuộc tính `Class.Mouse.Icon|Icon`, thay đổi
  kiểu hiển thị của con trỏ.
- Nó liên tục raycast vị trí chuột lên màn hình vào thế giới 3D bằng cách sử dụng
  thuộc tính `Class.Mouse.TargetFilter|TargetFilter`, lưu trữ kết quả của
  raycast trong các thuộc tính `Class.Mouse.Hit|Hit`, `Class.Mouse.Target|Target`, và
  `Class.Mouse.TargetSurface|TargetSurface`. Những điều này có thể hữu ích
  cho các trường hợp đơn giản, nhưng `Class.WorldRoot:Raycast()` nên được sử dụng trong
  những kịch bản [raycasting](/workspace/raycasting) phức tạp hơn.
- `Class.Plugin|Plugins` có thể sử dụng `Class.Plugin:GetMouse()` để lấy
  `Class.PluginMouse`, hoạt động tương tự như vậy.

```lua
-- Từ một LocalScript:
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local mouse = player:GetMouse()
-- Thiết lập biểu tượng chuột
mouse.Icon = "rbxasset://SystemCursors/Wait"
```
Ghi chú:

- Đối tượng này không kiểm soát/hạn chế chuyển động con trỏ. Để làm điều này, hãy xem
  `Class.UserInputService.MouseBehavior` và
  `Class.UserInputService.MouseDeltaSensitivity`.
- Nếu hai hàm được kết nối với cùng một sự kiện đầu vào, chẳng hạn như
  `Class.Mouse.Button1Down|Button1Down`, **cả hai** hàm sẽ chạy khi sự kiện
  xảy ra. Không có khái niệm về việc chặn/truyền đầu vào, vì các sự kiện không
  hỗ trợ hành vi này. Tuy nhiên, `Class.ContextActionService` có hành vi này thông qua
  `Class.ContextActionService:BindAction()|BindAction`.
- Mặc dù có thể không có chuột trên tất cả các nền tảng, chuột vẫn
  hoạt động trên di động (chạm) và console (gamepad), những thứ thường không có
  chuột hoặc phần cứng con trỏ. Để có các hành vi chéo nền tảng rõ ràng, hãy sử dụng
  `Class.UserInputService` và `Class.ContextActionService`.

  Xem [Input và Camera](/input) để biết thêm thông tin về
  việc tùy chỉnh đầu vào trong trải nghiệm của bạn.

Sự kiện này sẽ kích hoạt khi người chơi nhấn nút chuột trái. Lưu ý
rằng điều này có thể được truy cập từ một `Class.Tool`; ví dụ, khi được đặt trong
một `Class.LocalScript`, mã dưới đây sẽ in ra `Button1Down` mỗi khi nút chuột trái được nhấn.

```lua
local tool = script.Parent  -- Đảm bảo đây là một đối tượng Tool

tool.Equipped:Connect(function(mouse)
	mouse.Button1Down:Connect(function()
		print("Button1Down")
	end)
end)
```
Bạn có thể tìm ra vị trí của chuột trong không gian thế giới và nếu nó đang chỉ vào
bất kỳ `Class.BasePart` nào sử dụng thuộc tính `Class.Mouse.Hit|Hit` và
`Class.Mouse.Target|Target`.

Mouse.Button1Down

Kích hoạt khi nút chuột trái được nhấn.

Sự kiện này sẽ kích hoạt khi người chơi thả nút chuột trái. Lưu ý
rằng điều này có thể được truy cập từ một `Class.Tool`; ví dụ, khi được đặt trong
một `Class.LocalScript`, mã dưới đây sẽ in ra `Button1Up` mỗi khi nút chuột trái được thả.

```lua
local tool = script.Parent  -- Đảm bảo đây là một đối tượng Tool

tool.Equipped:Connect(function(mouse)
	mouse.Button1Up:Connect(function()
		print("Button1Up")
	end)
end)
```
Bạn có thể tìm ra vị trí của chuột trong không gian thế giới và nếu nó đang chỉ vào
bất kỳ `Class.BasePart` nào sử dụng thuộc tính `Class.Mouse.Hit|Hit` và
`Class.Mouse.Target|Target`.

Mouse.Button1Up

Kích hoạt khi nút chuột trái được thả.

Sự kiện này sẽ kích hoạt khi người chơi nhấn nút chuột phải. Lưu ý
rằng điều này có thể được truy cập từ một `Class.Tool`; ví dụ, khi được đặt trong
một `Class.LocalScript`, mã dưới đây sẽ in ra `Button2Down` mỗi khi nút chuột phải được nhấn.

```lua
local tool = script.Parent  -- Đảm bảo đây là một đối tượng Tool

tool.Equipped:Connect(function(mouse)
	mouse.Button2Down:Connect(function()
		print("Button2Down")
	end)
end)
```
Bạn có thể tìm ra vị trí của chuột trong không gian thế giới và nếu nó đang chỉ vào
bất kỳ `Class.BasePart` nào sử dụng thuộc tính `Class.Mouse.Hit|Hit` và
`Class.Mouse.Target|Target`.

Mouse.Button2Down

Kích hoạt khi nút chuột phải được nhấn.

Sự kiện này sẽ kích hoạt khi người chơi thả nút chuột phải. Lưu ý
rằng điều này có thể được truy cập từ một `Class.Tool`; ví dụ, khi được đặt trong
một `Class.LocalScript`, mã dưới đây sẽ in ra `Button2Up` mỗi khi nút chuột phải được thả.

```lua
local tool = script.Parent  -- Đảm bảo đây là một đối tượng Tool

tool.Equipped:Connect(function(mouse)
	mouse.Button2Up:Connect(function()
		print("Button2Up")
	end)
end)
```
Bạn có thể tìm ra vị trí của chuột trong không gian thế giới và nếu nó đang chỉ vào
bất kỳ `Class.BasePart` nào sử dụng thuộc tính `Class.Mouse.Hit|Hit` và
`Class.Mouse.Target|Target`.

Mouse.Button2Up

Kích hoạt khi nút chuột phải được thả.

Ví dụ này minh họa cách các sự kiện chuột được truyền trong mỗi khung hình

Kích hoạt trong mỗi nhịp tim mà chuột không được truyền cho sự kiện chuột khác.

Lưu ý, sự kiện này không nên được sử dụng để xác định khi chuột đang đứng yên.
Vì nó kích hoạt trong mỗi nhịp tim nên nó sẽ kích hoạt giữa các sự kiện `Class.Mouse.Move`.

Để biết thêm thông tin về cách lấy đối tượng `Class.Mouse`, xin vui lòng xem trang
`Class.Mouse`.

Các nhà phát triển có thể tìm ra vị trí của chuột trong không gian thế giới, và nếu
nó đang chỉ vào bất kỳ `Class.BasePart` nào sử dụng thuộc tính `Class.Mouse.Hit` và
`Class.Mouse.Target`.

Lưu ý, các nhà phát triển được khuyến nghị sử dụng `Class.UserInputService` thay vì
đối tượng `Class.Mouse` trong các tác phẩm mới.

Mouse.Idle

Kích hoạt trong mỗi nhịp tim mà chuột không được truyền cho sự kiện chuột khác.

Ví dụ bên dưới, giả sử rằng 'mouse' đã được định nghĩa, sẽ in ra phím đã
được nhấn (ví dụ: "q") cùng với giá trị ascii cho phím đó (ví dụ: 113).


Sự kiện này sẽ kích hoạt khi một phím được nhấn, với đối số được truyền là phím đã được nhấn.

Lưu ý:

- Không phải tất cả các phím đều phát sinh sự kiện này. Tuy nhiên, bạn có thể vượt qua điều này với
  một số phím, ví dụ như "/", bằng cách sử dụng sự kiện `Class.Mouse.KeyUp`.
- Một số phím phát sinh cùng một chuỗi như các phím khác.
- Có thể chuỗi là rỗng (có thể do mã phím "\\0").

Mouse.KeyDown

Kích hoạt khi một phím được nhấn.

Mouse.keyDown

Ví dụ dưới đây, giả sử rằng 'mouse' đã được định nghĩa, sẽ in ra phím mà
đã được nhả (ví dụ: "q") cùng với giá trị ascii cho phím đó (ví dụ: 113).


Sự kiện này được kích hoạt khi một phím được thả, với tham số truyền qua là
phím đã được thả.

Lưu ý:

- Không phải tất cả các phím đều tạo ra sự kiện này. Tuy nhiên, bạn có thể vượt qua điều này với
  một vài phím, như phím " / ", bằng cách sử dụng sự kiện
  [[API:Class/Mouse/KeyUp|KeyUp]].
- Một số phím tạo ra cùng một chuỗi như các phím khác.
- Có khả năng chuỗi có thể trống (có thể do mã phím "\\0").


Mouse.KeyUp

Kích hoạt khi một phím được thả.


Ví dụ dưới đây cho phép `Class.Players.LocalPlayer|người chơi địa phương` di chuyển
các phần bằng chuột của họ.

Khi người chơi nhấn nút chuột trái của họ lên một phần, phần đó là
`Class.Mouse.Target|mục tiêu của chuột` và trở thành _điểm_. Cho đến khi người chơi
nhả nút chuột trái, phần đó sẽ di chuyển đến vị trí thế giới của chuột
khi người chơi di chuyển chuột của họ.

Lưu ý rằng thuộc tính `Class.Mouse.TargetFilter` cho phép mã bỏ qua
phần đang được di chuyển khi xác định vị trí thế giới của chuột.

Mã này sẽ hoạt động như mong đợi khi được đặt trong một `LocalScript`.

Kích hoạt khi chuột được di chuyển.

Lưu ý, sự kiện này được kích hoạt khi vị trí của chuột được cập nhật, do đó
nó sẽ kích hoạt lặp đi lặp lại trong khi được di chuyển.

Để biết thông tin về cách lấy đối tượng `Class.Mouse`, vui lòng xem trang
`Class.Mouse`.

Các nhà phát triển có thể tìm ra vị trí của chuột trong không gian thế giới, và nếu
nó đang chỉ vào bất kỳ `Class.BasePart` nào bằng cách sử dụng thuộc tính `Class.Mouse.Hit` và
`Class.Mouse.Target`.

```
mouse.Move:Connect(function()
	local position = mouse.Hit.p
	local target = mouse.Target
	print(target, position)
end)
```
Lưu ý, các nhà phát triển được khuyến nghị sử dụng `Class.UserInputService` thay vì
đối tượng `Class.Mouse` trong công việc mới.


Mouse.Move

Kích hoạt khi chuột được di chuyển.


Ví dụ dưới đây giả định rằng bạn đã có chuột của người chơi (và
đặt nó làm biến có tên là 'mouse'), cho dù bằng cách sử dụng `Class.Tool`,
`Class.HopperBin` hoặc phương thức `Class.Player:GetMouse()`. Nó sẽ in ra
"Bánh xe đã quay lại!" khi người chơi cuộn bánh xe quay lại.

Sự kiện WheelBackward kích hoạt khi bánh xe chuột được cuộn ngược lại.
Các sử dụng có thể cho sự kiện này bao gồm thay đổi phạm vi của súng trong trò chơi bắn súng từ
người thứ nhất (FPS) hoặc phóng to camera của người chơi.

Điều này có thể được sử dụng cùng với sự kiện cuộn về phía trước,
`Class.Mouse.WheelForward`.

Để biết thông tin về cách lấy đối tượng `Class.Mouse`, vui lòng xem trang
`Class.Mouse`.

Lưu ý, các nhà phát triển được khuyến nghị sử dụng `Class.UserInputService` thay vì
đối tượng `Class.Mouse` trong công việc mới.


Mouse.WheelBackward

Kích hoạt khi bánh xe chuột được cuộn ngược lại.


Ví dụ dưới đây giả định rằng bạn đã có chuột của người chơi (và
đặt nó thành một biến có tên là 'mouse'), có thể thông qua việc sử dụng `Tool`, `HopperBin`\hoặc phương thức `Class.Player:GetMouse()`. Nó sẽ in ra "Bánh xe đã di chuyển về phía trước!"
khi người chơi cuộn về phía trước.

Sự kiện WheelForward kích hoạt khi bánh xe chuột được cuộn về phía trước.
Các sử dụng có thể cho sự kiện này bao gồm thay đổi phạm vi của súng trong trò chơi bắn súng từ
người thứ nhất (FPS) hoặc phóng to camera của người chơi.

Điều này có thể được sử dụng cùng với sự kiện cuộn ngược lại,
`Class.Mouse.WheelBackward`.

Để biết thông tin về cách lấy đối tượng `Class.Mouse`, vui lòng xem trang
`Class.Mouse`.

Lưu ý, các nhà phát triển được khuyến nghị sử dụng `Class.UserInputService` thay vì
đối tượng `Class.Mouse` trong công việc mới.


Mouse.WheelForward

Kích hoạt khi bánh xe chuột được cuộn về phía trước.


Mouse

Mã trong ví dụ này, khi được đặt bên trong một `LocalScript` trong
`StarterPlayerScripts`, sẽ vẽ một tia laser đỏ giữa đầu nhân vật và
`Class.Mouse.Hit` vào mọi thời điểm.

Lưu ý, tia này sẽ đi xuyên qua các chướng ngại vật trong chế độ người thứ ba vì raycasting của `Mouse` được thực hiện từ `Class.Workspace.CurrentCamera` chứ không phải từ đầu.

Mã dưới đây hình dung sự khác biệt giữa `Class.Mouse.Hit` và
`Class.Mouse.Origin`. Để làm điều này, mã sử dụng các
vị trí `Datatype.Vector3` của giá trị va chạm và gốc `Datatype.CFrame`
sử dụng `.p`.

Sự khác biệt là gốc là "nơi chuột xuất phát" (gốc của nó)
và va chạm là vị trí mà chuột chạm vào (đó là khi người chơi nhấn
chuột của họ).

Ví dụ này cũng hình dung rằng gốc chuột rất giống với vị trí của
`CurrentCamera` bằng cách in ra độ lớn (khoảng cách) giữa
hai vị trí.

Thuộc tính này chỉ ra `Datatype.CFrame` của vị trí con chuột trong 3D
không gian. Lưu ý rằng `Class.Mouse.TargetFilter` và các đối tượng con của nó sẽ bị
bỏ qua.

Các nhà phát triển có thể lấy được vị trí của Hit như sau:

```
local position = mouse.Hit.Position
```
Hit thường được sử dụng bởi `Class.Tool|Tools` để bắn vũ khí về phía con chuột
trong chế độ góc nhìn thứ ba.

Các nhà phát triển muốn tìm `Class.BasePart` mà chuột đang chỉ vào
nên sử dụng `Class.Mouse.Target`.

#### Làm thế nào để Mouse.Hit được tính toán?

Vị trí của CFrame Hit được tính toán như là điểm giao nhau
giữa `Datatype.Ray` nội bộ của chuột (phiên bản mở rộng của
`Class.Mouse.UnitRay`) và một đối tượng trong không gian 3D (chẳng hạn như một phần).

Định hướng của CFrame Hit tương ứng với hướng của
`Class.Mouse.UnitRay`.

```
local unitRayDirection = mouse.UnitRay.Direction
local mouseHitDirection = mouse.Hit.lookVector
-- unitRayDirection ≈ mouseHitDirection
-- các vector là tương đối bằng nhau
```
Lưu ý, góc nghiêng của `Class.Workspace.CurrentCamera` không được sử dụng khi
tính toán định hướng của Hit `Datatype.CFrame`.

Ray nội bộ của chuột kéo dài đến 1.000 stud. Nếu chuột không
chỉ vào một đối tượng trong không gian 3D (chẳng hạn như khi chỉ vào bầu trời),
thuộc tính này sẽ cách `Class.Workspace.CurrentCamera` 1.000 stud.

Mouse.Hit

`Datatype.CFrame` của vị trí con chuột trong không gian 3D.

Mouse.hit

Ví dụ này thay đổi biểu tượng chuột của `Class.Players.LocalPlayer` để trông giống như một
hình ảnh con rồng.


**Biểu tượng** là một thuộc tính xác định hình ảnh được sử dụng làm con trỏ. Nếu
trống, một mũi tên mặc định sẽ được sử dụng. Khi con trỏ di chuyển qua
một `Class.GuiButton`, thuộc tính này sẽ tạm thời bị bỏ qua.

Để ẩn hoàn toàn con trỏ, **không** sử dụng hình ảnh trong suốt &ndash;
thay vào đó, đặt `Class.UserInputService.MouseIconEnabled` thành false.

Đối với việc lấy/cài đặt biểu tượng chuột của người dùng trong trải nghiệm, bạn nên sử dụng
`Class.UserInputService.MouseIcon`. `Class.Mouse.Icon` sẽ bị lỗi thời
sau khi API mới cho các plugin để đặt con trỏ chuột được phát hành.

##### Thiết kế con trỏ

Các hướng dẫn sau có thể hữu ích khi tạo ra các con trỏ chuột của riêng bạn:

- Kích thước của hình ảnh được sử dụng xác định kích thước của con trỏ.
- Kích thước của hình ảnh không nên vượt quá 256 pixel trên bất kỳ trục nào.
- **Trung tâm** của hình ảnh là nơi mà các input chuột được phát sinh.
- Hình ảnh chuột mặc định là 64x64 pixel, với chuột chiếm 17x24
  pixel không gian.

##### Con trỏ hệ thống

Khi sử dụng một `Class.PluginMouse` lấy từ `Class.Plugin:GetMouse()`,
bạn có thể sử dụng các biểu tượng sau tương tự như các con trỏ mặc định của hệ thống,
hệt như tay, mũi tên, I-beams, v.v. Bạn có thể sử dụng chúng với các sự kiện GUI
như `Class.GuiObject.MouseEnter|MouseEnter`,
`Class.GuiObject.MouseLeave|MouseLeave`, và
`Class.GuiButton.MouseButton1Down|MouseButton1Down` để cung cấp một
trải nghiệm Studio nhất quán khi tương tác với một số loại thành phần GUI.
Lưu ý rằng những điều này chỉ hoạt động cho các plugin Studio; chúng sẽ không
hoạt động cho các đối tượng `Class.Mouse` khác.

<table>
    <thead>
        <tr>
            <th>Hình dáng*</th>
            <th>Tài sản</th>
            <th>Sử dụng Gợi ý</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>Nhấp chuột và chọn mặc định.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-PointingHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/PointingHand</code></td>
            <td>Di chuột qua một liên kết/nút hoạt động.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-OpenHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/OpenHand</code></td>
            <td>Di chuột qua một vật thể có thể kéo.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-GrabbingHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/ClosedHand</code></td>
            <td>Kéo một vật thể.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-IBeam.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/IBeam</code></td>
            <td>Di chuột trong một trường văn bản.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNS.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNS</code></td>
            <td>Di chuột qua một tay cầm thay đổi kích thước theo chiều dọc.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeEW.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeEW</code></td>
            <td>Di chuột qua một tay cầm thay đổi kích thước theo chiều ngang.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNESW.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNESW</code></td>
            <td>Di chuột qua một tay cầm thay đổi kích thước ở góc.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNWSE.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNWSE</code></td>
            <td>Di chuột qua một tay cầm thay đổi kích thước ở góc.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeAll.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeAll</code></td>
            <td>Di chuột qua một tay cầm thay đổi kích thước nhiều hướng.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeSplitV.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SplitNS</code></td>
            <td>Di chuột qua một tay cầm "tách" theo chiều dọc.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeSplitH.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SplitEW</code></td>
            <td>Di chuột qua một tay cầm "tách" theo chiều ngang.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Forbidden.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Forbidden</code></td>
            <td>Di chuột qua một vật thể bị khóa/cấm.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Wait.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Wait</code></td>
            <td>Cho thấy một hành động đang diễn ra.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Busy.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Busy</code></td>
            <td>Cho thấy hệ thống đang bận.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Crosshair.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Cross</code></td>
            <td>Di chuột qua một khu vực chọn điểm chính.</td>
        </tr>
    </tbody>
</table>

<figcaption>* Những hình dáng này chỉ là gần đúng &mdash; ngoại hình thực tế phụ thuộc vào hệ điều hành của bạn.</figcaption>


Mouse.Icon

ID nội dung của hình ảnh được sử dụng làm biểu tượng `Class.Mouse`.


**Biểu tượng** là một thuộc tính xác định hình ảnh được sử dụng làm con trỏ. Nếu
trống, một mũi tên mặc định sẽ được sử dụng. Khi con trỏ di chuyển qua
một `Class.GuiButton`, thuộc tính này sẽ tạm thời bị bỏ qua. Thuộc tính này
chỉ hỗ trợ URI tài sản.

Để ẩn hoàn toàn con trỏ, **không** sử dụng hình ảnh trong suốt &ndash;
thay vào đó, đặt `Class.UserInputService.MouseIconEnabled` thành false.

Đối với việc lấy/cài đặt biểu tượng chuột của người dùng trong trải nghiệm, bạn nên sử dụng
`Class.UserInputService.MouseIcon`. `Class.Mouse.Icon` sẽ bị lỗi thời
sau khi API mới cho các plugin để đặt con trỏ chuột được phát hành.

##### Thiết kế con trỏ

Các hướng dẫn sau có thể hữu ích khi tạo ra các con trỏ chuột của riêng bạn:

- Kích thước của hình ảnh được sử dụng xác định kích thước của con trỏ.
- Kích thước của hình ảnh không nên vượt quá 256 pixel trên bất kỳ trục nào.
- **Trung tâm** của hình ảnh là nơi mà các input chuột được phát sinh.
- Hình ảnh chuột mặc định là 64x64 pixel, với chuột chiếm 17x24
  pixel không gian.

##### Con trỏ hệ thống

Khi sử dụng một `Class.PluginMouse` lấy từ `Class.Plugin:GetMouse()`,
bạn có thể sử dụng các biểu tượng sau tương tự như các con trỏ mặc định của hệ thống,
hệt như tay, mũi tên, I-beams, v.v. Bạn có thể sử dụng chúng với các sự kiện GUI
như `Class.GuiObject.MouseEnter|MouseEnter`,
`Class.GuiObject.MouseLeave|MouseLeave`, và
`Class.GuiButton.MouseButton1Down|MouseButton1Down` để cung cấp một
trải nghiệm Studio nhất quán khi tương tác với một số loại thành phần GUI.
Lưu ý rằng những điều này chỉ hoạt động cho các plugin Studio; chúng sẽ không
hoạt động cho các đối tượng `Class.Mouse` khác.

<table>
    <thead>
        <tr>
            <th>Hình dáng*</th>
            <th>Tài sản</th>
            <th>Sử dụng Gợi ý</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>Nhấp chuột và chọn mặc định.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-PointingHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/PointingHand</code></td>
            <td>Di chuột qua một liên kết/nút hoạt động.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-OpenHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/OpenHand</code></td>
            <td>Di chuột qua một vật thể có thể kéo.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-GrabbingHand.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/ClosedHand</code></td>
            <td>Kéo một vật thể.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-IBeam.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/IBeam</code></td>
            <td>Di chuột trong một trường văn bản.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNS.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNS</code></td>
            <td>Di chuột qua một tay cầm thay đổi kích thước theo chiều dọc.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeEW.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeEW</code></td>
            <td>Di chuột qua một tay cầm thay đổi kích thước theo chiều ngang.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNESW.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNESW</code></td>
            <td>Di chuột qua một tay cầm thay đổi kích thước ở góc.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeNWSE.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeNWSE</code></td>
            <td>Di chuột qua một tay cầm thay đổi kích thước ở góc.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeAll.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SizeAll</code></td>
            <td>Di chuột qua một tay cầm thay đổi kích thước nhiều hướng.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeSplitV.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SplitNS</code></td>
            <td>Di chuột qua một tay cầm "tách" theo chiều dọc.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-ResizeSplitH.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/SplitEW</code></td>
            <td>Di chuột qua một tay cầm "tách" theo chiều ngang.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Forbidden.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Forbidden</code></td>
            <td>Di chuột qua một vật thể bị khóa/cấm.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Wait.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Wait</code></td>
            <td>Cho thấy một hành động đang diễn ra.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Busy.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Busy</code></td>
            <td>Cho thấy hệ thống đang bận.</td>
        </tr>
        <tr>
            <td><img src="../../../assets/misc/Mouse-Icon-Crosshair.png" width="30" /></td>
            <td><code>rbxasset://SystemCursors/Cross</code></td>
            <td>Di chuột qua một khu vực chọn điểm chính.</td>
        </tr>
    </tbody>
</table>

<figcaption>* Những hình dáng này chỉ là gần đúng &mdash; ngoại hình thực tế phụ thuộc vào hệ điều hành của bạn.</figcaption>


Mouse.IconContent

Nội dung của hình ảnh được sử dụng làm biểu tượng `Class.Mouse`. Chỉ hỗ trợ
URI tài sản.


Thuộc tính gốc của `Class.Mouse` là một `Datatype.CFrame` chỉ ra vị trí mà
chuột xuất phát từ. Nó được đặt tại
`Class.Workspace.CurrentCamera` và hướng về vị trí 3D của chuột.

`Class.Mouse.UnitRay` bắt đầu từ cùng một vị trí như Origin, và mở rộng
trong cùng một hướng.

```lua
local unitRay = mouse.UnitRay
local origin = mouse.Origin
-- unitRay.Direction = origin.p
-- unitRay.Direction ≈ origin.lookVector
```
Để biết vị trí của `Class.Mouse` trong không gian 3D, hãy xem `Class.Mouse.Hit`.


Mouse.Origin

Một `Datatype.CFrame` được đặt tại `Class.Workspace.CurrentCamera` và
hướng về vị trí 3D của chuột.


Khi được đặt trong một `LocalScript` trong `StarterPlayerScripts`, đoạn mã sau
thay đổi `Class.BasePart.BrickColor` của mọi `BasePart` mà người chơi nhấp vào,
hay vị trí spawn hoặc baseplate.


Đối tượng trong không gian 3D mà `Class.Mouse|mouse` đang hướng đến.

Lưu ý:

- Nếu `Class.Mouse.TargetFilter` đã được thiết lập, bộ lọc mục tiêu và
  các con của nó sẽ bị bỏ qua.
- Khi chuột không chỉ vào một `Class.BasePart`, ví dụ như khi
  nó chỉ vào bầu trời, Target sẽ là `nil`.
- Các nhà phát triển muốn tìm vị trí của chuột trong không gian 3D nên sử dụng
  `Class.Mouse.Hit`.


Mouse.Target

Đối tượng trong không gian 3D mà `Class.Mouse|mouse` đang hướng đến.


Mouse.target

Thuộc tính này xác định một đối tượng sẽ bị chuột bỏ qua khi
tính toán `Class.Mouse.Hit` và `Class.Mouse.Target`. Các con của
dối tượng cũng bị bỏ qua, vì vậy bạn có thể bỏ qua nhiều đối tượng
miễn là chúng là con của đối tượng mà thuộc tính này được
đặt. Thuộc tính này hữu ích khi lọc các mô hình chứa các
effects đặc biệt hoặc trang trí không nên ảnh hưởng đến `Class.Mouse.Hit` hoặc
`Class.Mouse.Target`.

Thuộc tính này có thể được thiết lập thành bất kỳ `Class.Instance` hoặc `nil`, ví dụ:

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

local player = Players.LocalPlayer
local mouse = player:GetMouse()
mouse.TargetFilter = Workspace.Model
```
Lưu ý rằng `Class.Player.Character|Character` của
`Class.Players.LocalPlayer` sẽ bị chuột tự động bỏ qua.


Mouse.TargetFilter

Xác định một đối tượng (và các con của nó) sẽ bị bỏ qua khi xác định
`Class.Mouse.Hit` và `Class.Mouse.Target`.


Mã trong mẫu này, khi được đặt trong một `LocalScript` bên trong
`StarterPlayerScripts`, sẽ thiết lập bề mặt của bất kỳ `BasePart` nào được nhấp vào thành một
bề mặt ngẫu nhiên.

Thuộc tính này chỉ ra `Enum.NormalId` của bề mặt `Class.BasePart`
mà con chuột đang chỉ vào. Thuộc tính này được lấy từ
vị trí thế giới của chuột (`Class.Mouse.Hit`) và phần mà chuột đang chỉ vào (`Class.Mouse.Target`).

Thuộc tính này không có nghĩa lý khi chuột không chỉ vào một phần,
ví dụ khi chuột đang chỉ vào bầu trời. Hiện tại, thuộc tính này
được đặt thành 'Bên phải' trong những trường hợp này. Trước khi sử dụng thuộc tính này,
hãy kiểm tra mục tiêu của chuột không phải là `nil`.

```lua
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local mouse = player:GetMouse()
-- Kiểm tra rằng có một phần nào đó mà chuột đang chỉ vào
if mouse.Target then
	print("Con chuột đang chỉ vào " .. mouse.TargetSurface.Name .. " phía của " .. mouse.Target.Name)
else
	print("Con chuột không chỉ vào bất cứ thứ gì.")
end
```


Mouse.TargetSurface

Chỉ ra `Enum.NormalId` của bề mặt `Class.BasePart` mà con chuột đang chỉ vào.


Thuộc tính UnitRay là một `Datatype.Ray` hướng về vị trí của chuột
trong không gian 3D (được mô tả bởi `Class.Mouse.Hit`). Nó bắt nguồn từ
`Class.Camera.CFrame|CFrame` của `Class.Workspace.CurrentCamera`.
Như tất cả các tia đơn vị, nó có khoảng cách là 1.

```lua
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local mouse = player:GetMouse()
print(mouse.UnitRay.Direction.Magnitude) -- Luôn luôn 1
```


Mouse.UnitRay

Một `Datatype.Ray` hướng về vị trí thế giới của chuột, bắt nguồn
từ vị trí thế giới của `Class.Workspace.CurrentCamera`.


Ví dụ mã này cho thấy cách bạn có thể tạo ra một `Datatype.Vector2` đại diện cho
vị trí của đối tượng `Mouse` trên màn hình (`Class.Mouse.X|X()` và
`Class.Mouse.Y|Y()`) và kích thước của chính màn hình
(`Class.Mouse.ViewSizeX|ViewSizeX()` và `Class.Mouse.ViewSizeY|ViewSizeY()`).
Sử dụng những điều này, bạn có thể chuẩn hóa vị trí của chuột trên màn hình sao cho
góc trên bên trái ngay dưới thanh công cụ ánh xạ đến (0, 0) và góc dưới bên phải ánh xạ đến
(1, 1). Vị trí đã chuẩn hóa này được tính toán và in ra khi chuột di chuyển
bằng cách sử dụng sự kiện `Class.Mouse.Move|Move()`.

Thuộc tính ViewSizeX mô tả thành phần ngang của kích thước cửa sổ
trò chơi bằng pixel.


Mouse.ViewSizeX

Mô tả độ rộng của cửa sổ trò chơi bằng pixel.


Thuộc tính ViewSizeY mô tả thành phần dọc của kích thước cửa sổ
trò chơi bằng pixel. Chiều dài này bao gồm không gian mà
topbar sử dụng.


Mouse.ViewSizeY

Mô tả chiều cao của cửa sổ trò chơi bằng pixel.


Khi phát hiện các thay đổi trong vị trí của chuột trên màn hình, được
khuyến nghị rằng bạn sử dụng `Class.ContextActionService:BindAction()` với
`Enum.UserInputType.MouseMovement` hoặc
`Class.UserInputService.InputChanged`, cả hai đều mô tả vị trí của
chuột bằng `Class.InputObject.Position|Position` (một
`Datatype.Vector3`) của một `Class.InputObject`, thay vì sử dụng thuộc tính này và
các thuộc tính liên quan.

Thuộc tính X mô tả thành phần ngang của vị trí của chuột trên màn hình.
Vị trí được đo bằng pixel tương ứng với góc trên bên trái,
dưới thanh trên. Thuộc tính này có thể được sử dụng cùng với
`Class.Mouse.Y` để tạo ra một `Datatype.Vector2` đại diện cho vị trí của chuột:

```lua
local position = Vector2.new(mouse.X, mouse.Y)
```
Thuộc tính này không phát ra `Class.Object.Changed|Changed` hoặc tín hiệu
được trả về từ
`Class.Object:GetPropertyChangedSignal()|GetPropertyChangedSignal`. Sử dụng
sự kiện `Class.Mouse.Move` thay vào đó.


Mouse.X

Mô tả thành phần X (ngang) của vị trí chuột trên
màn hình.


Khi phát hiện các thay đổi trong vị trí của chuột trên màn hình, được
khuyến nghị rằng bạn sử dụng `Class.ContextActionService:BindAction()` với
`Enum.UserInputType.MouseMovement` hoặc
`Class.UserInputService.InputChanged`, cả hai đều mô tả vị trí của
chuột bằng `Class.InputObject.Position|Position` (một
`Datatype.Vector3`) của một `Class.InputObject`, thay vì sử dụng thuộc tính này và
các thuộc tính liên quan.

Thuộc tính Y mô tả thành phần dọc của vị trí của chuột trên
màn hình. Vị trí được đo bằng pixel tương ứng với góc trên bên trái,
dưới thanh trên. Thuộc tính này có thể được sử dụng cùng với
`Class.Mouse.X` để tạo ra một `Datatype.Vector2` đại diện cho vị trí của chuột:

```lua
local position = Vector2.new(mouse.X, mouse.Y)
```
Thuộc tính này không phát ra `Class.Object.Changed|Changed` hoặc tín hiệu
được trả về từ
`Class.Object:GetPropertyChangedSignal()|GetPropertyChangedSignal`. Sử dụng
sự kiện `Class.Mouse.Move` thay vào đó.


Mouse.Y

Mô tả thành phần Y (dọc) của vị trí màn hình của chuột.


Đối tượng kế thừa chứa các thành viên hữu ích cho đầu vào từ con trỏ.

`Instance` là lớp cơ sở cho tất cả các lớp trong hệ thống lớp Roblox
mà có thể là một phần của cây `Class.DataModel`.

Không thể tạo các đối tượng `Instance` gốc trực tiếp, nhưng
constructor đặc biệt `Datatype.Instance.new()` tạo ra các đối tượng qua mã,
lấy tên của lớp làm tham số và trả về đối tượng đã được tạo ra.

Minh họa việc phát hiện các thay đổi trong tổ tiên của một thể hiện bằng cách kết nối với sự kiện
`Class.Instance.AncestryChanged`.

Cha của ChangingPart được thiết lập với các giá trị khác nhau theo thời gian. Cha của
phần đó là tổ tiên của phần đó, vì vậy sự kiện `Class.Instance.AncestryChanged` sẽ được kích hoạt
mỗi khi nó thay đổi.


Bắt đầu khi thể hiện này được đặt lại cha hoặc khi bất kỳ tổ tiên nào của nó được
đặt lại cha.

Bạn có thể sử dụng sự kiện này để theo dõi việc xóa một thể hiện trong Studio,
hay là xóa thủ công trong Explorer hoặc thông qua một plugin. Nếu bạn cần
tìm thời điểm một thể hiện bị hủy bằng cách dùng `Class.Instance:Destroy()`,
sử dụng sự kiện `Class.Instance.Destroying` thay vào đó.

Instance.AncestryChanged

child

Thể hiện có thuộc tính `Class.Instance.Parent|Parent` đã thay đổi,
điều này có thể là thể hiện này hoặc một tổ tiên xa hơn, **không**
hất thiết là thể hiện mà hàm xử lý đang kết nối với.

parent

Bắt đầu khi thuộc tính `Class.Instance.Parent` của đối tượng này hoặc một trong
những tổ tiên của nó bị thay đổi.

Sự kiện này bắt đầu bất cứ khi nào bất kỳ thuộc tính nào được thay đổi trên thể hiện,
bao gồm khi một thuộc tính được thiết lập thành `nil`. Tên của thuộc tính đã thay đổi
được truyền vào hàm kết nối.

Chẳng hạn, đoạn mã sau kết nối hàm `attributeChanged()`
để kích hoạt bất cứ khi nào một trong những thuộc tính của phần thay đổi:

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

local part = Workspace.Part

local function attributeChanged(attributeName)
	print(attributeName, "đã thay đổi")
end

part.AttributeChanged:Connect(attributeChanged)
```
Xem thêm `Class.Instance:GetAttributeChangedSignal()` trả về một
sự kiện mà kích hoạt khi một thuộc tính nhất định thay đổi.

Instance.AttributeChanged

attribute

Tên của thuộc tính đã bị thay đổi.

Bắt đầu bất cứ khi nào một thuộc tính được thay đổi trên `Class.Instance`.

Đoạn mã này in tên các đối tượng khi chúng được thêm vào Workspace:


Bắt đầu sau khi một đối tượng được gán làm con của `Class.Instance`.

Lưu ý, khi sử dụng phương thức này trên client để phát hiện các đối tượng được tạo bởi
máy chủ, cần thiết phải sử dụng `Class.Instance:WaitForChild()` khi
chỉ mục các đối tượng con của những đối tượng này. Điều này là do đối tượng và các
đối tượng con của nó không được đảm bảo sao chép từ máy chủ sang client
một cách đồng bộ. Ví dụ:

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

Workspace.ChildAdded:Connect(function(child)
	-- Sử dụng WaitForChild() vì các đối tượng con có thể chưa được sao chép
	local head = child:WaitForChild("Head")
end)
```
Lưu ý, sự kiện này chỉ hoạt động cho các đối tượng con ngay lập tức của
`Class.Instance`. Đối với một sự kiện mà ghi lại tất cả các đối tượng con, hãy sử dụng
`Class.Instance.DescendantAdded`.

Xem thêm `Class.Instance.ChildRemoved`.

Instance.ChildAdded

Đối tượng `Class.Instance` đã được thêm vào.

Bắt đầu sau khi một đối tượng được gán làm con của `Class.Instance`.

Instance.childAdded

Đoạn mã này in ra tên của các đối tượng khi chúng bị xóa khỏi
Workspace:

Bắt đầu sau khi một đối tượng con bị xóa khỏi `Class.Instance`.

Bị xóa đề cập đến khi cha của một đối tượng bị thay đổi từ `Class.Instance`
sang một cái gì đó khác ngoài `Class.Instance`. Lưu ý, sự kiện này
cũng sẽ xảy ra khi một đối tượng con bị hủy (sử dụng
`Class.Instance:Destroy()`) khi chức năng hủy đặt cha của đối tượng
thành `nil`.

Sự kiện này chỉ hoạt động cho các đối tượng con ngay lập tức của
`Class.Instance`. Đối với một sự kiện mà ghi lại tất cả các đối tượng con, hãy sử dụng
`Class.Instance.DescendantRemoving`.

Xem thêm `Class.Instance.ChildAdded`.

Instance.ChildRemoved

Đối tượng `Class.Instance` đã bị xóa.

Bắt đầu sau khi một đối tượng con bị xóa khỏi `Class.Instance`.

Ví dụ sau đây sẽ in ra tên của bất kỳ đối tượng nào được thêm vào
Workspace:


Sự kiện này xảy ra sau khi một đối tượng con được thêm vào `Class.Instance`.

Vì nó xảy ra cho từng đối tượng con, việc gán một đối tượng vào
`Class.Instance` sẽ kích hoạt sự kiện cho đối tượng này và tất cả các
đối tượng con của nó một cách riêng biệt.

Nếu bạn chỉ quan tâm đến **các đối tượng con trực tiếp** của
`Class.Instance`, hãy sử dụng `Class.Instance.ChildAdded` thay vào đó.

Xem thêm `Class.Instance.DescendantRemoving`.

Instance.DescendantAdded

descendant

Bắt đầu sau khi một đối tượng con được thêm vào `Class.Instance`.

Ví dụ sau in tên của bất kỳ đối tượng con nào khi nó đang được gỡ ra
khỏi Workspace:

Sự kiện này xảy ra **ngay trước khi** `Class.Instance`
thay đổi sao cho một thể hiện **con cháu** sẽ không còn là một
con cháu nữa. `Class.Instance:Destroy()|Destroy()` thay đổi
thuộc tính `Class.Instance.Parent|Parent` của một thể hiện thành `nil`, vì vậy việc gọi phương thức đó trên một con cháu của cha sẽ gây ra sự kiện này xảy ra.

Vì sự kiện này xảy ra **trước** khi con cháu bị xóa, cha của
con cháu sẽ không thay đổi tại thời điểm sự kiện này xảy ra. Nếu con cháu
cũng là một **đối tượng trực tiếp** của cha, sự kiện này sẽ xảy ra
trước `Class.Instance.ChildRemoved`.

Nếu một con cháu có các đối tượng con, sự kiện này sẽ xảy ra với con cháu trước,
được theo sau bởi các con cháu của nó.

#### Cảnh báo

Sự kiện này xảy ra với đối tượng con đang bị xóa.
Cố gắng thiết lập thuộc tính `Class.Instance.Parent|Parent` của con cháu thành
một cái gì đó khác sẽ thất bại. Dưới đây là một ví dụ minh họa điều này:

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

Workspace.DescendantRemoving:Connect(function(descendant)
	-- Không thao tác với cha của con cháu trong hàm này!
	-- Sự kiện này xảy ra BỞI vì cha được thao tác, và sự thay đổi chưa diễn ra
	-- Do đó, việc thay đổi cha như thế này là vấn đề:
	descendant.Parent = game
end)

local part = Instance.new("Part")
part.Parent = Workspace
part.Parent = nil
```
Xem thêm `Class.Instance.DescendantAdded|DescendantAdded`.

Instance.DescendantRemoving

Đối tượng `Class.Instance` đang bị xóa.

Bắt đầu ngay trước khi một đối tượng con của `Class.Instance` bị xóa.

Mẫu này minh họa cách mà, khi sử dụng hành vi tín hiệu Ngay lập tức, một
Instance đang bị xóa vẫn giữ nguyên vị trí cho đến khi hàm kết nối tạm dừng.


Ví dụ này cho thấy cách mà, khi sử dụng hành vi tín hiệu Deferred, một Instance
được xóa trước khi tín hiệu được phát.


Đối tượng `Class.Instance` sẽ không bao giờ bị xóa khỏi bộ nhớ trong khi một hàm kết nối
vẫn đang sử dụng nó. Tuy nhiên, nếu hàm đó chờ tại bất kỳ thời điểm nào,
đối tượng `Class.Instance` và các con cháu của nó sẽ được chuyển thành `nil`.

Nếu thuộc tính `Class.Workspace.SignalBehavior` được thiết lập thành
`Enum.SignalBehavior.Immediate`, sự kiện này sẽ xảy ra ngay trước khi
`Class.Instance` hoặc một trong các tổ tiên của nó bị xóa bằng cách dùng
`Class.Instance:Destroy()`.

Nếu thuộc tính `Class.Workspace.SignalBehavior` được thiết lập thành
`Enum.SignalBehavior.Deferred`, sự kiện này sẽ xảy ra tại điểm tiếp theo,
điều này sẽ diễn ra sau khi `Class.Instance` hoặc một trong các tổ tiên của nó
bị xóa bằng cách dùng `Class.Instance:Destroy()`.

Với hành vi `Enum.SignalBehavior.Deferred|Deferred`, việc kết nối một kịch bản
với sự kiện `Class.Instance.Destroying` của chính nó là vấn đề, vì kịch bản
sẽ bị xóa trước khi callback có thể được gọi (nghĩa là nó sẽ không
thực thi).

Khi xóa một `Class.Instance` trong Studio, chẳng hạn như xóa thủ công
thông qua [Explorer](/studio/explorer) hoặc thông qua một plugin,
thì `Class.Instance` không bị xóa. Thay vào đó, cha được đặt thành `nil`
điều này bạn có thể theo dõi bằng `Class.Instance.AncestryChanged`.

Instance.Destroying

Bắt đầu ngay trước khi (hoặc được hoãn đến sau) thể hiện bị
hủy bằng cách dùng `Class.Instance:Destroy()`.

Sự kiện này xảy ra bất cứ khi nào bất kỳ thuộc tính phong cách nào được thay đổi trên thể hiện,
bao gồm khi một thuộc tính được thiết lập thành `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("Các thuộc tính phong cách đã thay đổi")
end

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

Instance.StyledPropertiesChanged

Bắt đầu bất cứ khi nào bất kỳ thuộc tính phong cách nào được thay đổi trên thể hiện, bao gồm
khi một thuộc tính được thiết lập thành `nil`.

Phương thức này áp dụng một thẻ cho đối tượng, không có hiệu ứng nếu thẻ đã
được áp dụng. Thêm thành công một thẻ sẽ kích hoạt tín hiệu được tạo ra bởi
`Class.CollectionService:GetInstanceAddedSignal()` với thẻ đã cho.

#### Cảnh báo

- Các thẻ của một đối tượng đã được thêm từ phía khách hàng sẽ bị xóa nếu máy chủ
   sau đó thêm hoặc xóa một thẻ trên đối tượng đó vì máy chủ
   nhân bản tất cả các thẻ cùng nhau và ghi đè lên các thẻ trước đó.

- Khi đánh dấu một đối tượng, thường có một số tài nguyên được sử dụng để
   cung cấp chức năng cho thẻ đó, ví dụ như các kết nối sự kiện hoặc bảng.
   Để tránh rò rỉ bộ nhớ, tốt nhất là dọn dẹp chúng (ngắt kết nối,
   đặt thành `nil`, v.v.) khi không còn cần thiết cho một thẻ.
   Làm điều này khi gọi `Class.Instance:RemoveTag()`, gọi
   `Class.Instance:Destroy()`, hoặc trong một hàm kết nối với một tín hiệu
   được trả về bởi `Class.CollectionService:GetInstanceRemovedSignal()`.

Instance:AddTag

Áp dụng một thẻ cho đối tượng.

Hàm con trả về một mảng của các con của đối tượng.

Instance:children

Mảng của các đối tượng/các trường hợp con.

Trả về một mảng của các con của đối tượng.

Phương thức này sẽ tiêu diệt tất cả con và hậu duệ của một đối tượng.

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

-- Thêm một số lấp lánh
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
```
Nếu bạn không muốn tiêu diệt **tất cả** con và hậu duệ, vui lòng sử dụng,
`Class.Instance:GetChildren()` hoặc `Class.Instance:GetDescendants()` để
lặp qua các con/hậu duệ đó và chọn những gì để tiêu diệt. Ví dụ,
mẫu mã sau đây sẽ tiêu diệt tất cả
`Class.BasePart|BaseParts` kế thừa từ một `Class.Model`:

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

local model = Workspace:FindFirstChild("TestModel")

for _, descendant in model:GetDescendants() do
	if descendant:IsA("BasePart") then
		descendant:Destroy()
	end
end
```

Instance:ClearAllChildren

Phương thức này tiêu diệt tất cả con của một đối tượng.

Minh họa việc nhân bản một mô hình bằng cách sử dụng `Class.Instance:Clone()`.


`Clone()` tạo ra một bản sao của một đối tượng và tất cả các hậu duệ của nó,
 bỏ qua tất cả các đối tượng không phải
`Class.Instance.Archivable|Archivable`. Bản sao của đối tượng gốc được
trả về bởi phương thức này và `Class.Instance.Parent|Parent` của nó được đặt thành
`nil`. Lưu ý rằng nếu chính đối tượng có
`Class.Instance.Archivable|Archivable` đặt thành `false`, phương thức này sẽ
trả về `nil`.

Nếu một thuộc tính tham chiếu như `Class.ObjectValue.Value` được đặt trong một
đối tượng được sao chép, giá trị của thuộc tính của bản sao phụ thuộc vào
giá trị của đối tượng gốc:

- Nếu một thuộc tính tham chiếu trỏ đến một đối tượng cũng được sao chép,
  bản sao sẽ trỏ đến bản sao đó.
- Nếu một thuộc tính tham chiếu trỏ đến một đối tượng không được sao chép,
  giá trị tương tự được giữ lại trong bản sao.

Instance:Clone

Tạo một bản sao của một đối tượng và toàn bộ hậu duệ của nó, bỏ qua các đối tượng
mà không phải là `Class.Instance.Archivable|Archivable`.

Instance:clone

Minh họa việc phá hủy một Part bằng cách sử dụng hàm `Class.Instance:Destroy()`.

Hàm này là cách đúng để giải phóng các đối tượng không còn cần thiết.

Đặt thuộc tính `Class.Instance.Parent` thành `nil`, khóa thuộc tính
`Class.Instance.Parent`, ngắt kết nối tất cả các kết nối, và gọi
`Destroy()` trên tất cả các con. Phương thức này là cách chính xác để loại bỏ
các đối tượng không còn cần thiết.

Việc loại bỏ các đối tượng không cần thiết là quan trọng, vì các đối tượng và
kết nối không cần thiết trong một địa điểm sử dụng bộ nhớ mà có thể dẫn đến
các vấn đề hiệu suất nghiêm trọng theo thời gian.

Như một phương pháp tốt nhất sau khi gọi `Destroy()` trên một đối tượng, hãy đặt bất kỳ
biến nào tham chiếu đến đối tượng (hoặc các hậu duệ của nó) thành `nil`. Điều này
ngăn chặn mã của bạn truy cập bất kỳ điều gì liên quan đến đối tượng đó.

```lua
local part = Instance.new("Part")
part.Name = "Hello, world"
part:Destroy()
-- Đừng làm điều này:
print(part.Name)  --> "Hello, world"
-- Làm điều này để ngăn dòng trên hoạt động:
part = nil
```
Một khi một `Class.Instance` đã bị tiêu diệt bởi phương thức này, nó không thể được
sử dụng lại vì thuộc tính `Class.Instance.Parent` bị khóa. Để **tạm thời**
loại bỏ một đối tượng thay vì tiêu diệt nó, hãy đặt `Class.Instance.Parent|Parent`
thành `nil`. Ví dụ:

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

object.Parent = nil
task.wait(2)
object.Parent = Workspace
```
Để tiêu diệt một đối tượng sau một khoảng thời gian nhất định, sử dụng
`Class.Debris:AddItem()`.

Instance:Destroy

Đặt thuộc tính `Class.Instance.Parent` thành `nil`, khóa thuộc tính
`Class.Instance.Parent`, ngắt kết nối tất cả các kết nối, và gọi
`Destroy()` trên tất cả các con.

Instance:destroy

Trả về tổ tiên đầu tiên của `Class.Instance` mà có
`Class.Instance.Name` bằng với tên đã cho.

Phương thức này hoạt động lên trên, nghĩa là nó bắt đầu từ `Class.Instance.Parent`
ngay tức thì và đi lên tới `Class.DataModel`. Nếu không tìm thấy tổ tiên tương ứng, nó sẽ trả về `nil`.

Mẫu mã sau đây sẽ tìm tổ tiên đầu tiên của đối tượng
có tên là `Car`.

```
local car = object:FindFirstAncestor("Car")
```
Đối với các biến thể của phương thức này tìm tổ tiên của một lớp cụ thể,
hãy xem `Class.Instance:FindFirstAncestorOfClass()` và
`Class.Instance:FindFirstAncestorWhichIsA()`.

Instance:FindFirstAncestor

name

Tên của `Class.Instance.Name` sẽ được tìm kiếm.

Trả về tổ tiên đầu tiên của `Class.Instance` mà có
`Class.Instance.Name` bằng với tên đã cho.

Trả về tổ tiên đầu tiên của `Class.Instance` mà có
`Class.Object.ClassName` bằng với tên lớp đã cho.

Phương thức này hoạt động lên trên, nghĩa là nó bắt đầu từ `Class.Instance.Parent`
ngay tức thì và đi lên tới `Class.DataModel`. Nếu không tìm thấy tổ tiên tương ứng, nó sẽ trả về `nil`.

Một cách sử dụng phổ biến của phương thức này là tìm `Class.Model` mà một
`Class.BasePart` thuộc về. Ví dụ:

```
local model = part:FindFirstAncestorOfClass("Model")
```
Phương thức này là một biến thể của `Class.Instance:FindFirstAncestor()` mà
kiểm tra thuộc tính `Class.Object.ClassName` thay vì
`Class.Instance.Name`. `Class.Instance:FindFirstAncestorWhichIsA()` cũng
có, sử dụng phương thức `Class.Object:IsA()` để tôn trọng sự kế thừa lớp.

Instance:FindFirstAncestorOfClass

className

Tên `Class.Object.ClassName` sẽ được tìm kiếm.

Trả về tổ tiên đầu tiên của `Class.Instance` mà có
`Class.Object.ClassName` bằng với tên lớp đã cho.

Trả về tổ tiên đầu tiên của `Class.Instance` mà
`Class.Object:IsA()` trả về true cho tên lớp đã cho.

Phương thức này hoạt động lên trên, nghĩa là nó bắt đầu từ `Class.Instance.Parent`
ngay tức thì và đi lên tới `Class.DataModel`. Nếu không tìm thấy tổ tiên tương ứng, nó sẽ trả về `nil`.

Khác với `Class.Instance:FindFirstAncestorOfClass()`, phương thức này sử dụng
`Class.Object:IsA()` mà tôn trọng sự kế thừa lớp. Ví dụ:

```
print(part:IsA("Part"))  --> true
print(part:IsA("BasePart"))  --> true
print(part:IsA("Instance"))  --> true
```
Do đó, mẫu mã sau sẽ trả về tổ tiên đầu tiên của `Class.BasePart`, bất kể nó là `Class.WedgePart`,
`Class.MeshPart` hay `Class.Part`.

```
local part = object:FindFirstAncestorWhichIsA("BasePart")
```
Cũng xem `Class.Instance:FindFirstAncestor()`.

Instance:FindFirstAncestorWhichIsA

Trả về tổ tiên đầu tiên của `Class.Instance` mà
`Class.Object:IsA()` trả về true cho tên lớp đã cho.

Phía dưới sẽ tìm kiếm trong Workspace cho một đối tượng có tên là "Brick". Nếu tìm thấy, nó
sẽ thay đổi tên của đối tượng thành "Foo".

Trả về con đầu tiên của `Class.Instance` với tên đã cho, hoặc
`nil` nếu không có con nào tồn tại. Nếu tham số tùy chọn `recursive`
được đặt thành `true`, phương thức này sẽ tìm kiếm tất cả các hậu duệ thay vì chỉ
các con ngay tức thì của `Class.Instance`.

#### Kiểm tra sự tồn tại của một đối tượng

`FindFirstChild()` là cần thiết nếu bạn cần xác minh một đối tượng tồn tại
trước khi tiếp tục. Cố gắng chỉ mục một con theo tên bằng cách sử dụng toán tử chấm sẽ gây lỗi nếu con không tồn tại.

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

-- Dòng sau sẽ báo lỗi nếu phần không tồn tại trong không gian làm việc
Workspace.Part.Transparency = 0.5
```
Cách tốt hơn là sử dụng `FindFirstChild()` để trước tiên kiểm tra cho `Part`,
sau đó sử dụng câu lệnh `if` để chạy mã cần nó.

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

local part = Workspace:FindFirstChild("Part")
if part then
	part.Transparency = 0.5
end
```

#### Tìm một con có tên khớp với một thuộc tính

Đôi khi `Class.Instance.Name|Name` của một đối tượng là giống với đó
của một thuộc tính của `Class.Instance.Parent|Parent`. Khi sử dụng toán tử chấm,
thuộc tính ưu tiên hơn các con nếu chúng chia sẻ cùng một tên.

Trong ví dụ sau đây, một `Class.Folder` gọi là `Color` đã được thêm vào một
`Class.Part`, mà cũng có thuộc tính `Class.Part.Color`. Lưu ý rằng
`part.Color` ám chỉ đến giá trị thuộc tính `Datatype.Color3`, không phải đối tượng con `Class.Folder`. Lợi ích của việc sử dụng
`Class.Instance:FindFirstChild()|FindFirstChild()` là việc giới thiệu các thuộc tính mới không tạo ra
rủi ro cho mã của bạn.

```lua
local part = Instance.new("Part")
local folder = Instance.new("Folder")
folder.Name = "Color"
folder.Parent = part
local c1 = part.Color  -- Thuộc tính
local c2 = part:FindFirstChild("Color")  -- Thư mục con
```

#### Ghi chú về hiệu suất

`Class.Instance:FindFirstChild()|FindFirstChild()` mất khoảng 20% thời gian
so với việc sử dụng toán tử chấm và gần như 8 lần lâu hơn so với việc chỉ lưu
trữ một tham chiếu đến một đối tượng. Do đó, bạn nên tránh gọi nó trong
mã phụ thuộc vào hiệu suất chẳng hạn như trong các vòng lặp chặt chẽ hoặc các hàm được kết nối
với `Class.RunService.Heartbeat` và `Class.RunService.PreRender`. Thay vào đó,
lưu trữ kết quả trong một biến, hoặc xem xét sử dụng
`Class.Instance.ChildAdded|ChildAdded` hoặc
`Class.Instance:WaitForChild()|WaitForChild()` để phát hiện khi một con có
tên nhất định trở nên khả dụng.

Instance:FindFirstChild

Tên `Class.Instance.Name` sẽ được tìm kiếm.

recursive

Liệu việc tìm kiếm có nên được thực hiện một cách đệ quy hay không.

Trả về con đầu tiên của `Class.Instance` được tìm thấy với tên đã cho.

Instance:findFirstChild

Trả về con đầu tiên của `Class.Instance` mà có
`Class.Object.ClassName|ClassName` bằng với tên `className` đã cho.
Khác với `Class.Instance:FindFirstChildWhichIsA()`, phương thức này chỉ trả về
những đối tượng mà lớp của chúng khớp với `className`, bỏ qua sự kế thừa lớp. Nếu không tìm thấy
con nào tương ứng, phương thức này sẽ trả về `nil`.

Instance:FindFirstChildOfClass

Trả về con đầu tiên của `Class.Instance` mà có
`Class.Object.ClassName|ClassName` bằng với tên lớp đã cho.

Trả về con đầu tiên của `Class.Instance` mà
`Class.Object:IsA()` trả về true cho tên lớp đã cho.

Nếu không tìm thấy con nào tương ứng, phương thức này sẽ trả về `nil`. Nếu tham số
tùy chọn đệ quy là true, phương thức này sẽ tìm kiếm tất cả các hậu duệ hơn là chỉ
các con ngay tức thì của `Class.Instance`.

Khác với `Class.Instance:FindFirstChildOfClass()`, phương thức này sử dụng
`Class.Object:IsA()` mà tôn trọng sự kế thừa lớp. Ví dụ:

```lua
print(part:IsA("Part")) --> true
print(part:IsA("BasePart")) --> true
print(part:IsA("Instance")) --> true
```
Do đó, mẫu mã sau đây sẽ trả về con đầu tiên của `Class.BasePart`, bất kể nó là `Class.WedgePart`,
`Class.MeshPart` hay `Class.Part`.

```
local part = object:FindFirstChildWhichIsA("BasePart")
```
Các nhà phát triển tìm kiếm một con bằng tên nên sử dụng
`Class.Instance:FindFirstChild()` thay vào đó.

Instance:FindFirstChildWhichIsA

Trả về con đầu tiên của `Class.Instance` mà
`Class.Object:IsA()` trả về true cho tên lớp đã cho.

Trả về hậu duệ đầu tiên được tìm thấy với `Class.Instance.Name` đã cho.

Phương thức này đã bị vô hiệu hóa và không thể sử dụng. Để tìm hậu duệ đầu tiên
của một đối tượng, hãy xem xét sử dụng tham số `đệ quy` trên
`Class.Instance:FindFirstChild()` thay thế.

Instance:FindFirstDescendant

Tên `Class.Instance.Name` để tìm kiếm.

Trả về hậu duệ đầu tiên được tìm thấy với `Class.Instance.Name` đã cho.

Nếu `Class.Instance` là một `Class.Actor`, chính `Class.Actor` sẽ được
trả về. Ngược lại, tổ tiên gần nhất của nó `Class.Actor` được trả về. Nếu không
có tổ tiên nào là `Class.Actor`, kết quả là `nil`.

Instance:GetActor

Trả về `Class.Actor` liên kết với Instance, nếu có.

Phương thức này trả về giá trị đã được gán cho tên thuộc tính đã cho.
Nếu không có thuộc tính nào được gán, `nil` sẽ được trả về.

Ví dụ, mẫu mã sau đây thiết lập và sau đó lấy giá trị của
thuộc tính `InitialPosition` của đối tượng:

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

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

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

#### Xem Thêm

- `Class.Instance:SetAttribute()` mà thiết lập thuộc tính với tên đã cho
  thành giá trị đã cho.
- `Class.Instance:GetAttributes()` mà trả về một từ điển của cặp khóa-giá trị
  cho mỗi thuộc tính của đối tượng.

Instance:GetAttribute

Tên của thuộc tính được truy xuất.

Giá trị đã được gán cho tên thuộc tính đã cho. Nếu không có
thuộc tính nào được gán, `nil` sẽ được trả về.

Trả về giá trị đã được gán cho tên thuộc tính đã cho.

Phương thức này trả về một sự kiện mà hoạt động giống như sự kiện
`Class.Object.Changed|Changed`, ngoại trừ việc nó chỉ kích hoạt khi
thuộc tính cụ thể đã cho thay đổi; về cơ bản, nó tương tự như
`Class.Object:GetPropertyChangedSignal()|GetPropertyChangedSignal()` nhưng
cho thuộc tính.

Thông thường, không nên sử dụng phương thức này thay vì một kết nối đến
`Class.Object.Changed|Changed` với một hàm kiểm tra tên thuộc tính. Các lần gọi sau đó
đến phương thức này trên cùng một đối tượng với cùng một tên thuộc tính trả về cùng một sự kiện.

Ví dụ mã sau đây trả về tín hiệu kích hoạt hàm
`attributeChanged()` khi thuộc tính `InitialPosition` của phần thay đổi:

```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)
```
Cũng xem `Class.Instance.AttributeChanged` mà kích hoạt bất cứ lúc nào có
thuộc tính nào bị thay đổi trên đối tượng.

Instance:GetAttributeChangedSignal

Tên của thuộc tính cụ thể mà tín hiệu thay đổi đang được trả về.

Một sự kiện mà kích hoạt khi thuộc tính đã cho thay đổi.

Trả về một sự kiện mà kích hoạt khi thuộc tính đã cho thay đổi.

Phương thức này trả về một từ điển của các cặp khóa-giá trị cho mỗi thuộc tính
nơi khóa là tên của thuộc tính và giá trị là một giá trị không phải `nil`.

Ví dụ, mẫu mã sau đây xuất ra các thuộc tính và giá trị của một đối tượng:

```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
```
Cũng xem `Class.Instance:GetAttribute()` mà trả về giá trị đã được gán cho
 tên thuộc tính đã cho.

Instance:GetAttributes

Một từ điển của các cặp chuỗi → biến thể cho mỗi thuộc tính mà chuỗi là tên
của thuộc tính và biến thể là một giá trị không bằng nil.

Trả về một từ điển của các thuộc tính của đối tượng.

Dưới đây sẽ in tên của tất cả các đối tượng hiện tại trong Workspace khi chạy.

Trả về một mảng (một bảng được lập chỉ mục số) chứa tất cả các
con trực tiếp của đối tượng, hoặc tất cả các `Class.Instance` mà
`Class.Instance.Parent|Parent` của chúng bằng với đối tượng. Mảng này có thể được
lặp qua bằng cả vòng lặp số hoặc vòng lặp tổng quát:

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

-- Ví dụ vòng lặp số
local children = Workspace:GetChildren()
for i = 1, #children do
	local child = children[i]
	print(child.Name .. " là con số " .. i)
end
```

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

-- Ví dụ vòng lặp tổng quát
local children = Workspace:GetChildren()
for i, child in children do
	print(child.Name .. " là con số " .. i)
end
```
Lưu ý rằng mảng trả về **không** được sắp xếp theo bất kỳ thứ tự nào, vì vậy
sắp xếp thủ công (ví dụ như sử dụng `Library.table.sort()`) được khuyên dùng cho
việc sắp xếp các con được trả về bởi phương thức này.

Cũng xem xét phương thức `Class.Instance:GetDescendants()|GetDescendants()`.

Instance:GetChildren

Trả về một mảng chứa tất cả các con của đối tượng.

Instance

`Instance` là lớp cơ sở cho tất cả các lớp trong hệ thống lớp Roblox
mà có thể là một phần của cây `Class.DataModel`.

/reference/engine/classes/PlayerMouse.yaml