文本组件 ​

文本组件用于显示标题、说明、状态值和剧情文字。它支持响应式变量、自定义 TTF 字体、文字颜色、按字符数量或实际像素宽度换行、逐字显示以及左对齐、居中和右对齐。

适用场景 ​

• 页面标题和按钮外的说明文字
• HUD 数值与状态提示
• 剧情对白和逐字出现的文本
• 通过页面变量和脚本动态修改的文字

通用配置 ​

专属配置 ​

逐字播放按页面渲染作用域记录。重新打开页面或通过运行时修改文本内容后，会从新内容开头重新显示。

响应式文字 ​

在内容中使用 {...}，文本就会跟随变量和只读常量实时变化：

点击次数：{vars.count}
生命：{vals.player.health} / {vals.player.maxHealth}
余额：{vals.papi.balance}
完成度：{vars.current / vars.total * 100}%

花括号外的文字保持原样，花括号内支持变量引用、四则运算和括号。需要显示普通花括号时，连续写两个左花括号或两个右花括号。未知变量或非法表达式会保留原占位内容，不会让页面崩溃。

详细配置、PAPI 映射和刷新说明请阅读响应式变量与实时文字。

显式换行 ​

text.value 可以包含真实换行。原版 Minecraft 字体和自定义 TTF 字体都会先按显式换行分段，再对每一段应用 textLineLength 和 textLineWidth。空行也会保留对应行高。

两个限制可以单独使用，也可以同时使用。同时设置时，追加下一个字符会超过任意一个限制就换到下一行。像素宽度按当前字体的真实字形和 textSize 计算，因此中英文、数字和不同 TTF 字体会得到与画面一致的行宽。单个字形本身超过 textLineWidth 时，该字形会单独占一行，不会消失。

text:
  value: |-
    第一行：当前状态正常
    第二行：等待下一次结算

    第四行：这里保留了一个空行
  textLineLength: 12
  textLineWidth: 160

如果页面只是显示标题、数值和简短说明，仍建议使用多个独立文本组件控制位置。长说明、剧情文字或服务端动态生成的多行内容再使用显式换行，会更容易保持布局清晰。

自定义字体与颜色 ​

将有权使用的 TTF 字体放进当前客户端的 resourcepacks/ChaUI 文件夹，再在“字体路径”中填写相对路径。例如字体实际位于 resourcepacks/ChaUI/fonts/title.ttf 时，配置填写 fonts/title.ttf。

字体路径只支持正斜杠和 .ttf 文件，不接受绝对路径、路径穿越或反斜杠。其他玩家的客户端也需要存在同一路径字体，否则会自动使用 Minecraft 原版字体。自定义字体缺少某个字符时，只会让该字符使用原版字体，不影响同一段中的其他字符。

“字体分辨率”决定自定义字体在放大时能保留多少细节，不会改变文字实际显示大小、组件布局、换行或对齐。文字在页面上需要多大，仍然由 text.textSize 控制。一般文字可保持默认 32；较大的标题或笔画细节丰富的字体可尝试 64 或 96。只有确实需要超大文字时才建议继续提高，避免无意义地增加客户端内存和显存占用。

16 低于默认精度，主要用于节省资源，不会让字体更清晰；而且在小字号下与 32 的差别可能不明显。要验证配置是否生效，建议在较大的标题上对比 16 与 96，实际显示大小仍应保持一致，变化的是笔画边缘细节。

同一个页面可以按组件分别设置字体分辨率。例如正文保持 32，标题使用 96。编辑器中留空不会保存该配置，运行时仍按默认值 32 处理；明确填写 32 时则会保留在页面配置中。未配置自定义字体时，“字体分辨率”不会产生效果。

颜色固定填写 # 加六位十六进制数字，例如 #FFCC66 是金黄色，#FFFFFF 是白色。需要半透明时，在文本组件根级填写 opacity: 0.5。

同样的 font、fontResolution 与 color 也可以配置在按钮的 button 数据块中。文本与按钮分别保存自己的字体样式；输入框文字、物品数量和悬浮提示仍使用原版字体。

自定义 TTF 字体同样支持原版内联颜色码 §0 至 §f 和重置码 §r。text.color 是整段文字的基础颜色，内联颜色码从出现位置开始覆盖 RGB，§r 会恢复 text.color。组件根级 opacity 统一作用于整段文字。例如：

text:
  value: "普通颜色 §c红色 §r恢复基础颜色"
  font: fonts/title.ttf
  color: "#66CCFF"

配置示例 ​

- id: welcome_title
  type: text
  parent: ""
  visible: true
  enabled: false
  pointerEvents: pass
  scale: 1
  opacity: 0.9
  z: 20
  layout:
    x: window.width * 0.5 - 100
    y: 30
    width: 200
    height: 20
  text:
    value: "欢迎来到服务器，{vars.playerName}"
    font: fonts/title.ttf    # 留空或删除此项时使用原版字体
    fontResolution: 96       # 16~256；大标题可适当提高，留空默认 32
    color: "#FFCC66"        # 固定六位 RRGGBB
    textSize: 1.5
    textLineLength: 0        # 0 表示不按字数主动换行
    textLineWidth: 0         # 0 表示不限制渲染后的 GUI 像素宽度
    revealIntervalMs: 40    # 每 40 毫秒显示一个字符
    align: center
  tooltip: []
  events:
    create: vars.titleCreated = true # 组件创建后写入当前页面变量

文本组件对象可以读取当前文字和布局声明。例如：

events:
  create: |-
    vars.titleText = component("welcome_title").text.value
    vars.titleXFormula = component("welcome_title").layout.expression("x").source

常见问题 ​

设置 center 后仍不在整个屏幕中央 ​

对齐只作用于组件自己的 layout.width。先让组件区域位于目标位置，再使用 center 居中文本。

中英文混排时怎样让右边界更整齐 ​

使用 textLineWidth 按当前字体的实际显示宽度换行。需要同时限制每行最多多少个字符时，再一起设置 textLineLength；两项中先达到的限制会触发换行。

文字突然不显示 ​

检查 visible、visibleWhen、根级 opacity、文字大小和布局公式。非法条件会按不可见安全处理；字体文件缺失或损坏时会自动回退原版字体，不会让整个页面失效。

自定义字体看起来模糊或有锯齿 ​

先确认“字体路径”已经正确加载，再逐步提高“字体分辨率”，例如从默认 32 调到 64 或 96。不要通过提高 textSize 来改善清晰度：textSize 只负责显示大小。分辨率越高，资源占用也越高，建议以实际页面中足够清晰为准。

创建事件 ​

文本组件的 events.create 适合写入初始变量或临时调整 text.value。页面 open 先执行，因此 create 可以读取 open 已设置的变量；文字中的 {vars.xxx} 会立即响应最新值。动态文本实例也会各触发一次。