`CanvasGroup` 将子对象以组的形式渲染，并对渲染结果应用颜色和透明度。
`Class.UIComponent` 的视觉修饰符，如 `Class.UICorner` 和 `Class.UIGradient`，在 `CanvasGroup` 下也将适用于整个组。请注意，`CanvasGroup` 始终将 `Class.GuiObject.ClipsDescendants|ClipsDescendants` 设置为 `true`，所有子对象将在组的视口内渲染。

#### 注意事项

- 仅当祖先 `Class.LayerCollector` 的 `Class.LayerCollector.ZIndexBehavior|ZIndexBehavior` 设置为 `Enum.ZIndexBehavior.Sibling` 时，`CanvasGroup` 的子对象才会作为平坦的纹理进行渲染。
- `CanvasGroup` 会消耗额外的纹理内存。纹理的质量和总内存使用量受到客户端的 `Enum.QualityLevel` 的限制。当超出内存上限时，`CanvasGroup` 将渲染为空白纹理。
- 建议将 `CanvasGroup` 与静态大小一起使用，否则将需要创建新的纹理以适应新大小。


CanvasGroup

CanvasGroup.GroupColor3

CanvasGroup.GroupTransparency

将后代作为一组进行颜色/透明度混合。

`Class.GuiObject` 是一个抽象类（类似于 `Class.BasePart`），用于 2D
用户界面对象。它定义了与图形用户界面（GUI）对象的显示相关的所有属性，如 `Class.GuiObject.Size|Size`
和 `Class.GuiObject.Position|Position`。它还有一些有用的只读
属性，如 `Class.GuiObject.AbsolutePosition|AbsolutePosition`、
`Class.GuiObject.AbsoluteSize|AbsoluteSize` 和
`Class.GuiObject.AbsoluteRotation|AbsoluteRotation`。

要以特殊方式操作GUI对象的布局，可以使用布局
结构，例如 [list/flex](/ui/list-flex-layouts) 或
[grid](/ui/grid-table-layouts)，并且可以通过
[appearance modifiers](/ui/appearance-modifiers) 在核心属性之外对其进行样式化。

虽然可以使用 `Class.GuiObject.InputBegan|InputBegan` 和
`Class.GuiObject.InputEnded|InputEnded` 检测任何 GUI 对象上的鼠标按钮事件，只有 `Class.ImageButton` 和
`Class.TextButton` 具有方便的专用事件，例如
`Class.TextButton.Activated|Activated` 来检测点击/按压。

以下示例假定它在一个 GuiObject 内，如 `TextButton`，并且
`Class.GuiObject.Draggable` 属性被设置为 true。它将打印玩家开始拖动对象的 UDim2。

当玩家开始拖动对象时，此事件被触发。

另请参见 `Class.GuiObject.DragStopped`。

GuiObject.DragBegin

initialPosition

在任何拖动操作开始之前，`Class.GuiObject` 的位置的 `Datatype.UDim2` 值。

当玩家开始拖动对象时被触发。

下面的示例假设在一个 GuiObject 中，例如 `TextButton`，并且
`Class.GuiObject.Draggable` 属性被设置为 true。它将打印玩家停止拖动 GUI 的 X 和 Y 坐标。例如，如果玩家在 189, 180 停止拖动对象，下面将打印 玩家在 (189, 180) 停止拖动 GuiObject

当玩家停止拖动对象时，此事件被触发。

另请参见 `Class.GuiObject.DragBegin`。

GuiObject.DragStopped

鼠标在屏幕上的 **X** 位置，以像素为单位，相对于屏幕左上角。

鼠标在屏幕上的 **Y** 位置，以像素为单位，相对于屏幕左上角。

当玩家停止拖动对象时被触发。

以下示例演示了根据输入类型处理用户输入的众多用法之一。

为了使其按预期工作，它必须放置在 `LocalScript` 中并且是 _gui_ 的子项。

当用户通过人机界面设备（鼠标按钮按下、开始触摸、键盘按钮按下等）与 `Class.GuiObject` 交互时，此事件被触发。

`Class.UserInputService` 还有一个同名事件，它不局限于特定的 UI 元素：`Class.UserInputService.InputBegan`。

此事件无论游戏状态如何始终会触发。

另请参见 `Class.GuiObject.InputEnded` 和 `Class.GuiObject.InputChanged`。

GuiObject.InputBegan

input

一个 `Class.InputObject`，包含用于查询用户输入的有用数据，如 `Enum.UserInputType|输入类型`，`Enum.UserInputState|输入状态`，以及 `Class.InputObject.Position|输入的屏幕坐标`。

当用户开始通过人机界面设备交互时触发（鼠标按钮按下、开始触摸、键盘按钮按下等）。

以下示例演示了处理用户从 InputChanged 发送输入的多种用例之一，具体取决于输入的类型。

为了使其按预期工作，必须将其放置在 `LocalScript` 中，并且是 _gui_ 的子级。

当用户更改通过人机界面设备（鼠标按钮按下、开始触摸、键盘按钮按下等）的交互方式时，此事件被触发。

`Class.UserInputService` 还有一个同名事件，它不局限于特定的 UI 元素：`Class.UserInputService.InputChanged`。

此事件无论游戏状态如何始终会触发。

另请参见 `Class.GuiObject.InputBegan` 和 `Class.GuiObject.InputEnded`。

GuiObject.InputChanged

当用户更改通过人机界面设备的交互方式时被触发（鼠标按钮按下、开始触摸、键盘按钮按下等）。

以下示例演示了根据输入类型处理用户输入的许多使用示例之一。

为了使其按预期工作，必须将其放置在 `LocalScript` 中，并且是 _gui_ 的子级。


InputEnded 事件在用户停止通过人机界面设备（鼠标按钮按下、开始触摸、键盘按钮按下等）交互时触发。

`Class.UserInputService` 还有一个同名事件，它不局限于特定的 UI 元素：`Class.UserInputService.InputEnded`。

此事件无论游戏状态如何始终会触发。

另请参见 `Class.GuiObject.InputBegan` 和 `Class.GuiObject.InputChanged`。

GuiObject.InputEnded

一个 `Class.InputObject`，包含用于查询用户输入的有用数据，如 `Enum.UserInputType`、`Enum.UserInputState` 和 `Class.InputObject.Position`。

当用户停止通过人机界面设备交互时触发（鼠标按钮按下、开始触摸、键盘按钮按下等）。

以下示例将在鼠标进入GUI元素时打印鼠标位置（以像素为单位）。

当用户将鼠标移动到 `Class.GuiObject` 元素中时，MouseEnter 事件被触发。

请注意，不要依赖此事件传递的 `x` 和 `y` 参数作为确定用户鼠标何时进入 GUI 的简单方法。这些坐标可能会变化，即使鼠标通过相同的边缘进入 GUI -特别是当鼠标快速进入元素时。这是因为坐标指示事件触发时鼠标的位置，而不是鼠标进入 GUI 的确切时刻。

即使 GUI 元素在另一个元素下渲染，此事件还是会被触发。

如果您希望跟踪用户的鼠标何时离开 GUI 元素，您可以使用 `Class.GuiObject.MouseLeave` 事件。

##### 另请参见

- `Class.GuiObject.MouseLeave`
- `Class.GuiObject.MouseMoved`
- `Class.GuiObject.MouseWheelForward`
- `Class.GuiObject.MouseWheelBackward`

GuiObject.MouseEnter

鼠标在屏幕上的 **X** 坐标，以像素为单位，相对于屏幕左上角。

鼠标在屏幕上的 **Y** 坐标，以像素为单位，相对于屏幕左上角。

当用户将鼠标移动到 GUI 元素中时触发。

MouseLeave 事件在用户将鼠标移出 `Class.GuiObject` 元素时被触发。

请注意，不要依赖此事件传递的 `x` 和 `y` 参数作为确定用户鼠标何时离开 GUI 的简单方法。这些坐标可能会变化，即使鼠标通过相同的边缘离开 GUI -特别是当鼠标快速离开元素时。这是因为坐标指示事件触发时鼠标的位置，而不是鼠标离开 GUI 的确切时刻。

即使 GUI 元素在另一个元素下渲染，此事件还是会被触发。

##### 另请参见

- `Class.GuiObject.MouseEnter`
- `Class.GuiObject.MouseMoved`
- `Class.GuiObject.MouseWheelForward`
- `Class.GuiObject.MouseWheelBackward`

GuiObject.MouseLeave

当用户将鼠标移出 GUI 元素时被触发。

每当用户在 `Class.GuiObject` 元素内部移动他们的鼠标时被触发。它类似于 `Class.Mouse.Move`，在用户的鼠标是否在 GUI 元素上时触发。

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

`x` 和 `y` 参数指示用户鼠标的更新屏幕坐标，以像素为单位。这些信息可以帮助确定鼠标在 GUI、屏幕上的位置，以及相对于鼠标之前的位置的增量。

下面的代码演示了如何确定用户鼠标相对于 GUI 元素的 `Datatype.Vector2` 偏移：

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

local CustomScrollingFrame = script.Parent
local SubFrame = CustomScrollingFrame:FindFirstChild("SubFrame")

local mouse = Players.LocalPlayer:GetMouse()

local function getPosition(X, Y)
	local gui_X = CustomScrollingFrame.AbsolutePosition.X
	local gui_Y = CustomScrollingFrame.AbsolutePosition.Y


	local pos = Vector2.new(math.abs(X - gui_X), math.abs(Y - gui_Y - 36))
	print(pos)
end

CustomScrollingFrame.MouseMoved:Connect(getPosition)
```
请注意，此事件可能不会在用户的鼠标进入或退出 GUI 元素的确切时刻触发。因此，`x` 和 `y` 参数可能不会完全与 GUI 的边缘坐标匹配。

##### 另请参见

- `Class.GuiObject.MouseEnter`
- `Class.GuiObject.MouseLeave`
- `Class.GuiObject.MouseWheelForward`
- `Class.GuiObject.MouseWheelBackward`

GuiObject.MouseMoved

每当用户在 GUI 元素内部移动他们的鼠标时被触发。

WheelBackward 事件在用户在 `Class.GuiObject` 元素上向后滚动鼠标时被触发。它类似于
`Class.Mouse.WheelBackward`，在用户的鼠标是否在 GUI 元素上时触发。

此事件仅作为滚轮向后移动的指示。这意味着 `x` 和 `y` 鼠标坐标参数并未因为此事件而改变。这些坐标仅在鼠标移动时变化，可以通过 `Class.GuiObject.MouseMoved` 事件进行跟踪。

##### 另请参见

- `Class.GuiObject.MouseEnter`
- `Class.GuiObject.MouseLeave`
- `Class.GuiObject.MouseMoved`
- `Class.GuiObject.MouseWheelForward`

GuiObject.MouseWheelBackward

当用户在 GUI 元素上向后滚动鼠标时被触发。

WheelForward 事件在用户在 `Class.GuiObject` 元素上向前滚动鼠标时被触发。它类似于
`Class.Mouse.WheelForward`，在用户的鼠标是否在 GUI 元素上时触发。

此事件仅作为滚轮向前移动的指示。这意味着 **X** 和 **Y** 鼠标坐标参数并未因为此事件而改变。这些坐标仅在鼠标移动时变化，可以通过 `Class.GuiObject.MouseMoved` 事件进行跟踪。

##### 另请参见

- `Class.GuiObject.MouseEnter`
- `Class.GuiObject.MouseLeave`
- `Class.GuiObject.MouseMoved`
- `Class.GuiObject.MouseWheelBackward`

GuiObject.MouseWheelForward

当用户在 GUI 元素上向前滚动鼠标时被触发。

以下示例在用户使用游戏手柄选择对象时打印一条消息。

为了使其按预期工作，它必须放置在 `LocalScript` 中并且是 _gui_ 的子项。

当游戏手柄选择器开始聚焦于 `Class.GuiObject` 时，此事件被触发。

如果您想检查游戏手柄选择器何时停止聚焦于 GUI 元素，可以使用 `Class.GuiObject.SelectionLost` 事件。

当 GUI 获得选择焦点时，`Class.GuiService.SelectedObject|SelectedObject` 属性的值也将更改。
要确定哪个 GUI 获得了选择，请检查此属性的值。

GuiObject.SelectionGained

当 GuiObject 被游戏手柄选择器聚焦时被触发。

以下示例在元素失去焦点时打印一条消息。

为了使其按预期工作，必须将其放置在 `LocalScript` 中，并且是 _gui_ 的子项。

当游戏手柄选择器停止聚焦于 `Class.GuiObject` 时，此事件被触发。

如果您想检查游戏手柄选择器何时开始聚焦于 GUI 元素，可以使用 `Class.GuiObject.SelectionGained` 事件。

当某个 GUI 失去选择焦点时，`Class.GuiService.SelectionObject|SelectionObject` 属性的值将更改为 `nil` 或获取选择焦点的 GUI 元素。
要确定哪个 GUI 获得选择焦点，或者是否没有 GUI 被选择，请检查此属性的值。

GuiObject.SelectionLost

当游戏手柄选择器停止聚焦于 GuiObject 时被触发。

此代码示例允许玩家通过短暂按住 UI 元素（如 `Frame`）来操作某些 UI 元素的屏幕位置。然后，玩家移动手指并释放。在手势过程中，框架的颜色为蓝色并带有白色轮廓。

此事件在玩家使用触摸设备按住 UI 元素后短暂后触发。它会带有一个表，包含描述手势中涉及的手指相对屏幕位置的 `Datatype.Vector2`。此外，它会多次触发：在短暂延迟后触发 `Enum.UserInputState.Begin`，如果玩家在手势过程中移动手指则触发 `Enum.UserInputState.Change`，最后触发 `Enum.UserInputState.End`。延迟时间取决于平台；在 Studio 中，延迟时间稍长于一秒。

GuiObject.TouchLongPress

touchPositions

一个 `Datatype.Vector2` 的数组，描述参与手势的手指的 **相对** 位置。

state

一个 `Enum.UserInputState`，描述手势的状态：

- Begin 在手势开始时触发一次（经过短暂延迟后）
- Change 如果玩家在按住时移动手指则触发
- End 在玩家释放手指时触发一次，表示手势结束。

当玩家开始、继续和停止长按 UI 元素时触发。

这个代码示例旨在放置在一个 `LocalScript` 内，该脚本位于一个内部
`Frame` 中，而这个内部 `Frame` 又位于一个外部 `Frame` 或其他 `GuiObject` 内。它允许玩家通过在外部框架上移动手指来操控内部框架的位置。

此事件在玩家使用触摸设备在 UI 元素上移动手指时触发。它在 `Class.GuiObject.TouchSwipe` 之前短暂触发，并且不在 `Class.GuiObject.TouchTap` 中触发。此事件对于允许玩家操控屏幕上 UI 元素的位置非常有用。

此事件带有一个表，包含描述手势中涉及的手指相对屏幕位置的 `Datatype.Vector2`。此外，它会多次触发：在短暂延迟后触发 `Enum.UserInputState.Begin`，在玩家在手势过程中移动手指时触发 `Enum.UserInputState.Change`，最后触发 `Enum.UserInputState.End`。

GuiObject.TouchPan

一个 Luau 数组，包含 `Datatype.Vector2` 对象，表示参与手势的所有手指的位置。

totalTranslation

表示平移手势相对于起始点的距离。

velocity

表示手势在每个维度上执行的速度。

当玩家在 UI 元素上移动手指时触发。

这段代码示例是为了在一个内部 `Frame` 的 `LocalScript` 而设计的，该内部 `Frame` 位于一个外部 `Frame` 或其他 `GuiObject` 之内。它允许玩家通过在外部框架上执行 `Class.GuiObject.TouchPinch` 手势来缩放内部框架。

此事件在玩家使用两个手指在 UI 元素上做捏合或拉动手势时触发，使用的是触摸设备。当两个或多个手指靠近时发生 **捏合**，当它们分开时发生 **拉动**。此事件与 `Class.GuiObject.TouchPan` 一起触发。此事件对于允许玩家操控屏幕上 UI 元素的缩放（大小）非常有用，通常用于缩放功能。

此事件带有一个表，包含描述手势中涉及的手指相对屏幕位置的 `Datatype.Vector2`。此外，它会多次触发：在短暂延迟后触发 `Enum.UserInputState.Begin`，在玩家在手势过程中移动手指时触发 `Enum.UserInputState.Change`，最后触发 `Enum.UserInputState.End`。需要注意的是，缩放应该是 **乘法式的**。

GuiObject.TouchPinch

一个 Luau 数组，包含 `Datatype.Vector2` 对象，表示参与捏合手势的所有手指的位置。

scale

一个浮点数，表示捏合手势开始时的差异。

一个浮点数，表示捏合手势进行的速度。

当玩家使用两个手指在 UI 元素上执行捏合或拉伸手势时触发。

这个代码示例适用于一个位于外部 `Frame` 内部的 `LocalScript`，或其他 `GuiObject`。它允许玩家通过在外部框架上执行 `Class.GuiObject.TouchRotate` 手势来旋转内部框架。

此事件在玩家使用两个手指在 UI 元素上做捏合或拉动手势时触发，使用的是触摸设备。当两根手指之间的线的角度变化时发生旋转。此事件与 `Class.GuiObject.TouchPan` 一起触发。此事件对于允许玩家操控屏幕上 UI 元素的旋转非常有用。

此事件带有一个表，包含描述手势中涉及的手指相对屏幕位置的 `Datatype.Vector2`。此外，它会多次触发：在短暂延迟后触发 `Enum.UserInputState.Begin`，在玩家在手势过程中移动手指时触发 `Enum.UserInputState.Change`，最后触发 `Enum.UserInputState.End`。

GuiObject.TouchRotate

一个 `Datatype.Vector2` 对象的 Luau 数组，每个对象指示参与手势的所有手指的位置。

rotation

一个浮点数，指示手势开始时旋转的程度。

一个浮点数，指示手势执行的速度。

当玩家在 UI 元素上使用两个手指执行旋转手势时触发。

这个代码示例会导致一个 `Frame`（或其他 `GuiObject`）在触摸设备（或 Studio 的模拟器）上执行滑动手势时跳动。
水平滑动将改变 `Class.GuiObject.BackgroundColor3` 的色调，而垂直滑动将改变饱和度。

此事件在玩家使用触摸设备在 UI 元素上进行滑动手势时触发。它会带有手势的方向（上、下、左或右）和参与手势的触摸点数量。滑动手势通常用于在移动 UI 中切换选项卡。

GuiObject.TouchSwipe

swipeDirection

一个 `Enum.SwipeDirection`，指示滑动手势的方向（上、下、左或右）。

numberOfTouches

参与手势的触点数量（通常为 1）。

当玩家在 UI 元素上执行滑动手势时触发。

此代码示例将在触摸设备上点击时切换 UI 元素（如 `Frame`）的 `Class.GuiObject.BackgroundTransparency`。

此事件在玩家使用触摸设备在 UI 元素上进行轻击手势时触发。轻击是快速的单次触摸，没有任何移动（较长的按压将触发 `Class.GuiObject.TouchLongPress`，在触摸过程中移动将触发 `Class.GuiObject.TouchPan` 和/或 `Class.GuiObject.TouchSwipe`）。它带有一个表，包含描述手势中涉及的手指相对位置的 `Datatype.Vector2` 对象。

GuiObject.TouchTap

一个描述参与手势的手指 **相对** 位置的 `Datatype.Vector2` 数组。

当玩家在 UI 元素上执行点击手势时触发。

此代码示例演示了 TweenPosition 的更复杂用法，通过定义回调函数来检测 tween 完成/取消。它还会打印 tween 是否会播放。

在指定时间平滑地将 GUI 移动到新的 `Datatype.UDim2` 位置，使用指定的 `Enum.EasingDirection` 和 `Enum.EasingStyle`。

此函数将返回 Tween 是否会播放。如果另一个 Tween 正在作用于 `Class.GuiObject` 并且覆盖参数为 `false`，则不会播放。

另请参见 `Class.GuiObject:TweenSize()` 和 `Class.GuiObject:TweenSizeAndPosition()`。

GuiObject:TweenPosition

endPosition

easingDirection

将 GUI 弹到 _endPosition_ 的方向。

easingStyle

在 _endPosition_ 中放松 GUI 的样式。

time

Tween 应该花费的时间（秒数）。

override

是否可以覆盖正在进行的 Tween。

callback

在 Tween 完成时执行的回调函数。

平滑地将 GUI 移动到新的 `Datatype.UDim2`。

此代码示例演示了 `Class.GuiObject:TweenSize()`
函数的用法。它在父级的 `Class.GuiObject.Size`
属性上启动动画，目标为 `UDim2.new(0.5, 0, 0.5, 0)`，即 `GuiObject` 的
父级大小在两个轴上的一半。

此外，它演示了如何使用回调参数来检测
tween 何时停止（无论是被另一个 tween 取消还是完成）。

在指定时间平滑地将 `Class.GuiObject` 的大小调整为新的 `Datatype.UDim2`，并使用指定的 `Enum.EasingDirection` 和 `Enum.EasingStyle`。

此函数将返回 Tween 是否会播放。通常，这将始终返回 `true`，但如果另一个 Tween 正在激活且覆盖设置为 `false`，则会返回 `false`。

另请参见 `Class.GuiObject:TweenSize()` 和 `Class.GuiObject:TweenSizeAndPosition()`。

GuiObject:TweenSize

endSize

平滑地将 `Class.GuiObject` 的大小调整为新的 `Datatype.UDim2`。

下面的示例将把 `Class.Frame` 动画到父级的左上角
大小并缩小到 0。

在指定时间平滑地将 GUI 调整为新的 `Datatype.UDim2` 大小和位置，使用指定的 `Enum.EasingDirection` 和 `Enum.EasingStyle`。

此函数将返回 Tween 是否会播放。通常，这将始终返回 `true`，但如果另一个 Tween 正在激活且覆盖设置为 `false`，则会返回 `false`。

另请参见 `Class.GuiObject:TweenSize()` 和 `Class.GuiObject:TweenSizeAndPosition()`。

GuiObject:TweenSizeAndPosition

将 GUI 弹到 _endSize_ 和 _endPosition_ 的方向。

在 _endSize_ 和 _endPosition_ 中放松 GUI 的样式。

平滑地将 GUI 移动到新的大小和位置。

GuiObject

此代码示例演示了 Active 属性作为 Activated 事件的去抖动的用法。

此属性确定 `Class.GuiObject` 是否会将输入传递到 3D 空间，
例如使用 `Class.ClickDetector` 类的底层模型，如
`Class.DragDetector`。

对于 `Class.GuiButton` 对象（`Class.ImageButton` 和
`Class.TextButton`），此属性确定 `Class.GuiButton.Activated|Activated`
是否被触发（`Class.GuiButton.AutoButtonColor|AutoButtonColor` 仍然会对它们起作用）。事件 `Class.GuiObject.InputBegan|InputBegan`、
`Class.GuiObject.InputChanged|InputChanged` 和
`Class.GuiObject.InputEnded|InputEnded` 的功能是正常的，无论此属性的值如何。

GuiObject.Active

此代码示例将 UI 元素移动到父元素的不同侧面。
它从左上角开始，到右下角结束。将其粘贴到
ScreenGui 内的 Frame 中的 LocalScript 中。


此属性确定 `Class.GuiObject` 的原点，相对于其绝对大小。原点确定元素
被定位的起始点（通过 `Class.GuiObject.Position`）以及合成的 `Class.GuiObject.Size` 如何扩展。

有关插图和详细信息，请参见 [这里](/ui/position-and-size#anchorpoint)。

GuiObject.AnchorPoint

确定 `Class.GuiObject` 的原点，相对于其绝对大小。

以下脚本创建一个自动调整大小的父框架，带有一个 `UIListLayout`，
然后它插入多个自动调整大小的 `TextLabel` 对象。注意父 `UIListLayout`
会自动调整大小以适应其子内容，而标签会自动调整大小以适应其文本内容。
此脚本可以作为 `ScreenGui` 的子级。

此属性用于自动根据其子元素的大小调整父级 UI 对象的大小。您可以使用此属性在编辑或运行时动态添加文本
和其他内容到 UI 对象，并且大小将根据内容进行调整。

当 `Class.GuiObject.AutomaticSize|AutomaticSize` 设置为除 `Enum.AutomaticSize|None` 以外的 `Enum.AutomaticSize` 值时，
此 UI 对象可能会根据其子内容进行调整。

有关如何使用此属性及其工作原理的更多信息，请参见 [这里](/ui/size-modifiers#automatic-sizing)。

GuiObject.AutomaticSize

确定是否根据子内容调整大小。

确定 `Class.GuiObject` 背景的颜色。

GuiObject.BackgroundColor

这段代码示例使得父框架循环遍历所有颜色的
彩虹，使用 Color3.fromHSV。

此属性确定 `Class.GuiObject` 背景的颜色（填充颜色）。如果您的元素包含文本，
例如 `Class.TextBox`、`Class.TextButton` 或 `Class.TextLabel`，请确保背景的颜色与文本的颜色形成对比。

另一个确定背景视觉属性的属性是 `Class.GuiObject.BackgroundTransparency`；如果此属性设置为 `1`，则
背景和边框将不会被渲染。

另请参见 `Class.GuiObject.BorderColor3|BorderColor3`。

GuiObject.BackgroundColor3

此属性确定 `Class.GuiObject` 背景和边框的透明度。然而，它不确定文本的透明度，如果 GUI 是 `Class.TextBox`、
`Class.TextButton` 或 `Class.TextLabel`；文本透明度由 `Class.TextBox.TextTransparency`、`Class.TextButton.TextTransparency` 和
`Class.TextLabel.TextTransparency`分别决定。

如果此属性设置为 `1`，则背景和边框都不会渲染，GUI 背景将完全透明。

GuiObject.BackgroundTransparency

确定 `Class.GuiObject` 背景和边框的透明度。

确定 `Class.GuiObject` 边框的颜色。

GuiObject.BorderColor

这段代码示例使得当用户将鼠标悬停在元素上时，父级 GuiObject 的边框高亮显示。

确定 `Class.GuiObject` 矩形边框的颜色（也称为轮廓颜色）。这与对象的
`Class.GuiObject.BackgroundColor3` 是分开的。如果其 `Class.GuiObject.BorderSizePixel` 属性设置为 `0`，您将看不到
对象的边框。

请注意，`Class.UIStroke` 组件允许更高级的边框效果。

GuiObject.BorderColor3

此属性确定 `Class.GuiObject` 边框根据其维度的布局方式，使用同名的枚举 `Enum.BorderMode`。

请注意，`Class.UIStroke` 可以覆盖此属性并允许更高级的边框效果。

GuiObject.BorderMode

确定 `Class.GuiObject` 边框相对于其维度的布局方式。

此属性确定 `Class.GuiObject` 边框的宽度，以像素为单位。将其设置为 0 会完全禁用边框。

请注意，`Class.UIStroke` 可以覆盖此属性并允许更高级的边框效果。

GuiObject.BorderSizePixel

确定 `Class.GuiObject` 边框的像素宽度。

此属性确定 `Class.GuiObject` 是否会裁剪（使其不可见）任何子 GUI 元素的部分，这些部分原本会渲染在矩形的边界之外。

请注意，`Class.GuiObject.Rotation|Rotation` 对此属性不支持。如果此或任何祖先 GUI 的 `Class.GuiObject.Rotation|Rotation` 非零，则
此属性将被 **忽略**，并且子 GUI 元素将根据此属性的值进行渲染。

GuiObject.ClipsDescendants

确定父级 GUI 元素范围外的子 `Class.GuiObject|GuiObjects` 是否应该被渲染。

这表示 `Class.GuiObject`（及其子代）是否可以在屏幕上被拖动。

GuiObject.Draggable

确定 `Class.GuiObject`（及其子代）是否可以在屏幕上被拖动。

当玩家的手指出在 `Class.GuiObject` 上被触摸并按住时，`Class.GuiObject.GuiState|GuiState` 将被设置为 `Enum.GuiState.Press|Press`。
类似地，当玩家的手指从 `Class.GuiObject` 上释放时，`Class.GuiObject.GuiState|GuiState` 将被设置为 `Enum.GuiState.Idle|Idle`，
并且当 `Class.GuiObject.Interactable|Interactable` 在 `Class.GuiObject` 上关闭时，`Class.GuiState` 将被设置为
`Enum.GuiState.NonInteractable|NonInteractable`。

GuiObject.GuiState

确定玩家的鼠标是否正在 `Class.GuiObject` 上被按下。

GuiObject.InputSink

确定 `Class.GuiButton` 是否可以交互，或 `Class.GuiObject` 的 `Enum.GuiState|GuiState` 是否正在更改。

在 `Class.GuiButton` 上：

- 当 `Class.GuiButton` 上的 `Class.GuiObject.Interactable|Interactable` 设置为 `false` 时，`Class.GuiButton` 将不再能够被按压或点击，`Class.GuiObject.GuiState|GuiState` 将始终设置为 `Enum.GuiState.NonInteractable|NonInteractable`。
- 当 `Class.GuiButton` 上的 `Class.GuiObject.Interactable|Interactable` 设置为 `true` 时，`Class.GuiButton` 将正常行为，`Class.GuiObject.GuiState|GuiState` 将正常表现。

在 `Class.GuiObject` 上：

- 当 `Class.GuiButton` 上的 `Class.GuiObject.Interactable|Interactable` 设置为 `false` 时，`Class.GuiObject.GuiState|GuiState` 将始终设置为 `Enum.GuiState.NonInteractable|NonInteractable`。
- 当 `Class.GuiButton` 上的 `Class.GuiObject.Interactable|Interactable` 设置为 `true` 时，`Class.GuiObject.GuiState|GuiState` 将再次正常表现。

GuiObject.Interactable

确定 `Class.GuiButton` 是否可以交互，或 `Class.GuiObject` 的 `Enum.GuiState|GuiState` 是否正在更改。

该属性控制 `Class.GuiObject` 在使用 `Class.UIGridStyleLayout`（例如 `Class.UIListLayout` 或 `Class.UIPageLayout`）且 `Class.UIGridStyleLayout.SortOrder|SortOrder` 设置为 `Enum.SortOrder.LayoutOrder` 时的排序顺序。如果对象没有兄弟 UI 布局结构，则此属性没有功能。

`Class.GuiObject|GuiObjects` 按升序排序，较低的值优先于较高的值。具有相等值的对象根据它们被添加的顺序排队。

如果您不确定将来是否需要在两个现有元素之间添加元素，使用 `100` 的倍数（`0`、`100`、`200` 等）是一个好习惯。这确保有一个较大的布局顺序值间隔，可用于在其他元素之间排序的元素。

另请参见 `Class.GuiObject.ZIndex|ZIndex`，该值确定对象的 **渲染** 顺序而不是排序顺序。

GuiObject.LayoutOrder

控制 `Class.GuiObject` 在与 `Class.UIGridStyleLayout` 一起使用时的排序顺序。

此示例演示了如何在不必手动连接每个网格元素的 `Class.GuiObject.NextSelectionUp`、`Class.GuiObject.NextSelectionDown`、`GuiObject|NextSelectionRight` 和 `Class.GuiObject.NextSelectionLeft` 属性的情况下，通过 `GuiObject|GUI` 元素的网格启用手柄导航。

请注意，此代码示例假设您的 `UIGridLayout` 根据 `Class.UIGridLayout.SortOrder|name` 排序，其中元素按照连续的数字顺序命名。

代码依赖此设置为所有与 UIGridLayout 同级的 `GuiObjects` 设置 NextSelection 属性。在我们的示例中，UIGridLayoutObject 和网格中的 GUI 元素都是名为 _"Container"_ 的 `Frame` 的子级。代码 `Class.Instance:GetChildren()|获取子级` _"Container"_ 的子级并遍历每个子级。非 GuiObjects 的子级将被忽略。对于每个 GUI 元素，代码尝试使用以下逻辑分配 NextSelection 属性：

1. 从 1 开始，所有 GUI 元素的名称与它们在网格中的位置匹配
2. 左：左边的项目总是比当前元素的编号少 1
3. 右：右边的项目总是比当前元素的编号多 1
4. 上：上方的项目总是当前元素的上方一行中 GUI 的数量减少 1
5. 下：下方的项目总是当前元素的下方一行中 GUI 的数量多于 1。这一逻辑还允许行首和行尾的 GUI 元素（不包括第一个和最后一个元素）包裹到下一行和上一行。如果左、右、上或下的元素不存在，NextSelection 将保持为 nil，朝该方向移动手柄选择器将不会改变所选的 GUI。

此示例还包含代码，使用键盘的箭头键（上、下、左、右）测试网格，而不是手柄，以防您没有手柄进行测试。此部分代码最初通过将名为 _"1"_ 的元素分配给 `Class.GuiService.SelectedObject` 属性来选择该元素。


此属性设置当用户将 [手柄](/input/gamepad) 选择器向下移动时所选的 `Class.GuiObject`。如果此属性为空，向下移动游戏手柄不会更改所选的 GUI。

向下移动手柄选择器会将 `Class.GuiService.SelectedObject` 设置为此对象，除非 GUI 不是 `Class.GuiObject.Selectable|Selectable`。请注意，即使 GUI 元素不是 `Class.GuiObject.Selectable|Selectable`，此属性也可以设置为 GUI 元素，因此您应确保 GUI 的可选择性属性值与您的预期行为相匹配。

另请参见 `Class.GuiObject.NextSelectionUp|NextSelectionUp`、`Class.GuiObject.NextSelectionLeft|NextSelectionLeft` 和 `Class.GuiObject.NextSelectionRight|NextSelectionRight`。

GuiObject.NextSelectionDown

设置当手柄选择器向下移动时将被选择的 `Class.GuiObject`。

此属性设置当用户将 [手柄](/input/gamepad) 选择器向左移动时所选的 `Class.GuiObject`。如果此属性为空，向左移动游戏手柄不会更改所选的 GUI。

向左移动手柄选择器会将 `Class.GuiService.SelectedObject` 设置为此对象，除非 GUI 不是 `Class.GuiObject.Selectable|Selectable`。请注意，即使 GUI 元素不是 `Class.GuiObject.Selectable|Selectable`，此属性也可以设置为 GUI 元素，因此您应确保 GUI 的可选择性属性值与您的预期行为相匹配。

另请参见 `Class.GuiObject.NextSelectionUp|NextSelectionUp`、`Class.GuiObject.NextSelectionDown|NextSelectionDown` 和 `Class.GuiObject.NextSelectionRight|NextSelectionRight`。

GuiObject.NextSelectionLeft

设置当手柄选择器向左移动时将被选择的 `Class.GuiObject`。

此属性设置当用户将 [手柄](/input/gamepad) 选择器向右移动时所选的 `Class.GuiObject`。如果此属性为空，向右移动游戏手柄不会更改所选的 GUI。

向右移动手柄选择器会将 `Class.GuiService.SelectedObject` 设置为此对象，除非 GUI 不是 `Class.GuiObject.Selectable|Selectable`。请注意，即使 GUI 元素不是 `Class.GuiObject.Selectable|Selectable`，此属性也可以设置为 GUI 元素，因此您应确保 GUI 的可选择性属性值与您的预期行为相匹配。

另请参见 `Class.GuiObject.NextSelectionUp|NextSelectionUp`、`Class.GuiObject.NextSelectionDown|NextSelectionDown` 和 `Class.GuiObject.NextSelectionLeft|NextSelectionLeft`。

GuiObject.NextSelectionRight

设置当手柄选择器向右移动时将被选择的 `Class.GuiObject`。

此属性设置当用户将 [手柄](/input/gamepad) 选择器向上移动时所选的 `Class.GuiObject`。如果此属性为空，向上移动游戏手柄不会更改所选的 GUI。

向上移动手柄选择器会将 `Class.GuiService.SelectedObject` 设置为此对象，除非 GUI 不是 `Class.GuiObject.Selectable|Selectable`。请注意，即使 GUI 元素不是 `Class.GuiObject.Selectable|Selectable`，此属性也可以设置为 GUI 元素，因此您应确保 GUI 的可选择性属性值与您的预期行为相匹配。

另请参见 `Class.GuiObject.NextSelectionDown|NextSelectionDown`、`Class.GuiObject.NextSelectionLeft|NextSelectionLeft` 和 `Class.GuiObject.NextSelectionRight|NextSelectionRight`。

GuiObject.NextSelectionUp

设置当手柄选择器向上移动时将被选择的 `Class.GuiObject`。

此属性使用 `Datatype.UDim2` 确定 `Class.GuiObject` 的像素和标量位置。位置围绕对象的 `Class.GuiObject.AnchorPoint` 中心。

标量位置是相对于父 GUI 元素的大小（如果有）。

`Datatype.UDim2` 值的像素部分与父 GUI 的大小无关。该值表示对象在像素中的位置。对象的实际像素位置可以通过 `Class.GuiBase2d.AbsolutePosition` 属性读取。

GuiObject.Position

确定 `Class.GuiObject` 的像素和标量位置。

此属性确定 `Class.GuiObject` 旋转的度数。旋转是相对于对象的 **中心**，**不是** `Class.GuiObject.AnchorPoint|AnchorPoint`，这意味着您无法更改旋转点。此外，该属性与 `Class.GuiObject.ClipsDescendants|ClipsDescendants` 不兼容。

GuiObject.Rotation

确定 `Class.GuiObject` 旋转的度数。

下面的示例提供了一个简单的演示，展示如何使用
`Class.GuiObject.Selectable` 属性来限制何时可以通过游戏手柄导航器选择一个 GUI 元素。

当一个 `TextBox` 获得焦点时，它可以被选择。然而，当一个 TextBox 失去焦点时，它就无法再被选择。

尽管这是一个简单的演示，但该属性也可以用来防止导航器选择那些存在于外观上而非功能上的 UI 元素。例如，虽然菜单屏幕上的按钮应该是可选择的，但标题图片就不应该可选择。

此属性确定在使用手柄导航 GUI 时 `Class.GuiObject` 是否可以被选择。

如果此属性为 `true`，则可以选择 GUI。选择一个 GUI 还会将 `Class.GuiService.SelectedObject` 属性设置为该对象。

当此值为 `false` 时，GUI 不能被选择。但是，当 GUI 被选择时将其设置为 `false` 并不会取消选择它，也不会更改 `Class.GuiService.SelectedObject` 属性的值。

对于该元素，`Class.GuiObject.SelectionGained` 和 `Class.GuiObject.SelectionLost` 不会触发。要取消选择 GuiObject，您必须更改 `Class.GuiService.SelectedObject` 属性。

该属性对于通过此类属性连接到多个 GUI 的 GUI 很有用，例如 `Class.GuiObject.NextSelectionUp`、`Class.GuiObject.NextSelectionDown`、`Class.GuiObject|NextSelectionRight` 或 `Class.GuiObject|NextSelectionLeft`。与其更改所有属性以使手柄无法选择 GUI，不如暂时禁用其可选择性属性以防止它被选择。然后，当您想要让手柄选择器能够选择 GUI 时，只需重新启用其可选择性属性。

GuiObject.Selectable

确定 `Class.GuiObject` 是否可以被手柄选择。

所有 2D 用户界面对象的抽象类。

/reference/engine/classes/CanvasGroup.yaml