roblox-user-interfaces

roblox-user-interfaces

选择适合显示表面的 GUI 容器，然后使用布局和约束来适配不同屏幕尺寸。对于 ScreenGui 内的粒子，请使用 2D UI 对象；ParticleEmitter 不会在其中渲染。

主要来源：

• https://create.roblox.com/docs/en-us/ui
• https://create.roblox.com/docs/en-us/ui/on-screen-containers
• https://create.roblox.com/docs/en-us/ui/in-experience-containers
• 关于框架、标签、按钮、文本输入、位置和大小、列表与弹性布局、网格与表格布局、外观修改器、样式设置、接近提示、ui-drag-detectors 等内容的子指南。
• roblox-animation skill（用于这些对象上的动态效果）
• 引擎类：ScreenGui、SurfaceGui、BillboardGui、GuiObject 及其所有派生类、各种 UILayout 和 UIConstraint 类、CanvasGroup、ViewportFrame 等。

对于 UI 动态效果，请阅读 roblox-animation。对于 3D 世界中的效果，请阅读 roblox-vfx。

选择 GUI 容器

ScreenGui（屏幕叠加层）

• 将其设为 StarterGui 的子对象，以便自动克隆到每位玩家的 PlayerGui 中。
• 使用 .Enabled（或父子对象操作）控制可见性。
• 使用 .DisplayOrder 对多个界面分层（值越大，层级越靠上）。
• .ScreenInsets = CoreUISafeInsets（默认值，会避开顶栏和设备刘海区域）、DeviceSafeInsets、TopbarSafeInsets 或 None。
• .ResetOnSpawn 的行为取决于它与 StarterGui 的直接祖先关系。
• 所有交互和逻辑都仅在客户端运行（LocalScripts 或客户端 ModuleScripts）。

SurfaceGui（部件表面上的世界空间界面）

• 可以直接设为 BasePart 的子对象（此时使用 .Face），也可以放在 StarterGui/PlayerGui 中，再通过 .Adornee 指定一个部件。
• 只有当 SurfaceGui 最终位于查看玩家的 PlayerGui 下，且部件的 CanQuery 为 true 时，交互按钮才能接收输入。
• .AlwaysOnTop、.Brightness（0-1000）、.LightInfluence（0-1）、.MaxDistance、.ZOffset（用于对同一表面上的多个界面排序）。
• 非常适合用于终端、车辆仪表盘、键盘和标牌。

BillboardGui（世界空间界面，始终面向摄像机）

• 属性与 SurfaceGui 类似，另有 .StudsOffset（相对于摄像机朝向偏移）和 .StudsOffsetWorldSpace（沿世界坐标轴偏移）。大小以 studs 表示，通过 Size 的缩放分量指定（例如，UDim2.fromScale(4, 2) 会创建一个 4×2 studs 的广告牌，其屏幕尺寸会随距离变化）。
• 非常适合用于名牌、悬浮生命值条、任务标记、伤害数字，以及显示在角色或物体上方的上下文提示。
• 交互元素需要遵循与 SurfaceGui 相同的 PlayerGui 祖先关系规则，并且需要设置 BillboardGui.Active = true（按钮本身的 Active 也需启用）。

其他／特殊用途：

• CoreGui（由 Roblox 管理；使用 StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.XXX, false) 控制）。
• ViewportFrame（在 2D 矩形中嵌入 3D 摄像机和世界；非常适合用于物品预览和静态 3D 模型；真实的 ParticleEmitter、Beam 和 Trail 效果不会在其中渲染）。

布局对象和修饰器

绝大多数现代 Roblox UI 都由以下对象构建：

• Frame 或 CanvasGroup 用作容器（ClipsDescendants、AutomaticSize = X/Y/XY、Background* 属性、Rotation）。
• TextLabel / ImageLabel 用于显示。
• TextButton / ImageButton 用于交互（Activated 是首选的跨平台事件）。
• TextBox 用于输入。
• ScrollingFrame（CanvasSize、AutomaticCanvasSize、ScrollBar* 属性）。
• ViewportFrame 用于 3D 内容。

布局对象（真正强大的功能）：

• UIListLayout / UIGridLayout / UIPageLayout：自动排列、FillDirection、Horizontal/VerticalAlignment、Padding、SortOrder。UIListLayout 还支持弹性布局功能（HorizontalFlex、VerticalFlex、ItemLineAlignment、Wraps），并可搭配各对象上的 UIFlexItem 覆盖弹性布局设置。
• 这些对象搭配父对象上的 AutomaticSize，可构建出真正自适应的 UI，使其能随内容或不同语言而扩展或收缩。

外观和约束修饰器（用这些替代旧式技巧）：

• UIStroke（ApplyStrokeMode、Color、Enabled、LineJoinMode、Thickness、Transparency、ZIndex）。适用于任何 GuiObject 的现代边框。
• UIGradient（Color 是一个 ColorSequence；Transparency 是一个 NumberSequence）。Type 可选择 Linear、Radial、Conical 或 Elliptical（Elliptical 属于 Beta 功能“Upgraded UIGradients”的一部分）；Scale 控制范围，TileMode 可选择 Clamp、Repeat 或 Mirror。径向渐变会忽略 Rotation。参见 https://create.roblox.com/docs/ui/appearance-modifiers#gradient。
• UICorner（CornerRadius；用于圆角矩形，比 9-slice 技巧好得多）。
• UIPadding、UISizeConstraint、UIAspectRatioConstraint、UIScale、UIFlexItem。

定位基础知识（高质量 UI 必不可少）：

• 几乎所有情况都优先使用 Scale（0-1），而不是 Offset（像素）。
• AnchorPoint 控制对象的枢轴点（0,0 = 左上角；0.5,0.5 = 中心；在对 Position 或 Size 使用补间动画前设置）。
• ZIndex 用于在同一容器内分层；DisplayOrder 用于对整个 ScreenGui 分层。
• 对于世界空间：BillboardGui 上使用 StudsOffset；Surface 和 Billboard 上使用 ZOffset + AlwaysOnTop。

请参阅 references/gui-containers.md，了解详尽的属性表、常见层级结构和自适应布局方案（其中涵盖构建模块和布局）。

交互模型

• 按钮：优先使用 .Activated（在释放时触发，适用于鼠标、触摸和游戏手柄）。
• MouseButton1Click / MouseButton1Down 等事件仍然存在，但不太适合跨平台使用。
• TextBox 提供 FocusLost、Focused、ReturnPressedFromOnScreenKeyboard 等事件。
• 新功能：UI 拖拽检测器（2D）和 3D 拖拽检测器，可用于滑块、旋钮、可拖拽物体、门等。
• ProximityPrompt 用于 3D 世界中“按 E 交互”风格的提示（它与 UI 相互独立，但通常会搭配使用）。

使用 StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, false) 等方式控制 Roblox 的默认 UI。提供自定义输入时，可通过 GuiService.TouchControlsEnabled = false 隐藏虚拟控件。

UI 中的粒子效果

直接使用的 ParticleEmitter 位于 3D 世界中（以 Part 或 Attachment 为父对象）。对于 2D UI，有几个出色的选项：

1. 脚本控制的 2D 粒子池。使用由 ImageLabel 组成的表（或一个包含许多小型子项的 CanvasGroup）。使用 TweenService 为 Position（按比例或局部坐标）、Size、Transparency、Rotation 和 Color 创建补间动画。对实例进行池化和回收。非常适合制作彩纸、火花、飘动的数字、奖励爆发效果和命中标记。
2. 嵌入 ViewportFrame。在 ScreenGui 中放置一个 ViewportFrame。在其中放入 3D 零件、网格、摄像机和小型装配。真正的 ParticleEmitter、Beam、Trail 和 Light 对象不会在 ViewportFrame 中渲染。可以为 ViewportFrame 自身的属性或其中的摄像机／零件创建补间动画。许多 3D 技能预览或发光物品查看器都是这样制作的。
3. CanvasGroup + 快速补间动画。用于组的“弹出”、闪烁或溶解效果。
4. UIStroke + UIGradient 动画。用于能量边框、蓄力效果和动态线条。
5. Text + MaxVisibleGraphemes，搭配小型图像“粒子”，用于制作精美的对话或标题序列。

性能现状：透明图层过度绘制和填充率是移动设备上的主要瓶颈。控制同时显示的 UI“粒子”数量，积极复用实例，使用较小的纹理，并在低画质下进行测试。

请参阅专门的 references/particles-in-ui.md，了解具体的粒子池实现、ViewportFrame 设置模式、与 3D 标记的集成以及性能防护措施。

响应式布局

• 使用规范的分辨率／宽高比（例如 1920x1080 或常见的移动设备分辨率）进行设计，但所有内容都使用比例和约束来实现。
• 对于行／列布局，使用 UIListLayout + AutomaticSize + Padding，而不是手动计算位置。
• 对于不同的设备类别，可以使用多个 ScreenGui 变体，并通过 UserInputService 切换；也可以使用一个布局，通过布局对象和尺寸修饰符实现自适应。
• 通用样式（Style Editor + StyleRules）相当于 Roblox 中的 CSS。可用它在多个 UI 元素间统一颜色、描边、字体，甚至过渡效果。

UI 检查清单

新建 ScreenGui：

• 为内容设置正确的 ScreenInsets（交互内容 → CoreUISafeInsets）。
• 如果需要显示在其他图层上方／下方，则设置 DisplayOrder。
• 明确并有意设置 ResetOnSpawn 行为。
• 所有子项都使用比例、AnchorPoint 和约束。

新建交互元素：

• 按钮使用 Activated。
• 如果位于世界空间，则输入操作的层级规则必须满足要求（PlayerGui），且零件的 CanQuery 为 true。
• 通过悬停／按下状态提供视觉反馈（使用补间动画，或更改按钮自身或同级高亮元素的状态）。

UI 中的粒子／VFX：

• 对实例进行池化／回收。
• 限制同时显示的数量。
• 在最低画质下进行测试。
• 将其与有意义的游戏时刻关联（通过动画技能中的标记或 UI 事件）。

如需查阅每个属性的权威列表和最新新增内容（新布局、拖动检测器、样式功能），请参阅 Engine API 参考：https://create.roblox.com/docs/reference/engine。

参考索引

• gui-containers.md：选择屏幕空间或世界空间容器，并配置布局行为。
• particles-in-ui.md：创建 2D 粒子效果，或将 UI 与 3D 预览结合使用。