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 節點後,這兩個屬性都位於檢視器的頂端。

../../_images/bbcode_in_richtextlabel_inspector.webp

例如, BBCode [color=blue]blue[/color] 將會出現藍色的單詞“blue”。

../../_images/bbcode_in_richtextlabel_basic_example.webp

大多數 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 將顯示為文字。

未轉義的使用者輸入導致 BBCode 注入(第 2 行)和轉義的使用者輸入(第 3 行)的範例

未轉義的使用者輸入導致 BBCode 注入(第 2 行)和轉義的使用者輸入(第 3 行)的範例

這幾個檔案的內容如下:

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 標籤。當在另一個不支援 BBCode 的控制項(例如工具提示)中顯示 RichTextLabel 的文字時,這非常有用:

extends RichTextLabel

func _ready():
    var regex = RegEx.new()
    regex.compile("\\[.*?\\]")
    var text_without_tags = regex.sub(text, "", true)
    # `text_without_tags` contains the text with all BBCode tags removed.

備註

不建議對使用者輸入完全刪除 BBCode 標籤,因為它可能會修改顯示的文字,而使用者並不了解部分訊息被刪除的原因。 轉義使用者輸入 應該是首選。

效能

在大多數情況下,您可以直接按原樣使用 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”的粗體(或粗體斜體)字形。

[b]{text}[/b]

使“{text}”使用“RichTextLabel”的斜體(或粗體斜體)字形。

[i]{text}[/i]

u
{text} 上顯示底線。

[u]{text}[/u]

s
{text} 上顯示刪除線。

[s]{text}[/s]

code
{text} 使用 RichTextLabel 的等寬字形。

[code]{text}[/code]

p
新增帶有``{text}``的新段落。支援配置選項,請參閱 段落選項
[p]{text}[/p]
[i]{text}[/i]
center
使得 {text} 水平居中.
與“[palign=center]”相同。

[center]{text}[/center]

left
Makes {text} horizontally left-aligned.
與“[palign=left]”相同。

[left]{text}[/left]

right
使得 {text} 右對齊.
與“[palign=right]”相同。

[right]{text}[/right]

fill
使{text}填充RichTextLabel的寬度.
與“[palign=fill]”相同。

[fill]{text}[/fill]

indent
Indents {text} once. The indentation width is the same as with [ul] or [ol], but without a bullet point.

[indent]{text}[/indent]

url
建立超連結(帶下劃線且可點擊的文字)。可以包含可選的“{text}”或按原樣顯示“{link}”。
顯示 {url},文字帶有底線並且可以點擊。**必須在“meta_clicked”訊號中處理,點擊才會生效。**參閱 處理 [url] 標籤點擊
[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
使“{text}”使用“{path}”中的字型資源。
支援配置選項,請參閱 匯入選項
[font=<path>]{text}[/font]
[font=<path>]{text}[/font]
font_size
為 {text} 內容設定自訂字形, 字形由 <path> 指定.

[font_size={size}]{text}[/font_size]

dropcap
對「{text}」使用不同的字形大小和顏色,同時使標籤的內容在足夠大的情況下跨越多行。
‘首字下沉 <https://www.computerhope.com/jargon/d/dropcap.htm>`__ 通常是一個大寫字符,但 [dropcap] 支援包含多個字元。 「margins」值以逗號分隔,可以是正數、零或負數。負頂部和底部邊距對於允許段落的其餘部分顯示在首字下沉下方特別有用。

[dropcap font_size={size} color={color} margins={left},{top},{right},{bottom}]{text}[/dropcap]

功能:
{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.

[lang={code}]{text}[/color]

color
更改“{text}”的顏色。顏色必須由通用名稱提供(請參閱 doc_bbcode_in_richtextlabel_named_colors`)或使用十六進位格式(例如“#ff00ff”,請參閱 doc_bbcode_in_richtextlabel_hex_colors`)。

[color={code/name}]{text}[/color]

編輯器:
繪製“{text}”後面的顏色。這可用於突出顯示文字。接受與“color”標籤相同的值。

[bgcolor={code/name}]{text}[/bgcolor]

編輯器:
在``{text}``前面繪製顏色。這可用於透過使用不透明的前景色來「編輯」文字。接受與“color”標籤相同的值。

[fgcolor={code/name}]{text}[/fgcolor]

outline_size
為 {text} 內容設定自訂字形, 字形由 <path> 指定.
[outline_size={size}]
{project}
[/outline_size]
編輯器:
對“{text}”使用自訂輪廓顏色。接受與“color”標籤相同的值。
[outline_color={code/name}]
{project}
[/outline_color]
table
建立一個包含「{number}」欄位的表。使用“cell”標籤來定義表格儲存格。

[table={number}]{cells}[/table]

cell
將帶有{text}的儲存格新增到表格中.
如果提供了“{ratio}”,則儲存格將嘗試與其他儲存格及其比值成比例地擴充到該值。
支援配置選項,請參閱 通用選項
[cell]{text}[/cell]
[cell={ratio}]{text}[/cell]
[cell]{text}[/cell]
ul
新增無序列表。列表「{items}」必須透過在每行文字中放置一個專案來提供。
可以使用「{bullet}」參數自訂專案符號點,請參閱 或無序集合:
[ul]{items}[/ul]
[url=<url>]{text}[/url]
ol
新增給定「{type}」的有序(編號)列表(請參閱 宣告型別)。列表「{items}」必須透過在每行文字中放置一個專案來提供。

[ol 型別={型別}]{專案}[/ol]

rb
分別加上``[]``。允許轉義 BBCode 標記。
這些是自關閉標籤,這意味著您不需要關閉它們(並且沒有“[/lb]”或“[/rb]”關閉標籤)。
[lb]b[rb]text[lb]/b[rb] 將顯示為``[b]text[/b]``。
可以使用自己的自結束標記來新增多個 Unicode 控製字元。
與貼上這些相比,這可以使維護更容易
直接在文字中控製字元。
``[lrm]``(從左到右標記),``[rlm]``(從右到左標記),``[lre]``(從左到右嵌入),
``[rle]``(從右到左嵌入),``[lro]``(從左到右覆蓋),``[rlo]``(從右到左覆蓋),
``[pdf]``(流行定向格式),``[alm]``(阿拉伯字母標記),``[lri]``(從左到右隔離),
``[rli]``(從右到左隔離),``[fsi]``(第一個強隔離),``[pdi]``(流行定向隔離),
``[zwj]``(零寬度連接符),``[zwnj]``(零寬度非連接符),``[wj]``(單字連接符),
``[害羞]``(軟連字符)

備註

如果在 RichTextLabelNode 的主題覆蓋中設定了適當的自訂字形,則粗體 ([b]) 和斜體 ([i]) 格式的標籤效果最佳。如果沒有定義自訂粗體或斜體字形,則 Godot 將產生「仿粗體和斜體字形 <https://fonts.google.com/knowledge/glossary/faux_fake_pseudo_synthesized>」。與手工製作的粗體/斜體字形變體相比,這些字形很少看起來很好。

等寬([code])標籤**僅**在 RichTextLabel 節點的主題覆蓋中設定自訂字形時才有效。否則,等寬文字將使用常規字形。

目前還沒有用於控制文字垂直居中的BBCode標籤.

可以跳過所有標籤的選項。

段落選項

  • align

    leftcenterrightfill

    預設

    length()

    文字水平對齊。

  • bidi_overridest

    defaulturifileemaillistnonecustom

    預設

    預設

    結構化文字覆蓋。

  • directiondir

    -h, --help, /?

    預設

    繼承

    沿指定方向移動。

  • languagelang

    圖片: 請參閱 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 to 10.0,30.0, the first tab will be at 10 pixels, the second tab will be at 10 + 30 = 40 pixels, and the third tab will be at 10 + 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” (``底部`)。

匯入選項

  • namen

    資源路徑

    預設

    繼承

    資源路徑

  • sizes

    數位,單位為像素。

    預設

    繼承

    自定 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 節點後在屬性面板中停用**控制> 佈局> 剪輯內容** 來解決此問題,或者透過使用該效果在行上方和下方使用換行符來確保在文字周圍新增足夠的邊距。

脈衝

../../_images/bbcode_in_richtextlabel_effect_pulse.webp

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.

波浪

../../_images/bbcode_in_richtextlabel_effect_wave.webp

波浪會使文字上下波動。其標籤格式是 [wave amp=50 freq=2][/wave]amp 控制特效高低,freq 控制文字上下移動的速度。

「amp」控制效果的高低,「freq」控製文字上升和下降的速度。 freq 值為``0`` 將導致沒有可見波,負``freq`` 值也不會顯示任何波。如果「connected」為「1」(預設),則帶有連字的字形將一起移動。如果“connected”為“0”,則每個字形都會單獨移動,即使它們是透過連字連接的。這可以解決字形連字的某些渲染問題。

旋風

../../_images/bbcode_in_richtextlabel_effect_tornado.webp

龍捲風使文字在圓圈內移動, 它的標籤格式是 [tornado radius=5 freq=2][/tornado] . radius 是控制偏移的圓半徑, freq 是文字在圓中移動的速度.

「radius」是控制偏移的圓的半徑,「freq」是文字在圓中移動的速度。 freq 值為``0`` 將暫停動畫,而負值``freq`` 將向後播放動畫。如果「connected」為「1」(預設),則帶有連字的字形將一起移動。如果“connected”為“0”,則每個字形都會單獨移動,即使它們是透過連字連接的。這可以解決字形連字的某些渲染問題。

抖動

../../_images/bbcode_in_richtextlabel_effect_shake.webp

晃動使文字晃動。其標籤格式為「[搖動率=20.0等級=5連線=1]{文字}[/搖動]」。

「rate」控製文字抖動的速度,「level」控製文字偏離原點的距離。如果「connected」為「1」(預設),則帶有連字的字形將一起移動。如果“connected”為“0”,則每個字形都會單獨移動,即使它們是透過連字連接的。這可以解決字形連字的某些渲染問題。

漸隱

../../_images/bbcode_in_richtextlabel_effect_fade.webp

淡入淡出創造靜態淡入淡出效果,使每個角色的不透明度倍增。其標籤格式為``[fade start=4 length=14]{text}[/fade]``。

漸變在沒有動畫的文字上建立一個漸變效果, 它的標籤格式是 [fade start=4 length=14][/fade] . start 控制相對於插值淡入命令的起始位置, length 控制淡出應該發生多少個字元.

彩虹

../../_images/bbcode_in_richtextlabel_effect_rainbow.webp

彩虹讓文字呈現出隨時間變化的彩虹色, 它的標籤格式是 [rainbow freq=0.2 sat=10 val=20][/rainbow] . freq 是每秒完整的彩虹週期數, sat 是彩虹的飽和度, val 是彩虹的數值.

「freq」是每秒完整彩虹週期的數量,「sat」是彩虹的飽和度,「val」是彩虹的數值。 freq 值為``0`` 將暫停動畫,而負值``freq`` 將向後播放動畫。

字形輪廓「不受」彩虹效果的影響(它們保持原來的顏色)。現有的字形顏色被彩虹效果覆蓋。但是,CanvasItem 的 ModulateSelf Modulate 屬性將影響彩虹效果的外觀,因為調變會倍增其最終顏色。

自訂 BBCode 標籤和文字效果

可以通過擴充 RichTextEffect 資源型別來建立自己的 BBCode 標籤。首先擴充 RichTextEffect 資源型別並為腳本提供 class_name,這樣就能夠在屬性面板中選擇該效果。如果想在編輯器中運作這些自訂效果,請在 GDScript 檔中新增 @tool 注解。RichTextLabel 不需要附加腳本,也不需要在 tool 模式下運作。註冊效果的方法是將這個新建的效果在屬性面板中加入到 Markup > Custom Effects 陣列中,或者在程式碼中使用 install_effect() 方法:

儲存使用「class_name」擴充 RichTextEffect 的腳本後選擇自訂 RichTextEffect

儲存使用「class_name」擴充 RichTextEffect 的腳本後選擇自訂 RichTextEffect

警告

如果自訂效果沒有註冊到 RichTextLabel 的 Custom Effects 屬性中,就不會有可見的效果,保留原始的標籤。

只需要擴充一個函式: _process_custom_fx(char_fx) , 或者可以通過新增成員名稱 bbcode 來提供自訂BBCode識別字, 該程式碼將自動檢查bbcode屬性, 或使用檔案名來決定BBCode標籤應該是什麼.

_process_custom_fx

這是每個效果的邏輯生效的地方, 在文字渲染繪製階段, 每個字元被呼叫一次, 將傳入一個 CharFXTransform 物件, 該物件擁有一些變數來控制相關字元的渲染方式:

  • identity身份 指定正在處理哪個自訂效果, 應該用它來控制程式碼流程.

  • 如果呼叫效果來繪製文字輪廓,則「outline」為「true」。

  • relative_index 告訴你在一個給定的自訂效果區塊中的索引有多遠.

  • elapsed_time 是文字效果運作的總時間.

  • visible 將告訴你這個字元是否可見, 也允許你隱藏文字的某個部分.

  • offset 是相對於給定字元在正常情況下應該呈現的位置的偏移位置.

  • color 是一種預先規定的字元顏色.

  • “glyph_index” 和 “font” 是正在繪製的字形和用於繪製它的字形資料資源。

  • 最後, env 是一個指定自訂效果的參數 Dictionary . 如果使用者指定, 您可以使用 Get() 和可選預設值來檢索每個參數. 例如, [custom_fx spread=0.5 color=#FFFF00]test[/custom_fx] 在其 env 字典中將有一個浮動 spread 和顏色 color 參數. 有關更多的實例用法, 請參閱下面的內容.

最後需要注意的關於此函式, 必須返回一個布林值 true , 以驗證結果處理正確, 這樣一來, 如果這個預先規定的字元渲染出現問題, 它將完全退出自訂渲染的效果, 直到使用者修復自訂渲染出現的任何錯誤.

以下是一些自訂效果的範例:

幽靈

@tool
extends RichTextEffect
class_name RichTextGhost

# Syntax: [ghost freq=5.0 span=10.0][/ghost]

# Define the tag name.
var bbcode = "ghost"

func _process_custom_fx(char_fx):
    # Get parameters, or use the provided default value if missing.
    var speed = char_fx.env.get("freq", 5.0)
    var span = char_fx.env.get("span", 10.0)

    var alpha = sin(char_fx.elapsed_time * speed + (char_fx.range.x / span)) * 0.5 + 0.5
    char_fx.color.a = alpha
    return true

矩陣

@tool
extends RichTextEffect
class_name RichTextMatrix

# Syntax: [matrix clean=2.0 dirty=1.0 span=50][/matrix]

# Define the tag name.
var bbcode = "matrix"

# Gets TextServer for retrieving font information.
func get_text_server():
    return TextServerManager.get_primary_interface()

func _process_custom_fx(char_fx):
    # Get parameters, or use the provided default value if missing.
    var clear_time = char_fx.env.get("clean", 2.0)
    var dirty_time = char_fx.env.get("dirty", 1.0)
    var text_span = char_fx.env.get("span", 50)

    var value = char_fx.glyph_index

    var matrix_time = fmod(char_fx.elapsed_time + (char_fx.range.x / float(text_span)), \
                           clear_time + dirty_time)

    matrix_time = 0.0 if matrix_time < clear_time else \
                  (matrix_time - clear_time) / dirty_time

    if matrix_time > 0.0:
        value = int(1 * matrix_time * (126 - 65))
        value %= (126 - 65)
        value += 65
    char_fx.glyph_index = get_text_server().font_get_glyph_index(char_fx.font, 1, value, 0)
    return true

這將增加一些新的BBCode命令, 可以像這樣使用:

[center][ghost]This is a custom [matrix]effect[/matrix][/ghost] made in
[pulse freq=5.0 height=2.0][pulse color=#00FFAA freq=2.0]GDScript[/pulse][/pulse].[/center]