Galacean Logo
文档
API 参考
示例
游乐场
2D

文字渲染器

TextRenderer 组件用于在 3D/2D 场景中显示文字，支持动态文本、自定义字体、多行显示、对齐方式等特性。

编辑器使用

添加文本组件

  1. 在场景中选择目标实体。
  2. 通过实体属性面板添加 TextRenderer 组件。
  3. 配置组件参数以定义文本样式。
添加TextRenderer组件操作示意图

参数说明

选中带有 TextRenderer 组件的实体，在右侧 Inspector 面板中配置以下属性：

TextRenderer组件属性面板示意图
属性说明
Text显示的文本内容（支持多行输入）
Color文本颜色（RGBA格式）
FontSize字体大小（单位：像素）
Font自定义字体资源（默认使用系统字体）
Width文本设计宽度（影响换行和布局，单位：场景单位）
Height文本设计高度（影响截断和布局，单位：场景单位）
LineSpacing行间距（单位：像素）
FontStyle字体样式：None（默认）/ Bold（加粗）/ Italic（斜体）
HorizontalAlignment水平对齐：Left（左）/ Center（中）/ Right（右）
VerticalAlignment垂直对齐：Top（顶）/ Center（中）/ Bottom（底）
EnableWrapping是否启用自动换行（需设置有效Width）
OverflowMode溢出处理：Overflow（显示溢出内容）/ Truncate（截断超出部分）
Mask Interaction遮罩交互模式（与SpriteMask配合使用）
Mask Layer遮罩层级（默认Everything匹配所有层）
Priority渲染优先级（值越小越优先渲染）
Width 和 Height 属性仅用于定义文本的布局范围（如换行和对齐），并非实际渲染尺寸。如需获取文本在三维空间中的真实包围盒尺寸，请通过 TextRenderer.bounds 属性读取。

基础操作示例

设置文本内容

  1. 在 Text 属性字段输入目标文本。
  2. 支持多行文本直接换行输入。
设置文本内容示意图

使用自定义字体

  1. 准备字体文件（支持 .ttf、.otf、.woff 格式）。
  2. 将字体文件拖拽至编辑器资源面板。
  3. 在 Font 属性中选择已上传的字体。
自定义字体设置示意图

脚本开发指南

基础用法

import { TextRenderer, Font, Color } from "@galacean/engine";
 
// 创建文本实体并添加组件
const textEntity = rootEntity.createChild("text");
const textRenderer = textEntity.addComponent(TextRenderer);
 
// 设置基础属性
textRenderer.text = "Galacean Text Rendering";  // 文本内容
textRenderer.fontSize = 24;                   // 字体大小（像素）
textRenderer.color = new Color(1, 0, 0, 1);    // 红色文本

高级功能

1. 自定义字体加载

// 方式1：使用系统字体
textRenderer.font = Font.createFromOS(engine, "Arial");
 
// 方式2：加载外部字体文件
engine.resourceManager.load({ url: "fonts/Avelia.otf" }).then((font) => {
  textRenderer.font = font;
});

2. 布局与换行

// 设置包围盒尺寸（单位：场景单位）
textRenderer.width = 5;   // 控制自动换行宽度
textRenderer.height = 3;  // 影响截断高度
 
// 启用自动换行
textRenderer.enableWrapping = true;
 
// 设置行间距
textRenderer.lineSpacing = 0.5;

3. 溢出与截断

// 溢出模式设置
textRenderer.overflowMode = OverflowMode.Truncate; // 或 OverflowMode.Overflow
 
// 对齐方式（需结合宽高使用）
textRenderer.horizontalAlignment = TextHorizontalAlignment.Center;
textRenderer.verticalAlignment = TextVerticalAlignment.Top;

4. 字体样式组合

// 同时应用加粗和斜体
textRenderer.fontStyle = FontStyle.Bold | FontStyle.Italic;

注意事项

  1. 宽高为0的陷阱：若启用换行（enableWrapping=true）但未设置有效宽高，文本将不渲染。
  2. 字体兼容性：部分复杂字体（如含异体字）可能存在渲染异常，建议测试验证。
  3. 性能优化：频繁更新文本内容可能影响性能，建议对静态文本启用合批。

API 参考

类/枚举关键属性/值说明
TextRenderertext, font, fontSize文本渲染器主类
TextHorizontalAlignmentLeft, Center, Right水平对齐模式
TextVerticalAlignmentTop, Center, Bottom垂直对齐模式
FontStyleNone, Bold, Italic字体样式组合

这篇文档对您有帮助吗？