Up to date
This page is up to date for Godot 4.2
.
If you still find outdated information, please open an issue.
RichTextLabel 中的 BBCode¶
前言¶
Label 節點非常適合顯示基本文字,但它們有局限性。如果更改文字的顏色或對齊方式,則該更改會影響標籤節點中的所有文字。沒法只讓一部分文字用一種顏色,或者只居中一部分文字。要繞過此限制,可以使用 RichTextLabel 。
class_RichTextLabel 允許使用標記語法或內建 API 對文字進行複雜的格式化。它使用 BBCodes 作為標記語法,這是一種為部分文字指定格式規則的標記系統。如果您曾經使用過論壇(也稱為“公告板”,因此“BBCode”中的“BB”),您可能會熟悉它們。
與 Label 不同,RichTextLabel 還帶有自己的垂直捲軸。如果文字不適合控制項的大小,則會自動顯示此捲軸。可以透過取消選取 RichTextLabel 屬性面板中的 Scroll Active 屬性來停用捲軸。
大部分BBCode標籤也可以用在 XML 格式的類參考文件 .
也參考
除了這份說明文件,你可能也會想看看 Godot Demo 專案 。
使用 BBCode¶
預設情況下,class_RichTextLabel 的功能與普通的 class_Label 類似。它具有 property_text 屬性,您可以編輯該屬性以取得均勻格式的文字。為了能夠使用 BBCode 進行富文字格式,您需要透過設定 bbcode_enabled 開啟 BBCode 模式。之後,您可以使用可用標籤編輯:ref:text <class_RichTextLabel_property_text> 屬性。選擇 RichTextLabel 節點後,這兩個屬性都位於檢視器的頂端。
例如, BBCode [color=blue]blue[/color]
將會出現藍色的單詞“blue”。
大多數 BBCode 由 3 部群組成:開始標籤、內容和結束標籤。開始標記界定格式化部分的開始,也可以攜帶一些設定選項。一些開始標籤,例如上面顯示的“color”,也需要一個值才能工作。其他開始標籤可以接受多個選項(在開始標籤內以空格分隔)。結束標記界定格式化部分的結尾。在某些情況下,結束標記和內容都可以省略。
與 HTML 中的 BBCode 不同,RichTextLabel 在顯示時不會刪除前導/尾隨空白。重複的空格也會以原樣顯示在最終輸出中。這意味著在 RichTextLabel 中顯示程式碼區塊時,您不需要使用預先格式化的文字標記。
[tag]content[/tag]
[tag=value]content[/tag]
[tag option1=value1 option2=value2]content[/tag]
[tag][/tag]
[tag]
備註
RichTextLabel 不支援糾纏 BBCode 標籤。例如,不要使用:
[b]bold[i]bold italic[/b]italic[/i]
請使用:
[b]bold[i]bold italic[/i][/b][i]italic[/i]
安全地處理使用者輸入¶
在使用者可以自由輸入文字的場景中(例如多人遊戲中的聊天),您應該確保使用者不能使用將由 RichTextLabel 解析的任意 BBCode 標籤。這是為了避免不當使用格式,如果您的 RichTextLabel 處理「[url]」標籤,這可能會出現問題(因為玩家可能能夠建立指向網路釣魚網站或類似網站的可點擊連結)。
使用 RichTextLabel 的「[lb]」和/或「[rb]」標籤,我們可以用這些轉義標籤取代訊息中任何 BBCode 標籤的左括號和/或右括號。這可以防止使用者使用將被解析為標籤的 BBCode - 相反,BBCode 將顯示為文字。
這幾個檔案的內容如下:
extends RichTextLabel
func _ready():
append_chat_line("Player 1", "Hello world!")
append_chat_line("Player 2", "Hello [color=red]BBCode injection[/color] (no escaping)!")
append_chat_line_escaped("Player 2", "Hello [color=red]BBCode injection[/color] (with escaping)!")
# Returns escaped BBCode that won't be parsed by RichTextLabel as tags.
func escape_bbcode(bbcode_text):
# We only need to replace opening brackets to prevent tags from being parsed.
return bbcode_text.replace("[", "[lb]")
# Appends the user's message as-is, without escaping. This is dangerous!
func append_chat_line(username, message):
append_text("%s: [color=green]%s[/color]\n" % [username, message])
# Appends the user's message with escaping.
# Remember to escape both the player name and message contents.
func append_chat_line_escaped(username, message):
append_text("%s: [color=green]%s[/color]\n" % [escape_bbcode(username), escape_bbcode(message)])
效能¶
在大多數情況下,您可以直接按原樣使用 BBCode,因為文字格式化很少是一項繁重的工作。但是,對於特別大的 RichTextLabel(例如跨越數千行的控制台紀錄),當更新 RichTextLabel 的文字時,您可能會在遊戲過程中遇到卡頓的情況。
Godot 沒有使用限制
使用“append_text()”函式而不是附加到“text”屬性。此函式只會解析新增文字的 BBCode,而不是從整個「text」屬性解析 BBCode。
使用``push_[tag]()`` 和``pop()`` 函式將標籤新增至RichTextLabel,而不是使用BBCode。
在 RichTextLabel 中啟用 Threading > Threaded 屬性。這不會加快處理速度,但會防止主執行緒阻塞,從而避免在遊戲過程中出現卡頓。僅在專案中實際需要時才啟用線程,因為線程有一些開銷。
使用 push_[標籤]() 和 pop() 函式代替 BBCode¶
如果因為效能原因不想使用 BBCode,可以使用 RichTextLabel 提供的函式來建立格式化標籤,而無需在文字中寫入 BBCode。
每個 BBCode 標籤(包括效果)都有一個``push_[tag]()`` 函式(其中``[tag]`` 是標籤的名稱)。還有一些方便的函式可用,例如“push_bold_italics()”,它將“push_bold()”和“push_italics()”組合到一個標籤中。有關``push_[tag]()`` 函式的完整列表,請參閱 RichTextLabel 類別參考 <class_RichTextLabel>`。
pop()
函式用於結束 any 標籤。由於 BBCode 是一個標籤 stack,因此使用 pop()
將首先關閉最近啟動的標籤。
以下腳本將產生與使用「BBCode [color=green]test [i]example[/i][/color]」相同的視覺輸出:
extends RichTextLabel
func _ready():
append_text("BBCode ") # Trailing space separates words from each other.
push_color(Color.GREEN)
append_text("test ") # Trailing space separates words from each other.
push_italics()
append_text("example")
pop() # Ends the tag opened by `push_italics()`.
pop() # Ends the tag opened by `push_color()`.
警告
使用格式化函式時,請勿直接設定“text”屬性。附加到「text」屬性將刪除使用「append_text()」、「push_[tag]()」和「pop()」函式對 RichTextLabel 所做的所有修改。
參考¶
標籤 |
範例 |
乙
使“{text}”使用“RichTextLabel”的粗體(或粗體斜體)字形。
|
|
我
使“{text}”使用“RichTextLabel”的斜體(或粗體斜體)字形。
|
|
u
在
{text} 上顯示底線。 |
|
s
在
{text} 上顯示刪除線。 |
|
code
讓
{text} 使用 RichTextLabel 的等寬字形。 |
|
p
新增帶有``{text}``的新段落。支援配置選項,請參閱 段落選項。
|
[p]{text}[/p] [i]{text}[/i] |
center
使得 {text} 水平居中.
與“[palign=center]”相同。
|
|
left
Makes
{text} horizontally left-aligned.與“[palign=left]”相同。
|
|
right
使得 {text} 右對齊.
與“[palign=right]”相同。
|
|
fill
使{text}填充RichTextLabel的寬度.
與“[palign=fill]”相同。
|
|
indent
Indents
{text} once.
The indentation width is the same as with [ul] or [ol] , but without a bullet point. |
|
url
建立超連結(帶下劃線且可點擊的文字)。可以包含可選的“{text}”或按原樣顯示“{link}”。
|
[url]{url}[/url] [url=<url>]{text}[/url] |
霧:
建立當滑鼠懸停在文字上時顯示的工具提示提示。工具提示文字不應加引號(否則引號將按原樣顯示在工具提示中)。
|
[hint={懸停時顯示的工具提示文字}]{文字}[/hint] |
img
從「{path}」插入映像(可以是任何有效的 class_Texture2D 資源)。
如果提供了“{width}”,圖像將嘗試適應該寬度並保持縱橫比。
如果同時提供了“{width}”和“{height}”,則圖像將縮放到該尺寸。
如果提供了「{valign}」配置,圖像將嘗試與周圍的文字對齊,請參閱:ref:doc_bbcode_in_richtextlabel_image_alignment。
支援配置選項,請參閱 匯入選項。
|
[img]{path}[/img] [img=<width>]{path}[/img] [img=<width>x<height>]{path}[/img] [img]{path}[/img] [img]{path}[/img] |
[font=<path>]{text}[/font] [font=<path>]{text}[/font] |
|
font_size
為 {text} 內容設定自訂字形, 字形由 <path> 指定.
|
|
dropcap
對「{text}」使用不同的字形大小和顏色,同時使標籤的內容在足夠大的情況下跨越多行。
‘首字下沉 <https://www.computerhope.com/jargon/d/dropcap.htm>`__ 通常是一個大寫字符,但
[dropcap] 支援包含多個字元。 「margins」值以逗號分隔,可以是正數、零或負數。負頂部和底部邊距對於允許段落的其餘部分顯示在首字下沉下方特別有用。 |
|
功能:
為
{text} 啟用自訂 OpenType 字形功能。{list} 中的功能必須以英文逗號分隔。 |
[opentype_features={list}] {project} [/opentype_features] |
lang
Overrides the language for
{text} that is set by the BiDi > Language property
in RichTextLabel. {code} must be an ISO language code.
This can be used to enforce the use of a specific script for a language without
starting a new paragraph. Some font files may contain script-specific substitutes,
in which case they will be used. |
|
color
更改“{text}”的顏色。顏色必須由通用名稱提供(請參閱 doc_bbcode_in_richtextlabel_named_colors`)或使用十六進位格式(例如“#ff00ff”,請參閱 doc_bbcode_in_richtextlabel_hex_colors`)。
|
|
編輯器:
繪製“{text}”後面的顏色。這可用於突出顯示文字。接受與“color”標籤相同的值。
|
|
編輯器:
在``{text}``前面繪製顏色。這可用於透過使用不透明的前景色來「編輯」文字。接受與“color”標籤相同的值。
|
|
outline_size
為 {text} 內容設定自訂字形, 字形由 <path> 指定.
|
[outline_size={size}] {project} [/outline_size] |
編輯器:
對“{text}”使用自訂輪廓顏色。接受與“color”標籤相同的值。
|
[outline_color={code/name}] {project} [/outline_color] |
table
建立一個包含「{number}」欄位的表。使用“cell”標籤來定義表格儲存格。
|
|
[cell]{text}[/cell] [cell={ratio}]{text}[/cell] [cell]{text}[/cell] |
|
[ul]{items}[/ul] [url=<url>]{text}[/url] |
|
ol
新增給定「{type}」的有序(編號)列表(請參閱 宣告型別)。列表「{items}」必須透過在每行文字中放置一個專案來提供。
|
|
磅,rb
分別加上``[
和 ]``。允許轉義 BBCode 標記。這些是自關閉標籤,這意味著您不需要關閉它們(並且沒有“[/lb]”或“[/rb]”關閉標籤)。
|
[lb]b[rb]text[lb]/b[rb] 將顯示為``[b]text[/b]``。 |
可以使用自己的自結束標記來新增多個 Unicode 控製字元。
與貼上這些相比,這可以使維護更容易
直接在文字中控製字元。
|
備註
如果在 RichTextLabelNode 的主題覆蓋中設定了適當的自訂字形,則粗體 ([b]
) 和斜體 ([i]
) 格式的標籤效果最佳。如果沒有定義自訂粗體或斜體字形,則 Godot 將產生「仿粗體和斜體字形 <https://fonts.google.com/knowledge/glossary/faux_fake_pseudo_synthesized>」。與手工製作的粗體/斜體字形變體相比,這些字形很少看起來很好。
等寬([code]
)標籤**僅**在 RichTextLabel 節點的主題覆蓋中設定自訂字形時才有效。否則,等寬文字將使用常規字形。
目前還沒有用於控制文字垂直居中的BBCode標籤.
可以跳過所有標籤的選項。
段落選項¶
align
值
left
、center
、right
、fill
預設
length()
文字水平對齊。
bidi_override、st
值
default
、uri
、file
、email
、list
、none
、custom
預設
預設
結構化文字覆蓋。
direction、dir
值
-h
,--help
,/?
預設
繼承
沿指定方向移動。
language、lang
值
圖片: 請參閱 doc_import_images 。
預設
繼承
Locale override. Some font files may contain script-specific substitutes, in which case they will be used.
tab_stops
值
List of floating-point numbers, e.g.
10.0,30.0
預設
Width of the space character in the font
Overrides the horizontal offsets for each tab character. When the end of the list is reached, the tab stops will loop over. For example, if you set
tab_stops
to10.0,30.0
, the first tab will be at10
pixels, the second tab will be at10 + 30 = 40
pixels, and the third tab will be at10 + 30 + 10 = 50
pixels from the origin of the RichTextLabel.
處理 [url]
標籤點擊¶
預設情況下, [url]
標籤在按一下時不執行任何操作.這是為了允許靈活使用 [url]
標籤,而不是限制它們在Web瀏覽器中打開URL.
要對點擊``[url]`` 標籤進行處理,請將該 RichTextLabel 節點的 meta_clicked 訊號連接到一個腳本函式上。
例如,將如下方法連接到 meta_clicked
上即可在使用者的預設網頁瀏覽器中打開被點擊的 URL:
# This assumes RichTextLabel's `meta_clicked` signal was connected to
# the function below using the signal connection dialog.
func _richtextlabel_on_meta_clicked(meta):
# `meta` is not guaranteed to be a String, so convert it to a String
# to avoid script errors at run-time.
OS.shell_open(str(meta))
要支援更高級的用法,也可以在 [url]
標籤的選項中儲存 JSON,然後在處理 meta_clicked
訊號的函式中解析。例如:
[url={"example": "value"}]JSON[/url]
匯入選項¶
color
值
顏色名稱或十六進位格式的顏色
預設
繼承
圖像的著色顏色(調變)。
height
值
數字
預設
繼承
檔案的絕對路徑
width
值
數字
預設
繼承
檔案的絕對路徑
版本
值
x,y,寬度,高度(以像素為單位)
預設
繼承
圖像的區域框。可用於顯示精靈表中的單個圖像。
變數與賦值¶
當使用“[img]”標籤提供垂直對齊值時,圖像將嘗試將自身與周圍的文字對齊。使用影像的垂直點和文字的垂直點來執行對齊。圖像上有 3 個可能的點(「頂部」、「中心」和「底部」),文字上有 4 個可能的點(「頂部」、「中心」、「基線``和``底部``) ,可以任意組合使用。
若要指定這兩個點,請使用它們的全名或簡稱作為圖像標籤的值:
[img=top,bottom]
[img=center,center]
您也可以只指定一個值(「top」、「center」或「bottom」)以使用對應的預設(「top-top」、「center-center」) ,和「底部-底部」分別)。
值的簡稱為“t”(“top”)、“c”(“center”)、“l”(“baseline”)和“b” (``底部`)。
匯入選項¶
name、n
值
資源路徑
預設
繼承
資源路徑
size、s
值
數位,單位為像素。
預設
繼承
自定 Godot 伺服器
有名稱的型別¶
對於允許按名稱指定顏色的標籤,您可以使用內建 class_Color 類別中的常數名稱。命名類別可以使用不同的大小寫以多種樣式指定:「DARK_RED」、「DarkRed」和「darkred」將給出相同的精確結果。
十六進位顏色程式碼¶
不透明的 RGB 顏色支援使用任何有效的 6 位十六進位數,例如 [color=#ffffff]白色[/color]
。也支援短的 RGB 顏色碼,比如 ``#6f2``(等價於 #66ff22)。
透明的 RGB 顏色可以使用任意 8 位十六進位數,例如 [color=#88ffffff]半透明白色[/color]
。請注意這裡的 alpha 通道是顏色碼中的**第一個**分量,不是最後一個。也支援短的 RGBA 顏色碼,比如 #86f2`(等價於 `#8866ff22)。
通用選項¶
會被解析為
值
整數
預設
1
細胞膨脹率。這定義了哪些單元格將嘗試按比例擴充至其他單元格及其擴充比率。
border
值
顏色名稱或十六進位格式的顏色
預設
繼承
儲存格邊框顏色。
bg
值
顏色名稱或十六進位格式的顏色
預設
繼承
單元格背景顏色。對於交替奇數/偶數行背景,您可以使用``bg=odd_color,even_color``。
或無序集合:¶
預設情況下,「[ul]」標籤使用「U+2022」「Bullet」Unicode 字形作為專案符號字元。此行為類似於網頁瀏覽器。可以使用“[ulBullet={bullet}]”自訂專案符號字元。如果提供,此 {bullet}
參數必須是一個*單*字符,不帶引號(例如,[bullet=*]
)。附加字元將被忽略。專案符號字元的寬度不會影響列表的格式。
請參閱維基百科上的「專案符號(排版)」<https://en.wikipedia.org/wiki/Bullet_(typography)>`__,取得可以直接貼上到「bullet」參數中的常見專案符號字元列表。
宣告型別¶
有序列表可用於自動按升序以數字或字母標記專案。此標籤支援以下型別選項:
1
- 數字,如果可能,使用特定於語言的編號系統。a
,A
- 小寫和大寫拉丁字母。i
,I
- 小寫和大寫羅馬數字。
效果¶
BBCode 也可用於建立不同的文字效果,並且可以選擇動畫效果。開箱即用提供了五種可自訂的效果,您可以輕鬆建立自己的效果。預設情況下,當 SceneTree 暫停 <doc_pausing_games> 時,動畫效果將暫停:ref:`。您可以透過調整 RichTextLabel 的 Process > Mode 屬性來變更此行為。
下面的所有範例都提到了列出的標記格式中選項的預設值。
備註
移動字元位置的文字效果可能會導致字元被 RichTextLabel 節點邊界剪切。
您可以透過在選擇RichTextLabel 節點後在屬性面板中停用**控制> 佈局> 剪輯內容** 來解決此問題,或者透過使用該效果在行上方和下方使用換行符來確保在文字周圍新增足夠的邊距。
脈衝¶
Pulse creates an animated pulsing effect that multiplies each character's
opacity and color. It can be used to bring attention to specific text. Its tag
format is [pulse freq=1.0 color=#ffffff40 ease=-2.0]{text}[/pulse]
.
freq
controls the frequency of the half-pulsing cycle (higher is faster). A
full pulsing cycle takes 2 * (1.0 / freq)
seconds. color
is the target
color multiplier for blinking. The default mostly fades out text, but not
entirely. ease
is the easing function exponent to use. Negative values
provide in-out easing, which is why the default is -2.0
.
波浪¶
波浪會使文字上下波動。其標籤格式是 [wave amp=50 freq=2][/wave]
。amp
控制特效高低,freq
控制文字上下移動的速度。
「amp」控制效果的高低,「freq」控製文字上升和下降的速度。 freq
值為``0`` 將導致沒有可見波,負``freq`` 值也不會顯示任何波。如果「connected」為「1」(預設),則帶有連字的字形將一起移動。如果“connected”為“0”,則每個字形都會單獨移動,即使它們是透過連字連接的。這可以解決字形連字的某些渲染問題。
旋風¶
龍捲風使文字在圓圈內移動, 它的標籤格式是 [tornado radius=5 freq=2][/tornado]
. radius
是控制偏移的圓半徑, freq
是文字在圓中移動的速度.
「radius」是控制偏移的圓的半徑,「freq」是文字在圓中移動的速度。 freq
值為``0`` 將暫停動畫,而負值``freq`` 將向後播放動畫。如果「connected」為「1」(預設),則帶有連字的字形將一起移動。如果“connected”為“0”,則每個字形都會單獨移動,即使它們是透過連字連接的。這可以解決字形連字的某些渲染問題。
抖動¶
晃動使文字晃動。其標籤格式為「[搖動率=20.0等級=5連線=1]{文字}[/搖動]」。
「rate」控製文字抖動的速度,「level」控製文字偏離原點的距離。如果「connected」為「1」(預設),則帶有連字的字形將一起移動。如果“connected”為“0”,則每個字形都會單獨移動,即使它們是透過連字連接的。這可以解決字形連字的某些渲染問題。
漸隱¶
淡入淡出創造靜態淡入淡出效果,使每個角色的不透明度倍增。其標籤格式為``[fade start=4 length=14]{text}[/fade]``。
漸變在沒有動畫的文字上建立一個漸變效果, 它的標籤格式是 [fade start=4 length=14][/fade]
. start
控制相對於插值淡入命令的起始位置, length
控制淡出應該發生多少個字元.
彩虹¶
彩虹讓文字呈現出隨時間變化的彩虹色, 它的標籤格式是 [rainbow freq=0.2 sat=10 val=20][/rainbow]
. freq
是每秒完整的彩虹週期數, sat
是彩虹的飽和度, val
是彩虹的數值.
「freq」是每秒完整彩虹週期的數量,「sat」是彩虹的飽和度,「val」是彩虹的數值。 freq
值為``0`` 將暫停動畫,而負值``freq`` 將向後播放動畫。
字形輪廓「不受」彩虹效果的影響(它們保持原來的顏色)。現有的字形顏色被彩虹效果覆蓋。但是,CanvasItem 的 Modulate 和 Self Modulate 屬性將影響彩虹效果的外觀,因為調變會倍增其最終顏色。