Godot 4 RichTextLabel 与 BBCode 富文本实战：godot-demo-projects 官方演示深度解析-育师

示例工程

【免费下载链接】godot-demo-projects

Demonstration and Template Projects

项目地址：https://gitcode.com/GitHub_Trending/go/godot-demo-projects

本文以 Godot 官方 demo 仓库 godot-demo-projects 中的 Rich Text Label with BBCode 演示项目（gui/rich_text_bbcode）为对象，系统讲解RichTextLabel控件的 BBCode 富文本能力：从基础样式、颜色控制、内嵌图片与超链接，到段落对齐、首字下沉、动态特效、表格列表，再到meta_clicked交互与print_rich()控制台输出。读完本文，你将能够直接复刻该演示中的全部标签用法，并在自己的界面中熟练驾驭 BBCode。

一、项目概览：一个演示 BBCode 全貌的展示台

该演示项目（gui/rich_text_bbcode/README.md）的核心目的只有一个：通过一段精心编排的示例文本，把RichTextLabel支持的 BBCode 标签"一屏打尽"。其基本信息如下：

语言：GDScript（演示全部逻辑集中在 rich_text_bbcode.gd）
渲染器：Compatibility（兼容模式），见 project.godot 中renderer/rendering_method="gl_compatibility"
Godot 版本：project.godot 的config/features声明为4.7，应以 Godot 4.7 及以上版本打开
场景结构：根节点RichTextBBCode（Control，居中布局，尺寸 1024×600）下挂三个子节点——占满全屏的RichTextLabel、左下角的Pause（暂停）按钮与PrintToConsole按钮
发布渠道：该演示同时在 Godot Asset Store 发布（README 中注明，可在官方项目管理器内直接搜索下载）

运行方式很简单：在 Godot 项目管理器中直接导入 gui/rich_text_bbcode/project.godot（run/main_scene指向 rich_text_bbcode.tscn），按 F5 运行即可看到完整效果。演示的 BBCode 示例文本就内嵌在 rich_text_bbcode.tscn 的text属性中，是理解本文所有标签的第一手素材。

二、开启 BBCode：RichTextLabel 的关键配置

在 Godot 4 中，RichTextLabel默认就能解析 BBCode，前提是打开bbcode_enabled属性。本演示在 rich_text_bbcode.tscn 中将其显式设为true：

bbcode_enabled = true

围绕这一核心开关，演示场景还设置了几个值得关注的配套属性（同样位于 rich_text_bbcode.tscn）：

属性	演示中的值	作用
`bbcode_enabled`	`true`	启用 BBCode 解析，文本中的`[...]`标签才会被渲染
`selection_enabled`	`true`	允许鼠标框选文本并复制
`context_menu_enabled`	`true`	启用右键上下文菜单（复制/全选等）
`focus_mode`	`2`	允许获得键盘焦点，配合按钮快捷键使用
`theme_override_colors/selection_color`	`Color(1,1,1,0.16)`	自定义选中文本的高亮色
`theme_override_constants/line_separation`	`1`	行间距 1 像素
`theme_override_constants/table_h_separation`	`120`	表格列间距 120 像素
`theme_override_constants/table_v_separation`	`10`	表格行间距 10 像素
`theme_override_styles/focus`	`StyleBoxEmpty`	用空样式盒替换默认焦点框，聚焦时不显示难看的虚线框

其中StyleBoxEmpty是场景内定义的一个子资源（rich_text_bbcode.tscn），这是一种让控件"聚焦却无焦点样式"的常见做法。

三、基础样式标签：斜体、加粗、下划线、删除线

演示文本开头便集中展示了最常用的文本样式标签，且支持任意嵌套组合：

[i]italics[/i] 与 [b]bold[/b]，以及 [i][b]both[/b][/i] [u]Underline[/u] 和 [s]strikethrough[/s] 也支持， [u color=red][i]italics[/i][/u]、[u color=green][b]bold[/b][/u] [u color=yellow][i][b]both[/b][/i][/u]

要点如下：

成对闭合：所有样式标签都必须以[tag]开头、[/tag]结尾，作用范围是标签之间的内容；
嵌套组合：[i][b]...[/b][/i]可以叠加多种样式；
带参数：[u color=red]这样的标签支持参数，此处为下划线指定颜色，参数值既可以是red、green、yellow这类命名颜色，也可以是十六进制值；
行内对照：本段文本直接引自 rich_text_bbcode.tscn，读者可逐条对照截图观察渲染效果。

四、颜色控制：color、fgcolor 与 bgcolor

BBCode 的颜色体系分为三类：文本颜色、前景色、背景色。演示文本（rich_text_bbcode.tscn）的用法是：

[color=#4cf]文本颜色[/color] [fgcolor=#49c9]前景色[/fgcolor] [bgcolor=#49c9]背景色[/bgcolor]

[color=...]：设置文本颜色，支持命名颜色（red、aqua等）与十六进制（如 3 位缩写#4cf、4 位带透明度缩写#49c9、6 位全写#fff3等）；
[fgcolor=...]：单独设置文字的前景色；
[bgcolor=...]：单独设置文字的背景色块；
可嵌套：演示文本中前景/背景色内部还嵌套了[color=#4cf]，说明颜色标签可以逐层叠加覆盖。

实际使用中，color标签最常用，而fgcolor/bgcolor属于更精细的控制手段，适合制作高亮、荧光笔式的文本效果。

五、富文本中的多媒体：内嵌图片、超链接与工具提示

这是 BBCode 相比普通Label最具优势的部分。演示文本（rich_text_bbcode.tscn）展示了一组完整用法：

[img]res://unicorn_icon.png[/img] ← 内嵌图片 [font_size=24]custom images[/font_size] ← 调整字号 [color=aqua][url=...]custom URLs[/url][/color] ← 超链接 [hint=This displays a hint.]Hover this to display a tooltip![/hint] ← 悬停提示

逐个拆解：

[img]路径[/img]：把任意res://图片资源渲染在文本流中，本演示使用的是 unicorn_icon.png（49×50 像素的独角兽小图标），出现在截图里正文第二行；
[font_size=N]：临时改变局部字号，用于强调或排版对比；
[url=地址]显示文本[/url]：生成可点击超链接，点击行为由meta_clicked信号接管（详见第九节）；演示文本中还嵌套了[color=aqua]让链接着色；
[hint=文本]内容[/hint]：鼠标悬停时显示工具提示，参数即提示内容；
[lb]与[rb]：分别渲染字面量的左方括号[与右方括号]，当需要在文本中展示方括号本身（比如讲解 BBCode 语法）时使用，演示末尾正是用[lb]url[rb]来书写"url 标签"的字面样式。

图片资源本身在场景文件中通过res://unicorn_icon.png引用，对应仓库文件 gui/rich_text_bbcode/unicorn_icon.png。

六、段落对齐、分隔线与首字下沉

排版类标签用于控制文本块在控件内的布局。演示文本（rich_text_bbcode.tscn）依次展示了：

左对齐是默认的，[center]居中对齐[/center]，[right]右对齐[/right] [hr width=50% height=2 color=#fff3] [fill][dropcap font_size=48 color=yellow margins=0,-10,0,-12]F[/dropcap]两端对齐……[/fill]

对齐：[center]、[right]作用于标签内文本，左对齐是默认值无需标签；
[hr]：插入一条水平分隔线，支持width（宽度，可用百分比）、height（线高像素）与color（颜色，#fff3为带透明度的白色）参数，演示中用它在样式段落与正文之间划出一条淡色分割线；
[fill]：两端对齐（justify），让长文本均匀铺满整行水平空间，适合正文段落；
[dropcap]：首字下沉，把段落第一个字放大并占据数行高度。演示中F被放大到font_size=48、着色为黄色，并通过margins=0,-10,0,-12微调边距（依次为上、右、下、左四个方向的偏移），实现下沉字与正文的精细对齐。

七、动态文本特效：脉冲、波浪、龙卷风与彩虹

Godot 内置了一整套可作用于局部文本的动画特效标签，演示文本（rich_text_bbcode.tscn）把六种特效全部点名：

[pulse]Pulse[/pulse] [wave]Wave[/wave] [tornado]Tornado[/tornado] [shake]Shake[/shake] [fade start=75 length=7]Fade[/fade] [rainbow]Rainbow[/rainbow]

[pulse]：文字按频率明暗脉动；
[wave]：文字呈正弦波浪起伏；
[tornado]：文字做旋转扭曲运动；
[shake]：文字抖动；
[fade]：文字淡入淡出，start与length参数控制渐变的起止位置（演示中start=75 length=7表示在 75% 处开始、持续 7 个字符长度的渐变）；
[rainbow]：文字颜色按彩虹色渐变滚动。

这些标签非常适合标题、提示语、状态文字等需要吸引眼球的场景，用法统一是"标签包住目标文本"。

八、表格与列表：table、cell、ul、ol

复杂排版场景下，BBCode 还支持表格。演示文本（rich_text_bbcode.tscn）构造了一个两列表格：

[table=2] [cell border=#fff3 bg=#fff1] [ul]无序列表内容[/ul] [/cell] [cell border=#fc13 bg=#fc11] [ol]有序列表内容[/ol] [/cell] [/table]

[table=N]：声明表格列数，table=2即两列；
[cell]：定义单元格，支持border（边框颜色）与bg（背景色）参数，两个单元格的颜色参数形成了左右两栏的视觉对比；
[ul]：无序列表（项目符号），可跨行包含多段文本；
[ol]：有序列表（自动编号），演示中渲染出1. Ordered、2. list example.的编号效果；
单元格间距由第二节提到的table_h_separation/table_v_separation主题常量控制。

九、交互逻辑：meta 点击、控制台打印与暂停

演示的交互逻辑全部集中在 rich_text_bbcode.gd，仅三个函数，却完整展示了 BBCode 的三个典型落地场景。

1. 点击链接（meta_clicked信号）

func _on_RichTextLabel_meta_clicked(meta: Variant) -> void: var err := OS.shell_open(str(meta)) if err == OK: print("Opened link '%s' successfully!" % str(meta)) else: print("Failed opening the link '%s'!" % str(meta))

当用户点击[url]生成的链接时，RichTextLabel发出meta_clicked信号，参数meta就是 URL 地址。脚本用OS.shell_open()交给系统默认浏览器打开，并依据返回值打印成功或失败日志。信号连接定义在场景文件 rich_text_bbcode.tscn 中：[connection signal="meta_clicked" from="RichTextLabel" to="." method="_on_RichTextLabel_meta_clicked"]。这是实现"富文本内嵌可点击链接"的标准套路。

2. 打印到控制台（print_rich()）

func _on_print_to_console_pressed() -> void: print_rich($RichTextLabel.text) print_rich("---\n[b]Note:[/b] While the Output panel supports all BBCode tags, terminal output only supports a subset of BBCode tags. ...")

PrintToConsole按钮把整个RichTextLabel.text（含全部 BBCode 标签）交给print_rich()输出。脚本内的注释明确提醒：Godot 的 Output 面板支持全部 BBCode 标签，但终端标准输出只支持子集（部分终端模拟器也不支持全部 ANSI 转义码）——因此这套打印方案最适合在编辑器内调试，而不是依赖外部终端展示完整富文本。

3. 暂停游戏（按钮 + 快捷键双通道）

func _on_pause_toggled(button_pressed: bool) -> void: get_tree().paused = button_pressed

Pause按钮是toggle_mode开关按钮，按下即通过get_tree().paused暂停整个场景树。它同时绑定了快捷键：场景中定义了Shortcut子资源（rich_text_bbcode.tscn），对应 project.godot 中注册的toggle_pause输入动作（键码4194313，即键盘 Pause 键），因此键盘按 Pause 键也能触发暂停。

十、项目配置速览：跑通演示的环境要素

project.godot 中的几处配置决定了该演示的运行表现：

run/main_scene="res://rich_text_bbcode.tscn"：主场景即演示场景；
run/low_processor_mode=true：启用低处理器模式（节能）；
renderer/rendering_method="gl_compatibility"：Compatibility 渲染器，与 README 声明一致，兼容性最好、对硬件要求最低；
window/stretch/mode="canvas_items"与aspect="expand"：画布自适应拉伸，窗口比例变化时 UI 按画布坐标等比缩放；
[input]段定义了toggle_pause动作，绑定键盘 Pause 键；
开发规范：gdscript/warnings/untyped_declaration=1将未声明类型的告警提升为错误，演示脚本因此显式标注了meta: Variant类型。

十一、超越演示：自定义标签与扩展方向

演示文本的收尾（rich_text_bbcode.tscn）明确点出了 BBCode 的进阶能力：

You can also create custom tags/effects, or customize behavior of[lb]url[rb]tags on click.

即读者可以：

自定义 BBCode 标签与特效：Godot 允许为RichTextLabel注册自定义的标签与文本特效，实现项目专属的富文本语法（如表情、数据高亮）；
定制 url 标签的点击行为：meta_clicked信号拿到的meta不一定是 URL 字符串，也可以是任意自定义标识，因此完全可以实现"点击文本触发游戏内逻辑"（打开背包、跳转场景、弹出对话框等），而不必真的调用OS.shell_open()；
配合主题系统：演示中的selection_color、表格间距等均通过theme_override_*按控件覆盖，若需要全局统一风格，可改为定义Theme资源统一管理。

从源码结构看，该演示是"一段文本 + 三个回调"的最小完整闭环：RichTextLabel负责解析与渲染，rich_text_bbcode.gd 负责交互响应，rich_text_bbcode.tscn 负责布局与信号接线。将它作为模板，任何项目都能在十几分钟内搭建出属于自己的 BBCode 富文本界面。