`Class.BillboardGui` là một container cho các đối tượng UI xuất hiện trong không gian 3D
nhưng luôn hướng về phía máy ảnh. Vị trí của container tương đối với
`Class.BasePart` hoặc `Class.Attachment` (hoặc
`Class.BillboardGui.Adornee|Adornee`). Đối với `Class.BasePart|BaseParts`, thuôc tính
`Class.BasePart.Position|Position` được sử dụng, trong khi đối với
`Class.Attachment|Attachments`, thuôc tính
`Class.Attachment.WorldPosition|WorldPosition` được sử dụng.

<img src="/assets/ui/in-experience/BillboardGui-Diagram.jpg" width="800" alt="BillboardGui với một TextLabel mô tả bảng điều khiển màn hình mà nó nổi trên đó." />

Thuôc tính `Class.BillboardGui.Size|Size` của một billboard hoạt động hơi
khác so với `Class.GuiObject.Size`. Trong khi các thành phần **offset** hoạt động
giống nhau, các thành phần **scale** được sử dụng như kích thước stud trong không gian 3D.

Khi tạo một `Class.BillboardGui` kích thước theo tỷ lệ chứa một
`Class.TextLabel`, có thể hữu ích để bật thuộc tính
`Class.TextLabel.TextScaled|TextScaled` của nhãn để văn bản của nó điều chỉnh theo
bảng canvas billboard khi khoảng cách máy ảnh thay đổi.

Lưu ý rằng các phần tử UI tương tác như `Class.ImageButton|ImageButtons` và
`Class.TextButton|TextButtons` bên trong `Class.BillboardGui` chỉ nhận được
 đầu vào của người dùng nếu chúng được đặt làm con của `Class.PlayerGui`,
thường là thông qua việc đặt `Class.BillboardGui` bên trong `Class.StarterGui`. Thuôc tính
`Class.BillboardGui.Adornee|Adornee` có thể được sử dụng để nhắm đến một phần hoặc
gắn kết trong thế giới 3D trong khi `Class.BillboardGui` vẫn nằm trong
`Class.PlayerGui`.

Xem [UI trong trải nghiệm](/ui/in-experience-containers#billboard-ui)
để có hướng dẫn về cách làm việc với các container `Class.BillboardGui`.

##### Hành vi lưu trữ

Để cải thiện hiệu suất, hình dáng của `Class.BillboardGui` sẽ được
lưu trữ cho đến khi một trong những điều sau xảy ra, sau đó hình dáng sẽ
được tính toán lại trong khung hình kết xuất tiếp theo.

- Một phần tử con được thêm vào hoặc loại bỏ khỏi `Class.BillboardGui`.
- Một thuộc tính của một phần tử con của `Class.BillboardGui` thay đổi.
- Một thuộc tính của chính `Class.BillboardGui` thay đổi.


BillboardGui

Kiểm soát xem các phần tử con có nhận sự kiện đầu vào hay không. Nếu
`Class.BillboardGui` chứa một `Class.GuiButton`, nút đó sẽ chỉ có thể
nhấn nếu `Class.BillboardGui.Active|Active` được đặt thành `true` trên
cả `Class.BillboardGui` **và** nút.

Lưu ý rằng các phần tử UI tương tác như `Class.ImageButton|ImageButtons`
và `Class.TextButton|TextButtons` bên trong `Class.BillboardGui` sẽ chỉ
nhận được đầu vào của người dùng nếu chúng được đặt làm con của
`Class.PlayerGui`, thường là thông qua việc đặt `Class.BillboardGui` bên trong
`Class.StarterGui`. Thuôc tính `Class.BillboardGui.Adornee|Adornee` có thể được sử dụng
để nhắm đến một phần hoặc gắn kết trong thế giới 3D trong khi `Class.BillboardGui`
vẫn nằm trong `Class.PlayerGui`.


BillboardGui.Active

Kiểm soát xem các phần tử con có nhận sự kiện đầu vào hay không.


Đặt `Class.BasePart` hoặc `Class.Attachment` mục tiêu mà `Class.BillboardGui`
được đặt tương đối, ghi đè lên phần cha hoặc gắn kết.


BillboardGui.Adornee

Đặt phần hoặc gắn kết mục tiêu mà `Class.BillboardGui` được
đặt tương đối.


Thuôc tính này xác định xem `Class.BillboardGui` có luôn
hiển thị trên cùng các đối tượng 3D khác hay không.

Khi được đặt thành `false` (mặc định), `Class.BillboardGui` sẽ hiển thị như các
nội dung 3D khác và bị che khuất bởi các đối tượng 3D khác. Khi đặt thành `true`, `Class.BillboardGui`
luôn hiển thị trên cùng nội dung 3D và hình dáng thay đổi đáng kể:

- Màu sắc khớp với cách chúng xuất hiện trong một `Class.ScreenGui`.
- Văn bản có thể sắc nét hơn trên các thiết bị DPI cao.
- `Class.BillboardGui.LightInfluence|LightInfluence` được coi như là `0`.
- `Class.BillboardGui.Brightness|Brightness` không có tác dụng.


BillboardGui.AlwaysOnTop

Xác định xem `Class.BillboardGui` có luôn được hiển thị trên cùng
các đối tượng 3D khác hay không.


Thuôc tính này xác định hệ số mà ánh sáng của container `Class.BillboardGui`
được tỷ lệ khi `Class.BillboardGui.LightInfluence|LightInfluence` là `0`. Mặc định,
thuôc tính này là `1` và có thể được đặt thành bất kỳ số nào giữa `0` và `1000`.
Bằng cách sửa đổi thuôc tính này, độ sáng hiển thị của một
`Class.BillboardGui` có thể được phù hợp tốt hơn với môi trường của nó. Ví dụ, một billboard video có thể được làm sáng trong một căn phòng tối bằng cách
tăng `Class.BillboardGui.Brightness|Brightness` lên `10`.

Lưu ý rằng `Class.BillboardGui.Brightness|Brightness` không thể truy cập trong
Studio và không có tác dụng khi `Class.BillboardGui.LightInfluence|LightInfluence` là `1` hoặc
`Class.BillboardGui.AlwaysOnTop|AlwaysOnTop` là `true`.


BillboardGui.Brightness

Xác định hệ số mà ánh sáng của container `Class.BillboardGui`
được tỷ lệ khi `Class.BillboardGui.LightInfluence|LightInfluence` là `0`.


Khi được đặt thành `true` (mặc định), các phần của `Class.GuiObject|GuiObjects`
được rơi ra ngoài các biên canvas `Class.BillboardGui` sẽ không được
vẽ.

Ngay cả khi thuôc tính này là `false`, `Class.GuiObject|GuiObjects` hoàn toàn
nằm ngoài canvas sẽ không được hiển thị.


BillboardGui.ClipsDescendants

Có xác định xem các phần của `Class.GuiObject|GuiObjects` rơi ra ngoài
các biên của canvas `Class.BillboardGui` sẽ được vẽ hay không.


Khoảng cách hiện tại trong studs mà `Class.BillboardGui` ở
xa camera của người chơi. Một sự kiện thay đổi không được kích hoạt cho thuôc tính này trừ khi
`Class.BillboardGui.DistanceStep|DistanceStep` lớn hơn `0`.


BillboardGui.CurrentDistance

Khoảng cách hiện tại trong studs mà `Class.BillboardGui` ở
xa camera của người chơi.


Xác định khoảng cách trong studs tại đó `Class.BillboardGui` sẽ
ngừng tỷ lệ lớn hơn về kích thước tương đối với camera hiện tại của người chơi, với
một mặc định là `0`. Nếu `Class.BillboardGui.CurrentDistance|CurrentDistance`
của `Class.BillboardGui` dưới giá trị này, nó sẽ không mở rộng lớn hơn
như nó sẽ ở khoảng cách này.


BillboardGui.DistanceLowerLimit

Xác định khoảng cách trong studs tại đó `Class.BillboardGui` sẽ
ngừng tỷ lệ lớn hơn về kích thước.


Xác định kích thước `Class.BillboardGui.CurrentDistance|CurrentDistance`
tăng và giảm trong studs khi camera của người chơi di chuyển tới gần và
xa `Class.BillboardGui`. Thuôc tính này mặc định là `0`.


BillboardGui.DistanceStep

Xác định kích thước `Class.BillboardGui.CurrentDistance|CurrentDistance`
tăng và giảm trong studs khi camera của người chơi di chuyển tới gần và
xa `Class.BillboardGui`.


Xác định khoảng cách trong studs tại đó `Class.BillboardGui` sẽ
ngừng tỷ lệ nhỏ hơn về kích thước tương đối với camera hiện tại của người chơi. Nếu
`Class.BillboardGui.CurrentDistance|CurrentDistance` của `Class.BillboardGui`
trên giá trị này, nó sẽ không nhỏ hơn kích thước tối đa của nó vào khoảng cách này.

Thuôc tính này bị bỏ qua nếu giá trị thấp hơn `0`. Giá trị mặc định
là `-1`, có nghĩa là thuôc tính này sẽ bị bỏ qua theo mặc định.


BillboardGui.DistanceUpperLimit

Xác định khoảng cách trong studs tại đó `Class.BillboardGui` sẽ
ngừng tỷ lệ nhỏ hơn về kích thước.


Thuôc tính này xác định cách `Class.BillboardGui` bị lệch khỏi
`Class.BillboardGui.Adornee|Adornee`, tương đối với hướng nhìn của
`Class.Camera`, bằng đơn vị một nửa kích thước của hộp bao quanh
`Class.Camera`-canh chỉnh của mô hình.

Xem thêm `Class.BillboardGui.StudsOffset|StudsOffset` hoạt động
tương tự nhưng sử dụng đơn vị stud, hoặc
`Class.BillboardGui.ExtentsOffsetWorldSpace|ExtentsOffsetWorldSpace` hoạt động
tương tự ngoại trừ việc hướng lệch là tương đối với các trục toàn cầu.


BillboardGui.ExtentsOffset

Xác định cách `Class.BillboardGui` bị lệch khỏi
`Class.BillboardGui.Adornee|Adornee`, tương đối với hướng nhìn của
`Class.Camera`, bằng đơn vị một nửa kích thước của hộp bao quanh
`Class.Camera`-canh chỉnh của mô hình.


Thuôc tính này xác định cách `Class.BillboardGui` bị lệch khỏi
`Class.BillboardGui.Adornee|Adornee`, tương đối với các trục toàn cầu, trong
đơn vị một nửa kích thước của hộp bao quanh định hướng trục của mô hình.

Xem thêm `Class.BillboardGui.StudsOffset|StudsOffset` hoạt động
tương tự nhưng sử dụng đơn vị stud, hoặc
`Class.BillboardGui.ExtentsOffset|ExtentsOffset` hoạt động tương tự
ngoại trừ việc hướng lệch là tương đối với `Class.Camera`.


BillboardGui.ExtentsOffsetWorldSpace

Xác định cách `Class.BillboardGui` bị lệch khỏi
`Class.BillboardGui.Adornee|Adornee`, tương đối với các trục toàn cầu, trong
đơn vị một nửa kích thước của hộp bao quanh định hướng trục của mô hình.


Kiểm soát mức độ mà `Class.BillboardGui` bị ảnh hưởng bởi ánh sáng môi trường,
trong khoảng từ `0` đến `1`. Đặt điều này thành `1` có nghĩa là ánh sáng xung quanh
có toàn quyền kiểm soát hình dáng, trong khi đặt thành `0` có nghĩa là ánh sáng không có tác dụng.


BillboardGui.LightInfluence

Kiểm soát mức độ mà `Class.BillboardGui` bị ảnh hưởng bởi ánh sáng môi trường.


Thuôc tính này kiểm soát khoảng cách từ camera mà `Class.BillboardGui`
sẽ được hiển thị trước khi nó ngừng hiển thị. Giá trị `0` hoặc `inf`
(mặc định) có nghĩa là không có giới hạn và nó sẽ hiển thị vô hạn xa.

Đối với `Class.BillboardGui|BillboardGuis` xuất hiện ngoài trời,
được khuyên nên đặt `Class.BillboardGui.MaxDistance|MaxDistance` đủ cao
để đảm bảo rằng UI của container đủ nhỏ trên
màn hình khi nó xuất hiện hoặc biến mất, giúp giảm thiểu tác động pop‑in/out đột ngột.


BillboardGui.MaxDistance

Kiểm soát khoảng cách mà `Class.BillboardGui` có thể được hiển thị trước khi nó
ngừng hiển thị.


Được sử dụng bởi các script để ẩn `Class.BillboardGui` khỏi một người chơi cụ thể.

Để ẩn một `Class.BillboardGui` khỏi nhiều người chơi, hãy đặt nó vào
`Class.StarterGui` và sử dụng một script để đặt thuộc tính
`Class.BillboardGui.Enabled|Enabled` theo liệu `Class.Players.LocalPlayer|LocalPlayer`
có thể nhìn thấy nó hay không. Thuôc tính
`Class.BillboardGui.Adornee|Adornee` có thể được sử dụng để gắn
`Class.BillboardGui` vào một `Class.BasePart` hoặc `Class.Attachment` trong
`Class.Workspace`, thay vì đặt nó làm con.


BillboardGui.PlayerToHideFrom

Được sử dụng bởi các script để ẩn `Class.BillboardGui` khỏi một người chơi cụ thể.


Kiểm soát kích thước mà `Class.BillboardGui` sẽ có trên màn hình.
Khác với `Class.GuiObject.Size`, các thành phần
[scale](/ui/position-and-size#size) của thuôc tính này
đặt kích thước stud của billboard trong không gian 3D.


BillboardGui.Size

Kiểm soát kích thước mà `Class.BillboardGui` sẽ có trên màn hình.


Một độ lệch 2D trong các đơn vị liên quan đến kích thước hoạt động như một điểm neo. Điều này
có thể được sử dụng tương tự như thuộc tính `Class.GuiObject.AnchorPoint`, nhưng
g các giá trị là khác nhau.

<table size="small">
<thead>
<th>Offset Kích thước</th>
<th>Giải thích</th>
</thead>
<tbody>
<tr>
<td><code>0, 0</code></td>
<td>Mặc định trong đó UI sẽ được neo tại chính giữa.</td>
</tr>
<tr>
<td><code>0.5, 0.5</code></td>
<td>UI sẽ neo ở góc dưới bên trái.</td>
</tr>
<tr>
<td><code>0.5, -0.5</code></td>
<td>UI sẽ neo ở góc trên bên trái.</td>
</tr>
<tr>
<td><code>-0.5, 0.5</code></td>
<td>UI sẽ neo ở góc trên bên phải.</td>
</tr>
<tr>
<td><code>-0.5, -0.5</code></td>
<td>UI sẽ neo ở góc dưới bên phải.</td>
</tr>
</tbody>
</table>

Xem thêm `Class.BillboardGui.StudsOffset|StudsOffset`,
`Class.BillboardGui.StudsOffsetWorldSpace|StudsOffsetWorldSpace`,
`Class.BillboardGui.ExtentsOffset|ExtentsOffset`, và
`Class.BillboardGui.ExtentsOffsetWorldSpace|ExtentsOffsetWorldSpace` đều là các thuộc tính lệch hoạt động trong 3D.


BillboardGui.SizeOffset

Một độ lệch 2D trong các đơn vị liên quan đến kích thước hoạt động như một điểm neo.


Thuôc tính này xác định cách `Class.BillboardGui` được lệch khỏi
`Class.BillboardGui.Adornee|Adornee` trong studs, tương đối với
hướng nhìn của `Class.Camera`.

Xem thêm `Class.BillboardGui.StudsOffsetWorldSpace|StudsOffsetWorldSpace`
hoạt động tương tự ngoại trừ việc hướng lệch là tương đối với các trục
toàn cầu.


BillboardGui.StudsOffset

Xác định cách `Class.BillboardGui` được lệch khỏi
`Class.BillboardGui.Adornee|Adornee` trong studs, tương đối với
hướng nhìn của `Class.Camera`.


Thuôc tính này xác định cách `Class.BillboardGui` được lệch khỏi
`Class.BillboardGui.Adornee|Adornee` trong studs, tương đối với các trục toàn cầu.

Xem thêm `Class.BillboardGui.StudsOffset|StudsOffset` hoạt động
tương tự ngoại trừ việc hướng lệch là tương đối với `Class.Camera`.


BillboardGui.StudsOffsetWorldSpace

Xác định cách `Class.BillboardGui` được lệch khỏi
`Class.BillboardGui.Adornee|Adornee` trong studs, tương đối với các trục toàn cầu.


Một container cho `Class.GuiObject|GuiObjects` được hiển thị trong không gian 3D hướng về phía
máy ảnh.


**LayerCollector** là lớp cơ sở của các container UI 2D, hiển thị
các con cháu của `Class.GuiObject`, chẳng hạn như `Class.ScreenGui`.

Để cải thiện hiệu suất, hình thức của `Class.LayerCollector`
bị lưu trữ cho đến khi một trong các sự kiện sau xảy ra:

- Một con cháu được thêm vào hoặc xóa khỏi nó.
- Một thuộc tính của một con cháu thay đổi.
- Một thuộc tính của chính `Class.LayerCollector` thay đổi.

LayerCollector:GetLayoutNodeTree

LayerCollector

Chuyển đổi khả năng nhìn thấy của `Class.LayerCollector` này. Khi là `false`, các
nội dung UI sẽ không được hiển thị, không xử lý đầu vào của người dùng, hoặc cập nhật
theo phản ứng với các thay đổi.

LayerCollector.Enabled

Chuyển đổi khả năng nhìn thấy của `Class.LayerCollector` này.

Khi được đặt là `false` và `Class.LayerCollector` này là con trực tiếp của
`Class.StarterGui`, nó chỉ được sao chép vào `Class.PlayerGui` của mỗi người chơi một lần và sẽ không bị xóa khi nhân vật của người chơi
xuất hiện lại.

Khi được đặt là `true` (mặc định), hoặc nếu `Class.LayerCollector` này là một
con cháu **gián tiếp** của `Class.StarterGui`, nó sẽ được sao chép vào
`Class.PlayerGui` của mỗi người chơi khi nhân vật của họ xuất hiện lại và nó sẽ
xóa chính nó khi nhân vật của người chơi xuất hiện lại lần nữa.

LayerCollector.ResetOnSpawn

Xác định xem `Class.LayerCollector` có được đặt lại (xóa nó và
tạo lại vào `Class.PlayerGui` của người chơi) mỗi khi nhân vật của người chơi
xuất hiện lại hay không.

Điều khiển cách `Class.GuiObject.ZIndex` hoạt động trên tất cả các mục con của
`Class.LayerCollector`.

Với `Enum.ZIndexBehavior.Sibling` (mặc định), trẻ em luôn được hiển thị trên
các bậc phụ huynh của chúng, và `Class.GuiObject.ZIndex|ZIndex` được sử dụng để quyết định
thứ tự mà trẻ em của một đối tượng UI đơn sẽ hiển thị lên nhau.

`Enum.ZIndexBehavior.Global` sắp xếp tất cả các mục con theo
`Class.GuiObject.ZIndex|ZIndex`, sau đó giải quyết các mối liên quan bằng cách sử dụng thứ tự
hệ thống. Do đó, các mục con của `Class.GuiObject` cần có một
giá trị `Class.GuiObject.ZIndex|ZIndex` ít nhất phải cao bằng
bậc phụ huynh của chúng, nếu không chúng sẽ được hiển thị dưới bậc phụ huynh của mình.


LayerCollector.ZIndexBehavior

Điều khiển cách `Class.GuiObject.ZIndex` hoạt động trên tất cả các mục con của
`Class.LayerCollector`.


Lớp cơ sở của các container UI 2D, được sử dụng để hiển thị `Class.GuiObject|GuiObjects`
trong các lớp.

`Class.GuiBase2d` là một lớp trừu tượng được kế thừa bởi 2D
`Class.GuiObject|GuiObjects`.


Sự kiện này được kích hoạt khi việc chọn gamepad di chuyển đến, rời khỏi, hoặc thay đổi
trong `Class.GuiBase2d` kết nối hoặc bất kỳ phần tử con nào
`Class.GuiObject|GuiObjects`. Khi điểm nhấn chọn di chuyển đến một
`Class.GuiObject`, sự kiện sẽ nổi lên từ `Class.GuiObject` đó đến tất cả các tổ tiên của nó,
cho họ biết rằng sự chọn đã
thay đổi/nhập/xuất khỏi một `Class.GuiObject` trong cây con của họ.


GuiBase2d.SelectionChanged

amISelected

Đúng nếu lựa chọn mới khớp với GuiBase2d đã được gắn.


previousSelection

newSelection

Kích hoạt khi việc chọn gamepad di chuyển đến, rời khỏi, hoặc thay đổi trong
`Class.GuiBase2d` kết nối hoặc bất kỳ phần tử con nào
`Class.GuiObject|GuiObjects`.


GuiBase2d

`Class.GuiBase2d.AbsolutePosition|AbsolutePosition` là một thuộc tính chỉ đọc
cung cấp vị trí màn hình của một phần tử `Class.GuiBase2d` tính bằng pixel. Điều này đại diện cho vị trí pixel thực tế mà một phần tử
được tạo ra do các kích thước và vị trí của tổ tiên của nó. Lưu ý rằng
`Class.GuiBase2d.AbsolutePosition|AbsolutePosition` luôn đại diện cho
góc trên bên trái của phần tử `Class.GuiBase2d`.

Nếu `Class.GuiBase2d` nằm trong một `Class.ScreenGui`, thuộc tính
`Class.GuiBase2d.AbsolutePosition|AbsolutePosition` sử dụng
toạ độ xem của hệ thống tọa độ `Enum.ScreenInsets|CoreUISafeInsets`. Điểm gốc của hệ thống tọa độ này nằm ở góc dưới bên trái của
theo dõi Roblox. Lưu ý rằng đây là cùng một hệ thống tọa độ được sử dụng bởi thuộc tính `Class.InputObject.Position`.

<img src="/assets/engine-api/classes/GuiBase2d/AbsolutePositionCoordinateSystem.png" width="840" alt="Sơ đồ cho thấy gốc của hệ thống tọa độ AbsolutePosition." />

Xem thêm `Class.GuiBase2d.AbsoluteRotation|AbsoluteRotation` và
`Class.GuiBase2d.AbsoluteSize|AbsoluteSize`.


GuiBase2d.AbsolutePosition

Mô tả vị trí màn hình thực tế của một phần tử `Class.GuiBase2d`, tính bằng
pixel.


`Class.GuiBase2d.AbsoluteRotation|AbsoluteRotation` là một thuộc tính chỉ đọc
mô tả góc quay màn hình thực tế của một phần tử `Class.GuiBase2d`, tính bằng độ. Nó **không** thực hiện kiểm tra giới hạn, vì vậy giá trị của nó
có thể không nằm trong khoảng `0` đến `360`.

Xem thêm `Class.GuiBase2d.AbsolutePosition|AbsolutePosition` và
`Class.GuiBase2d.AbsoluteSize|AbsoluteSize`.


GuiBase2d.AbsoluteRotation

Mô tả góc quay màn hình thực tế của một phần tử `Class.GuiBase2d`, tính bằng
degree.


`Class.GuiBase2d.AbsoluteSize|AbsoluteSize` là một thuộc tính chỉ đọc mô tả
kích thước màn hình thực tế của một phần tử `Class.GuiBase2d`, tính bằng
pixel.

Xem thêm `Class.GuiBase2d.AbsolutePosition|AbsolutePosition` và
`Class.GuiBase2d.AbsoluteRotation|AbsoluteRotation`.


GuiBase2d.AbsoluteSize

Mô tả kích thước màn hình thực tế của một phần tử `Class.GuiBase2d`, tính bằng
pixel.


Khi được đặt thành `true`, việc địa phương hóa sẽ được áp dụng cho `Class.GuiBase2d`
và các phần tử con của nó. Các mục được sử dụng để địa phương hóa là cùng một tập hợp các mục
được trả về bởi `Class.LocalizationService:GetTableEntries()`. Các mục
với `Class.GuiBase2d.AutoLocalize|AutoLocalize` được bật sẽ tự động
được dịch lại sau khi bảng đám mây tải xong nếu cần.

Xem thêm `Class.GuiBase2d.RootLocalizationTable|RootLocalizationTable`.


GuiBase2d.AutoLocalize

Khi được đặt thành `true`, việc địa phương hóa sẽ được áp dụng cho `Class.GuiBase2d`
và các phần tử con của nó.


Thuộc tính này tự động được thiết lập thành true khi thuộc tính gốc của bảng địa phương hóa
`Class.LocalizationTable.Root` nhắm đến đối tượng này, hoặc tổ tiên của đối tượng này. `Class.LocalizationTable|LocalizationTables` có thuộc tính
`Class.LocalizationTable.Root` chỉ định một thể hiện sẽ
địa phương hóa tất cả `Class.TextLabel.TextButton` là con cháu của thể hiện gốc.


GuiBase2d.Localize

Tự động được thiết lập thành true khi thuộc tính gốc của bảng địa phương hóa
`Class.LocalizationTable.Root` nhắm đến đối tượng này, hoặc tổ tiên của đối tượng này.


Một tham chiếu đến `Class.LocalizationTable` sẽ được sử dụng để áp dụng việc địa phương hóa tự động
cho `Class.GuiBase2d` này và các phần tử con của nó.
`Class.GuiBase2d.AutoLocalize|AutoLocalize` phải được đặt thành `true` trên
`Class.GuiBase2d` và các tổ tiên của nó để việc địa phương hóa tự động được
áp dụng.

Bạn có thể thiết lập cái này để tham chiếu tới `Class.LocalizationTable` ở bất kỳ đâu trong
`Class.DataModel`. Đối tượng `Class.GuiBase2d` và tất cả các con của nó
sẽ cố gắng sử dụng bảng `Class.LocalizationTable` cụ thể đó và các tổ tiên
của nó cho việc thay thế văn bản tự động trước khi sử dụng các bảng trong
`Class.LocalizationService` theo thứ tự không xác định và bảng đám mây.

Nếu không có bản dịch nào có sẵn trong bảng được tham chiếu, nó sẽ tìm
theo dõi bản dịch trong bậc cha mẹ của bảng đó, nếu nó cũng là một
`Class.LocalizationTable`, và tiếp tục như vậy.

Xem thêm `Class.LocalizationService:GetTableEntries()` giải thích cách mà
`Class.GuiBase2d.RootLocalizationTable|RootLocalizationTable` được sử dụng
cho việc địa phương hóa tự động.


GuiBase2d.RootLocalizationTable

Một tham chiếu đến `Class.LocalizationTable` sẽ được sử dụng để áp dụng việc địa phương hóa tự động
cho `Class.GuiBase2d` này và các phần tử con của nó.


Tùy chỉnh hành vi chọn gamepad theo hướng xuống.


GuiBase2d.SelectionBehaviorDown

Tùy chỉnh hành vi chọn gamepad theo hướng trái.


GuiBase2d.SelectionBehaviorLeft

Tùy chỉnh hành vi chọn gamepad theo hướng phải.


GuiBase2d.SelectionBehaviorRight

Tùy chỉnh hành vi chọn gamepad theo hướng lên.


GuiBase2d.SelectionBehaviorUp

Cho phép tùy chỉnh cách mà việc chọn gamepad có thể di chuyển giữa
các nút, là các phần tử con của nhóm chọn, rời khỏi nhóm,
và chọn các nút khác.

Đặt `Class.GuiBase2d.SelectionGroup|SelectionGroup` thành `true` sẽ
mở ra các thuộc tính `Class.GuiBase2d.SelectionBehaviorUp|SelectionBehaviorUp`,
`Class.GuiBase2d.SelectionBehaviorDown|SelectionBehaviorDown`,
`Class.GuiBase2d.SelectionBehaviorLeft|SelectionBehaviorLeft`, và
`Class.GuiBase2d.SelectionBehaviorRight|SelectionBehaviorRight`.
Đối với những hành vi chọn này, việc thiết lập
`Enum.SelectionBehavior.Escape` (mặc định) có nghĩa là việc chọn gamepad
cố gắng tìm một lựa chọn trong nhóm chọn trước và chỉ di chuyển
ngoài nếu không tìm thấy một nút phù hợp. Ngược lại, việc thiết lập
`Enum.SelectionBehavior.Stop` có nghĩa là việc chọn gamepad chỉ tìm kiếm
trong nhóm chọn và không di chuyển ra ngoài nhóm từ hướng hành vi chọn.


GuiBase2d.SelectionGroup

Cho phép tùy chỉnh chuyển động khi chọn gamepad.


Một lớp trừu tượng được kế thừa bởi 2D `Class.GuiObject|GuiObjects`.


GuiBase là một lớp trừu tượng mà hầu hết các đối tượng giao diện người dùng đồ họa
kế thừa từ nó.


GuiBase

`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

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

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/BillboardGui.yaml