【前端接口】GUI:Text_Create：文本控件的创建与动态刷新

实战应用：用在哪里

GUI:Text_Create 是前端用得最多的控件接口：伤害飘字、状态提示、窗口标题、聊天气泡里的文字全由它生成。七参数签名把位置、字号、颜色、内容一次配齐，创建返回控件对象后还能持续改内容。

创建与刷新

---创建文本 Parent:父节点 ID:唯一ID X/Y:坐标 fontSize:字号 fontColor:颜色 str:内容
function GUI:Text_Create(Parent, ID, X, Y, fontSize, fontColor, str) end

-- 创建伤害飘字并飞出消失
local function showDamage(parent, x, y, dmg)
    local txt = GUI:Text_Create(parent, "dmg_" .. os.time(), x, y, 18, "#FF4500", "-" .. dmg)
    local act = GUI:ActionMoveTo(0.8, x, y - 40)
    txt:runAction(act)
end

-- 动态改内容
GUI:Text_setString(txt, "-1520")

Parent 决定文本挂在哪个界面层，ID 是窗口内的唯一标识，同 ID 重复创建的行为是覆盖旧控件，用时间戳做 ID 的飘字不会互相覆盖。返回的控件对象持有后可以调用 Text_setString 动态改内容、Text_setTextColor 改颜色、Text_setFontSize 改字号，创建一次刷新千次的模式比反复创建销毁高效得多。

文字的进阶样式

-- 描边与阴影：让文字在任何背景上清晰
GUI:Text_enableOutline(txt, "#000000", 1)
-- 对齐方式：多行文本的排版
GUI:Text_setTextHorizontalAlignment(txt, 1)

Text_enableOutline 给文字加描边，飘字与标题在复杂背景上的可读性靠描边保障。Text_setMaxLineWidth 设定换行宽度，长文本自动折行，Text_setTextHorizontalAlignment 控制水平对齐。文本的销毁：removeFromParent 立即移除，配合 GUI:ActionFadeOut 的淡出动作做柔和的消失，飘字的生命周期就是创建、飞行动作、淡出移除的三拍子。

验证与监控

同屏文本控件的存量监控，控件数量超过渲染预算的界面要做控件池化。

踩坑记录

中文字符串的颜色串格式错误（少了井号）曾经让整段文字不显示，颜色串的格式校验在封装层做了断言。控件 ID 的唯一性冲突在循环创建时高发，ID 的生成规则（前缀加自增或时间戳）是批量创建控件的标准姿势。

上线要点

文本控件的创建与销毁是 UI 的 GC 大头，高频的飘字场景用控件池复用而不是反复创建。字号与坐标的适配：不同分辨率的屏幕上绝对坐标会错位，Attach 系列的挂载接口与锚点设置是适配的正确姿势。富文本需求（一段文字里混排图片与多色）不要用多个 Text 拼接，直接用 RichText_Create 的富文本控件。

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付，内容以官方知识库与真实项目为出处，按版本持续修订。