TextUnit

概览

字段	值
Kind	Unit · 单位 Unit
Realm	common

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • [TextUnit]（26 属性）

继承成员

1 个来源 / 4 属性 / 25 函数 / 6 事件

• 来自 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

TextUnit 是可在三维场景中渲染文字内容的场景单位，用 Content 提供显示文本，并通过 FontName、FontSize、TextColor 等属性控制排版与外观。它支持 Width、Height、Scale 定义文字框尺寸，配合 LineWrap、OverflowStrategy、OverflowScrollSpeed、OverflowScrollSpacing 处理文字超出边框的情况，还能用 VerticalDirection、ReverseDirection、LineSpacing、TextSkew 调整排列与倾斜。借助 GradientColorEnable、GradientColors、GradientAngle 以及 OutlineColor、OutlineWidth，可以做出渐变与描边效果，并通过 BindSocket 依附到指定挂点。

适用场景

常用于在三维场景里显示世界空间文字，例如角色或物体上方的名称提示、场景装饰性文字与说明标签。需要让文字跟随单位移动或固定悬挂在模型挂点上时，可以设置 Position、Rotation 或将 BindSocket 指向目标挂点。

使用要点

先通过 game:CreateUnit("TextUnit", config) 或 World:CreateUnit("TextUnit", config) 创建实例，再用 Position、Rotation、Scale 确定文字在场景中的摆放，并用 Width、Height 描述文字框范围。随后写入 Content，并按需设置 FontName、FontSize、TextColor、LineSpacing、TextSkew 塑造外观，用 HoriAlign、VertAlign、LineWrap、OverflowStrategy 控制排版。若要强调文本，可开启 GradientColorEnable 并配置 GradientColors、GradientAngle，或通过 OutlineColor、OutlineWidth 添加描边，最后用 Visible 控制显隐。

注意事项

TextUnit 只能通过 game:CreateUnit 或 World:CreateUnit 创建，不存在直接构造实例的写法。FontName 需传入 Enums.TextFontType 的枚举值，HoriAlign、VertAlign、OverflowStrategy 分别对应 Enums.HorizontalAlignmentType、Enums.VerticalAlignmentType、Enums.TextOverflowStrategy，不能写成数字或省略 Enums. 前缀。选择滚动类超框策略时，应同时设置 OverflowScrollSpeed 与 OverflowScrollSpacing，显示的文本必须以 Content 赋值，否则文字框为空。

代码示例

创建 3D 文字并设置样式

-- @runtime client
local world = game:GetService("World")

local textUnit = world:CreateUnit("TextUnit", {
    Content = "欢迎来到关卡",
    Width = 6.0,
    Height = 2.0,
    FontName = Enums.TextFontType.HKXZYT_W9_GB,
    FontSize = 80,
    TextColor = Color.New(255, 230, 120, 255),
    OutlineColor = Color.New(0, 0, 0, 255),
    OutlineWidth = 2.0,
})

textUnit.GradientColorEnable = true
textUnit.GradientColors = {
    Color.New(255, 230, 120, 255),
    Color.New(255, 120, 80, 255),
}
print("文字内容:", textUnit.Content)

属性 (26)

Name	类型	默认值	说明
Position	Vector3	[0.0, 0.0, 0.0]	TextUnit 的 Position 属性，类型为 Vector3，表示该文本单元在场景中的位置，Meta 中声明的默认值为 (0, 0, 0)。该属性公开、可编辑且非只读，读取时返回当前坐标，赋值时更新该文本单元的位置。
Rotation	Quaternion	[0.0, 0.0, 0.0, 1.0]	TextUnit 的 Rotation 属性，类型为 Quaternion，表示该文本单元的旋转，Meta 中声明的默认值为 (0, 0, 0, 1)。该属性公开、可编辑且非只读，可用于读取当前旋转或在运行时重新设置旋转。
Width	Float	5.0	Width 是 TextUnit 的文字框宽度属性，类型为浮点数，用于描述承载文字的文本框宽度。
Height	Float	5.0	Height 是 TextUnit 的文字框高度属性，类型为浮点数，用于描述承载文字的文本框高度。
Scale	Vector3	[1.0, 1.0, 1.0]	TextUnit 的 Scale 属性，类型为 Vector3，表示该文本单元各轴上的缩放比例，Meta 中声明的默认值为 (1, 1, 1)。该属性公开、可编辑且非只读，支持读取当前缩放值以及按需重新设置。
Content	String	""	Content 是 TextUnit 的文字内容属性，类型为字符串，表示该文字单元所显示的文本。
FontName	TextFontType	Enums.TextFontType.HKXZYT_W9_GB	FontName 是 TextUnit 的字体名称属性，类型为 TextFontType 枚举，用于指定文字所使用的字体。
FontSize	Int	100	FontSize 是 TextUnit 的字体大小属性，类型为整数，用于控制文字显示的字号。
Visible	Bool	true	Visible 是 TextUnit 的可见性属性，类型为布尔值，用于控制该文字单元是否显示。
HoriAlign	HorizontalAlignmentType	Enums.HorizontalAlignmentType.ALIGN_LEFT	HoriAlign 是 TextUnit 的水平对齐方式属性，类型为 HorizontalAlignmentType 枚举，用于决定文字在文本框内的水平排布位置。
VertAlign	VerticalAlignmentType	Enums.VerticalAlignmentType.ALIGN_TOP	VertAlign 是 TextUnit 的垂直对齐方式属性，类型为 VerticalAlignmentType 枚举，用于决定文字在文本框内的垂直排布位置。
LineWrap	Bool	true	LineWrap 是 TextUnit 的自动换行开关属性，类型为布尔值，用于决定文字是否在文本框内自动换行。
OverflowStrategy	TextOverflowStrategy	Enums.TextOverflowStrategy.OVERFLOW_NONE	OverflowStrategy 是 TextUnit 的文本超框策略属性，类型为 TextOverflowStrategy 枚举，用于决定文字超出文本框范围时的处理方式。
OverflowScrollSpeed	Float	2.0	OverflowScrollSpeed 是 TextUnit 的跑马滚动速度属性，类型为浮点数，用于控制超框文字滚动显示的速度。
OverflowScrollSpacing	Float	0	OverflowScrollSpacing 是 TextUnit 的跑马滚动间距属性，类型为浮点数，用于设置滚动文本重复出现之间的间隔。
VerticalDirection	Bool	false	VerticalDirection 是 TextUnit 的纵向显示开关属性，类型为布尔值，用于决定文字是否按纵向排列。
ReverseDirection	Bool	false	ReverseDirection 是 TextUnit 的纵向排布方向属性，类型为布尔值，用于设定纵向显示时文字是否从右到左排列。
LineSpacing	Float	0.0	LineSpacing 是 TextUnit 的行间距属性，类型为浮点数，用于设置多行文字之间的间距。
TextSkew	Float	0.0	TextSkew 是 TextUnit 的文本倾斜角度属性，类型为浮点数，用于设置文字的倾斜程度。
GradientColorEnable	Bool	false	GradientColorEnable 是 TextUnit 的渐变色开关属性，类型为布尔值，用于决定文字是否启用渐变颜色。
TextColor	Color	Color.New(255, 255, 255, 255)	TextColor 是 TextUnit 的文本颜色属性，类型为 Color，用于设置文字本身的颜色。
GradientColors	Array<Color>	-	GradientColors 是 TextUnit 的文本颜色渐变列表属性，类型为数组，用于提供渐变所用的颜色序列。
GradientAngle	Float	0.0	GradientAngle 是 TextUnit 的文本颜色渐变角度属性，类型为浮点数，用于设置渐变色在文字上的方向角度。
OutlineColor	Color	Color.New(0, 0, 0, 255)	OutlineColor 是 TextUnit 的描边颜色属性，类型为 Color，用于指定文字描边的颜色。
OutlineWidth	Float	0.0	OutlineWidth 是 TextUnit 的描边宽度属性，类型为浮点数，用于控制文字描边的粗细。
BindSocket	String	""	BindSocket 是 TextUnit 的绑定挂点属性，类型为字符串，用于记录文字单元所要绑定到的挂点名称。

关联类型

• Unit
• Color
• HorizontalAlignmentType
• Quaternion
• TextFontType
• TextOverflowStrategy
• Vector3
• VerticalAlignmentType