SurfaceGui

概览

字段	值
Kind	Unit · 单位 Unit
Realm	common

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • SpaceUnit（2 属性 / 9 函数）
    • BasePart（24 属性 / 9 函数）
      • [SurfaceGui]（8 属性）

继承成员

3 个来源 / 30 属性 / 43 函数 / 6 事件

• 来自 BasePart（24 属性 / 9 函数）
  • 属性：CFrame、PivotOffset、Position、Rotation、Scale、Size、ModelAlpha、ModelVisible、CastShadow、ModelColor1、ModelColor2、ModelColor3、ModelColor4、SkinId、UseCustomAppearance、CustomAppearanceId、OcclusionType、AssemblyRootPriority、AssemblyLinearVelocity、AssemblyAngularVelocity、AssemblyMass、AssemblyCenterOfMass、Persistent、IsStaticOptimization
  • 函数：IsNetworkOwnerSide、GetNetworkOwner、SetNetworkOwner、GetNetworkOwnershipAuto、SetNetworkOwnershipAuto、IsWeldConstraintRoot、IsWeldConstraintChild、GetConnectedUnits、SyncRenderToPhysics
• 来自 SpaceUnit（2 属性 / 9 函数）
  • 属性：Tags、EcaPath
  • 函数：HasTag、AddTag、RemoveTag、GetPivot、PivotTo、ApplyPivotDelta、TranslateBy、IsTopLevel、FindTopLevel
• 来自 Unit（4 属性 / 25 函数 / 6 事件）
  • 属性：AssetId、Name、Desc、Parent
  • 函数：ClearAllChildren、GetChildren、GetDescendants、IsAncestorOf、IsDescendantOf、FindFirstAncestor、FindFirstAncestorWhichIsA、FindFirstAncestorOfClass、FindFirstChild、FindFirstChildWhichIsA、FindFirstChildOfClass、HasChildren、GetChildCount、GetChildAtIndex、SetAttribute、GetAttribute、GetAllProps、Clone、IsA、Destroy、GetPropertyChangedSignal、GetAttributeChangedSignal、FindFromPath、GetFullPath、GetDebugId
  • 事件：ChildAdded、ChildRemoved、DescendantAdded、DescendantRemoving、AncestryChanged、Destroying

贴面UI容器是一种可挂载到场景中的界面承载单位，负责把二维画布内容呈现在三维空间里。它通过尺寸模式、画布尺寸与每单位像素密度等属性控制排版基准，并能调整受光照影响程度、亮度与最大渲染距离来适配不同观察条件。

适用场景

常用于需要在场景表面展示信息面板、告示牌或可交互界面的场合，例如把界面贴到某个单位上随其移动。

使用要点

先通过 game:CreateUnit("SurfaceGui", config) 或 World:CreateUnit("SurfaceGui", config) 创建实例，并设置 Parent 挂到目标单位上；随后按需配置 SizingMode、CanvasSize、PixelsPerWorldUnit 与 WorldScale 来决定画布尺寸与缩放，再通过 Enabled 控制整体显示，并结合 LightInfluence、Brightness、MaxDistance 调整观感与可见范围。

注意事项

该类型只能经由 game:CreateUnit 或 World:CreateUnit 创建，不能使用构造式直接生成实例。属性修改会影响整体呈现，建议先确定尺寸模式再调整画布与缩放参数。当界面不需要显示时应通过 Enabled 关闭，而不是销毁实例后再重建。

代码示例

创建 SurfaceGui 实例

-- @runtime client
local World = game:GetService('World')
local surfaceGui = World:CreateUnit('SurfaceGui', {})
if surfaceGui == nil then return end
print('SurfaceGui 已创建:', surfaceGui.Name)

属性 (8)

Name	类型	默认值	说明
Enabled	Bool	true	总渲染开关。关闭后画布不渲染，子节点与内部结构不受影响。
SizingMode	SurfaceGuiSizingMode	Enums.SurfaceGuiSizingMode.FixedSize	画布尺寸模式，使用 Enums.SurfaceGuiSizingMode.FixedSize 按固定逻辑尺寸布局，或使用 Enums.SurfaceGuiSizingMode.PixelsPerWorldUnit 按每世界单位像素密度布局。
CanvasSize	Vector2	[700.0, 700.0]	画布逻辑尺寸（像素），需非零。仅 FixedSize 模式驱动布局。
PixelsPerWorldUnit	Vector2	[100.0, 100.0]	每轴像素密度，分量需大于 0。仅 PixelsPerWorldUnit 模式生效。
WorldScale	Vector3	[1.0, 1.0, 1.0]	画布在世界中的尺寸（各轴缩放）。
LightInfluence	Float	1.0	受场景光照影响程度，取值范围 0.0～1.0，默认 1.0。
Brightness	Float	1.0	亮度，取值范围 0.0～10.0，默认 1.0。
MaxDistance	Float	0	最大渲染距离，单位为世界单位；超出该距离则剔除不渲染，0 表示不限制。

关联类型

• BasePart
• SurfaceGuiSizingMode
• Vector2
• Vector3