BBCode в RichTextLabel

Введение

Узлы Label отлично подходят для отображения простого текста, но у них есть ограничения. Изменить цвет текста или его выравнивание можно только для всей надписи. Нельзя изменить цвет части текста или выровнять её по центру. Чтобы обойти эти ограничения, можно использовать RichTextLabel.

RichTextLabel позволяет осуществлять сложное форматирование текста с помощью синтаксиса разметки или встроенного API. Для синтаксиса разметки используются BBCodes — система тегов, определяющих правила форматирования фрагментов текста. Возможно, вы знакомы с ними, если когда-либо пользовались форумами (также известными как bulletin boards, отсюда и «BB» в «BBCode»).

В отличие от Label, RichTextLabel также имеет собственную вертикальную полосу прокрутки. Эта полоса прокрутки автоматически отображается, если текст не помещается в область элемента управления. Полосу прокрутки можно отключить, сняв флажок Scroll Active в инспекторе RichTextLabel.

Обратите внимание, что теги BBCode также можно использовать в некоторой степени и для других случаев использования:

• BBCode можно использовать для форматирования комментариев в XML-источнике ссылки на класс.

• BBCode можно использовать в комментариях документации GDScript.

• BBCode можно использовать при печати форматированного текста на нижней панели вывода.

См. также

Вы можете увидеть, как работает BBCode в RichTextLabel, используя демонстрационный проект Rich Text Label with BBCode.

Использование BBCode

По умолчанию RichTextLabel функционирует как обычный Label. У него есть свойство property_text, которое можно редактировать для получения единообразно отформатированного текста. Чтобы использовать BBCode для форматирования текста, необходимо включить режим BBCode, установив bbcode_enabled. После этого можно редактировать свойство text, используя доступные теги. Оба свойства расположены в верхней части инспектора после выбора узла RichTextLabel.

Например, BBCode [color=green]test[/color] отобразит слово "test" зеленым цветом.

Большинство BBCode состоят из трёх частей: открывающего тега, содержимого и закрывающего тега. Открывающий тег определяет начало форматируемой части и может содержать некоторые параметры конфигурации. Некоторые открывающие теги, например, color, показанный выше, также требуют значения для работы. Другие открывающие теги могут принимать несколько параметров (разделённых пробелами внутри открывающего тега). Закрывающий тег определяет конец форматируемой части. В некоторых случаях и закрывающий тег, и содержимое можно опустить.

В отличие от BBCode в HTML, 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]

Безопасная обработка пользовательского ввода

В ситуации, когда пользователи могут свободно вводить текст (например, в чате многопользовательской игры), следует убедиться, что пользователи не могут использовать произвольные теги BBCode, которые будут обработаны RichTextLabel. Это необходимо для предотвращения ненадлежащего использования форматирования, которое может привести к проблемам, если теги [url] обрабатываются вашим RichTextLabel (поскольку игроки могут создавать кликабельные ссылки на фишинговые сайты и т.п.).

Используя теги [lb] and/or [rb] класса RichTextLabel, мы можем заменить открывающие и/или закрывающие скобки любого тега BBCode в сообщении этими экранированными тегами. Это предотвращает использование пользователями BBCode, которые будут интерпретированы как теги — вместо этого BBCode будет отображаться как текст.

Пример неэкранированного пользовательского ввода, приводящего к внедрению 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 в другом элементе управления, не поддерживающем BBCode (например, во всплывающей подсказке):

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.

Есть несколько способов облегчить эту ситуацию:

• Используйте функцию append_text() вместо добавления к свойству text. Эта функция анализирует только BBCode добавленного текста, а не весь BBCode свойства text.

• Используйте функции push_[tag]() и pop() для добавления тегов в RichTextLabel вместо использования BBCode.

• Включите свойство Threading > Threaded в RichTextLabel. Это не ускорит обработку, но предотвратит блокировку основного потока, что позволит избежать подтормаживаний во время игры. Включайте многопоточность только в том случае, если она действительно необходима в вашем проекте, так как она влечёт за собой некоторые накладные расходы.

Использование функций push_[tag]() и pop() вместо BBCode

Если вы не хотите использовать BBCode по соображениям производительности, вы можете использовать функции, предоставляемые RichTextLabel, для создания тегов форматирования без написания BBCode в тексте.

У каждого тега BBCode (включая эффекты) есть функция push_[tag]() (где [tag] — имя тега). Также доступно несколько вспомогательных функций, например, push_bold_italics(), которая объединяет push_bold() и push_italics() в один тег. Полный список функций push_[tag]() см. в справочнике по RichTextLabel class reference.

Функция pop() используется для завершения любого тега. Поскольку BBCode — это стек тегов, использование 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 сотрет все изменения, внесённые в RichTextLabel с помощью функций append_text(), push_[tag]() и pop().

Rеference

См. также

Некоторые из этих тегов BBCode можно использовать в подсказках для переменных скрипта @export, а также в исходном XML-коде ссылки на класс. Подробнее см. Ссылка на класс BBCode.

Тег	Пример
b Заставляет {text} использовать жирный (или жирный курсив) шрифт RichTextLabel.	[b]{text}[/b]
i Заставляет {text} использовать курсив (или полужирный курсив) шрифта RichTextLabel.	[i]{text}[/i]
u Делает {text} подчеркнутым.	[u]{text}[/u] [u color={color}]{text}[/u]
s Делает {text} зачеркнутым.	[s]{text}[/s] [s color={color}]{text}[/s]
code Заставляет {text} использовать монохромный шрифт RichTextLabel.	[code]{text}[/code]
char Добавляет символ Unicode с шестнадцатеричным кодом UTF-32 {codepoint}.	[char={codepoint}]
p Добавляет новый абзац с {text}. Поддерживает параметры конфигурации, см. Параметры абзаца.	[p]{text}[/p] [p {options}]{text}[/p]
br Добавляет перенос строки в текст без добавления нового абзаца. При использовании в списке новый элемент списка не создаётся, а вместо этого добавляет перенос строки в текущий элемент.	[br]
hr Добавляет новую горизонтальную линию для разделения контента. Поддерживает параметры конфигурации, см. Параметры горизонтальной линейки.	[hr] [hr {options}]
center Выравнивает {text} по горизонтали и центрирует. То же, что и [p align=center].	[center]{text}[/center]
left Выравнивает {text} по горизонтали и по левому краю. То же, что и [p align=left].	[left]{text}[/left]
right Выравнивает {text} по горизонтали и по правому краю. То же, что и [p align=right].	[right]{text}[/right]
fill Заставляет {text} заполнять всю ширину RichTextLabel. То же, что и [p align=fill].	[fill]{text}[/fill]
indent Добавляет отступ {text} один раз. Ширина отступа такая же, как у [ul] или [ol], но без маркера.	[indent]{text}[/indent]
url Creates a hyperlink (underlined and clickable text). Can contain optional {text} or display {link} as is. Supports configuration options, see URL options. Для достижения эффекта необходимо обрабатывать сигнал "meta_clicked", см. Обработка кликов по тегу [url].	[url]{link}[/url] [url={link}]{text}[/url] [url {options}]{text}[/url]
hint Создаёт подсказку, которая отображается при наведении курсора мыши на текст. Хотя это не обязательно, рекомендуется заключать текст подсказки в двойные или одинарные кавычки. Обратите внимание, что экранировать кавычки с помощью \" или \' невозможно. Чтобы использовать одинарные кавычки для апострофов в строке подсказки, необходимо заключить строку в двойные кавычки.	[hint="{текст подсказки, отображаемый при наведении курсора}"]{text}[/hint]
img Вставляет изображение из {path} (может быть любой допустимый ресурс Texture2D). Если указано {width}, изображение попытается соответствовать этой ширине, сохраняя соотношение сторон. Если указаны оба параметра {width} и {height}, изображение будет масштабировано до этого размера. Добавьте % в конец значения {width} или {height}, чтобы указать его в процентах от ширины элемента управления, а не в пикселях. Если указана конфигурация {valign}, изображение попытается выровняться по окружающему тексту, см. Вертикальное выравнивание изображения и таблицы. Поддерживает параметры конфигурации, см. Image options.	[img]{path}[/img] [img={width}]{path}[/img] [img={width}x{height}]{path}[/img] [img={valign}]{path}[/img] [img {options}]{path}[/img]
font Заставляет {text} использовать ресурс шрифта из {path}. Поддерживает параметры конфигурации, см. Параметры шрифта.	[font={path}]{text}[/font] [font {options}]{text}[/font]
font_size Используйте нестандартный размер шрифта для {text}.	[font_size={size}]{text}[/font_size]
dropcap Используйте другой размер и цвет шрифта для {text}, а содержимое тега, если оно достаточно большое, должно занимать несколько строк. Буквица обычно состоит из одного заглавного символа, но [dropcap] поддерживает несколько символов. Значения margins разделяются запятыми и могут быть положительными, нулевыми или отрицательными. Значения не должны быть разделены пробелами; в противном случае они будут обработаны неправильно. Отрицательные верхние и нижние поля особенно полезны, поскольку позволяют отображать оставшуюся часть абзаца под буквицей.	[dropcap font={font} font_size={size} color={color} outline_size={size} outline_color={color} margins={left},{top},{right},{bottom}]{text}[/dropcap]
opentype_features Включает пользовательские функции шрифта OpenType для {text}. Функции должны быть указаны в виде списка {list}, разделённого запятыми. Значения не должны быть разделены пробелами; в противном случае список не будет обработан корректно.	[opentype_features={list}] {text} [/opentype_features]
lang Переопределяет язык для {text}, заданный свойством BiDi > Language в RichTextLabel. {code} должен быть кодом языка ISO language code. Это можно использовать для принудительного использования определённой письменности для языка без начала нового абзаца. Некоторые файлы шрифтов могут содержать замены, специфичные для конкретной письменности, и в этом случае они будут использоваться.	[lang={code}]{text}[/lang]
color Изменяет цвет {text}. Цвет должен быть задан общим именем (см. Именованные цвета) или в HEX формате (например, #ff00ff, см. Шестнадцатеричные цветовые коды).	[color={code/name}]{text}[/color]
bgcolor Рисует цвет позади тега {text}. Это можно использовать для выделения текста. Принимает те же значения, что и тег color. По умолчанию есть небольшой отступ, который управляется элементами темы text_highlight_h_padding и text_highlight_v_padding в узле RichTextLabel. Установите отступ на 0, чтобы избежать возможных проблем с наложением фоновых цветов в соседних строках/столбцах.	[bgcolor={code/name}]{text}[/bgcolor]
fgcolor Рисует цвет перед {text}. Это можно использовать для «редактирования» текста с помощью непрозрачного цвета переднего плана. Принимает те же значения, что и тег color. По умолчанию есть небольшой отступ, который управляется элементами темы text_highlight_h_padding и text_highlight_v_padding в узле RichTextLabel. Установите отступ на 0, чтобы избежать возможных проблем с наложением при наличии цветов переднего плана в соседних строках/столбцах.	[fgcolor={code/name}]{text}[/fgcolor]
outline_size Используйте пользовательский размер контура шрифта для {text}.	[outline_size={size}] {text} [/outline_size]
outline_color Использовать пользовательский цвет контура для {text}. Принимает те же значения, что и тег color.	[outline_color={code/name}] {text} [/outline_color]
table Создаёт таблицу с {number} числом столбцов. Для определения ячеек таблицы используйте тег cell. Если указана конфигурация {valign}, таблица попытается выровняться по окружающему тексту, см. Вертикальное выравнивание изображения и таблицы. Если используется выравнивание по базовой линии, таблица выравнивается по базовой линии строки с индексом {alignment_row} (с нуля). {name} is a table name for assistive apps (screen reader).	[table={number}]{cells}[/table] [table={number},{valign}]{cells}[/table] [table={number},{valign},{alignment_row}]{cells}[/table] [table={number},{valign},{alignment_row} name={name}]{cells}[/table]
cell Добавляет ячейку с {text} в таблицу. Если указано {ratio}, ячейка попытается расшириться до этого значения пропорционально другим ячейкам и их значениям отношения. Поддерживает параметры конфигурации, см. Параметры ячеек.	[cell]{text}[/cell] [cell={ratio}]{text}[/cell] [cell {options}]{text}[/cell]
ul Добавляет неупорядоченный список. Список {items} должен быть представлен одним элементом в каждой строке текста. Маркер можно настроить с помощью параметра {bullet}, см. Маркер неупорядоченного списка.	[ul]{items}[/ul] [ul bullet={bullet}]{items}[/ul]
ol Добавляет упорядоченный (нумерованный) список указанного {type} (см. Типы упорядоченных списков). Список {items} должен быть представлен путем размещения одного элемента на каждой строке текста.	[ol type={type}]{items}[/ol]
lb, 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] (объединитель слов), [shy] (мягкий дефис)

Примечание

Теги для форматирования жирным шрифтом ([b]) и курсивом ([i]) работают лучше всего, если соответствующие пользовательские шрифты настроены в переопределениях темы RichTextLabelNode. Если пользовательские полужирные или курсивные шрифты не определены, Godot сгенерирует поддельные жирные и курсивные шрифты. Такие шрифты редко выглядят хорошо по сравнению с вариантами жирного или курсивного шрифтов, созданными вручную.

Моноширинный тег ([code]) работает только, если в переопределениях темы узла RichTextLabel настроен пользовательский шрифт. В противном случае для моноширинного текста будет использоваться обычный шрифт.

Тегов BBCode для управления вертикальным центрированием текста пока нет.

Опции могут быть пропущены для всех тегов.

Параметры абзаца

• align

  Values	left (или l), center (или c), right (или r), fill (или f)
  Default	left

  Горизонтальное выравнивание текста.

• bidi_override, st

  Values	default (из d), uri (или u), file (или f), email (или e), list (или l), none (или n), custom (или c)
  Default	default

  Переопределение структурированного текста.

• justification_flags, jst

  Values	Список следующих значений, разделенных запятыми (без пробела после каждой запятой): kashida (или k), word (или w), trim (или tr), after_last_tab (или lt), skip_last (или sl), skip_last_with_chars (или sv), do_not_skip_single (или ns).
  Default	word,kashida,skip_last,do_not_skip_single

  Параметр выравнивания (заполнения). Подробнее см. TextServer.

• direction, dir

  Values	ltr (или l), rtl (или r), auto (или a)
  Default	Inherit (Наследовать)

  Базовое направление BiDi.

• language, lang

  Values	Коды языков ISO. См. Коды локалей (языков)
  Default	Inherit (Наследовать)

  Переопределение локали. Некоторые файлы шрифтов могут содержать специфичные для системы замены, и в этом случае они будут использоваться.

• tab_stops

  Values	Список чисел с плавающей точкой, например, 10.0,30.0
  Default	Ширина символа пробела в шрифте

  Переопределяет горизонтальные смещения для каждого символа табуляции. При достижении конца списка позиции табуляции будут циклически смещены. Например, если задать tab_stops равным 10.0,30.0, первая табуляция будет находиться на отметке 10 пикселей, вторая — на отметке 10 + 30 = 40 пикселей, а третья — на отметке 10 + 30 + 10 = 50 пикселей от начала RichTextLabel.

Обработка кликов по тегу [url]

По умолчанию теги [url] не выполняют никаких действий при нажатии. Это сделано для того, чтобы обеспечить гибкое использование тегов [url], а не ограничивать их открытием URL-адресов в веб-браузере.

Для обработки нажатых тегов [url] подключите сигнал meta_clicked узла RichTextLabel к функции скрипта.

Например, следующий метод можно подключить к 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 runtime.
    OS.shell_open(str(meta))

Для более сложных случаев использования можно также сохранить JSON в параметре тега [url] и проанализировать его в функции, обрабатывающей сигнал meta_clicked. Например:

[url={"example": "value"}]JSON[/url]

Параметры горизонтальной линейки

• color

  Values	Название цвета или цвет в шестнадцатеричном (HEX) формате
  Default	Color(1, 1, 1, 1)

  Цветовой оттенок правила (модуляция).

• lіght_only

  Values	Integer number (Целое число)
  Default	2

  Целевая высота линейки в пикселях. Добавьте % в конец значения, чтобы указать ее в процентах от ширины элемента управления, а не в пикселях.

• width

  Values	Integer number (Целое число)
  Default	90%

  Целевая ширина линейки в пикселях. Добавьте % в конец значения, чтобы указать ее в процентах от ширины элемента управления, а не в пикселях.

• align

  Values	left (или l), center (или c), right (или r)
  Default	left

  Горизонтальное выравнивание.

URL options

• underline

  Values	always, never, hover
  Default	always

  URL underlining mode.

• tooltip

  Values	String.
  Default

  URL tooltip.

• href

  Values	String.
  Default

  URL target address.

Image options

• color

  Values	Название цвета или цвет в шестнадцатеричном (HEX) формате
  Default	Inherit (Наследовать)

  Цветовой оттенок изображения (модуляция).

• lіght_only

  Values	Integer number (Целое число)
  Default	Inherit (Наследовать)

  Целевая высота изображения в пикселях. Добавьте % в конец значения, чтобы указать ее в процентах от ширины элемента управления, а не в пикселях.

• width

  Values	Integer number (Целое число)
  Default	Inherit (Наследовать)

  Целевая ширина изображения в пикселях. Добавьте % в конец значения, чтобы указать его в процентах от ширины элемента управления, а не в пикселях.

• region

  Values	x,y,ширина,высота в пикселях
  Default	Inherit (Наследовать)

  Прямоугольная область изображения. Может использоваться для отображения одного изображения из таблицы спрайтов.

• pad

  Values	false, true
  Default	false

  Если установлено значение true, а изображение меньше размера, указанного width и height, то вместо масштабирования к изображению добавляется отступ для соответствия размеру.

• tooltip

  Values	Строка
  Default

  Подсказка к изображению.

• alt

  Values	see Вертикальное выравнивание изображения и таблицы
  Default	center,center

  Image alignment to the surrounding text.

• alt

  Values	Строка
  Default

  Image description for assistive apps (screen reader).

Вертикальное выравнивание изображения и таблицы

Если значение вертикального выравнивания указано с помощью тега [img] или [table], изображение/таблица попытается выровняться относительно окружающего текста. Выравнивание выполняется по вертикальной точке изображения и вертикальной точке текста. Возможны три точки на изображении (top, center и bottom) и четыре точки на тексте и таблице (top, center, baseline и bottom), которые можно использовать в любой комбинации.

Чтобы указать обе точки, используйте их полные или краткие названия в качестве значения тега изображения/таблицы:

text [img=top,bottom]...[/img] text
text [img=center,center]...[/img] text

text [table=3,center]...[/table] text  # Center to center.
text [table=3,top,bottom]...[/table] text # Top of the table to the bottom of text.
text [table=3,baseline,baseline,1]...[/table] text # Baseline of the second row (rows use zero-based indexing) to the baseline of text.

Вы также можете указать только одно значение (top, center или bottom), чтобы использовать соответствующую предустановку (top-top, center-center и bottom-bottom соответственно).

Короткие названия значений: t (top), c (center), l (baseline) и b (bottom).

Параметры шрифта

• name, n

  Values	Допустимый путь к ресурсу шрифта.
  Default	Inherit (Наследовать)

  Путь к ресурсам шрифта.

• size, s

  Values	Число в пикселях.
  Default	Inherit (Наследовать)

  Пользовательский размер шрифта.

• glyph_spacing, gl

  Values	Число в пикселях.
  Default	Inherit (Наследовать)

  Дополнительный интервал для каждого глифа.

• space_spacing, sp

  Values	Число в пикселях.
  Default	Inherit (Наследовать)

  Дополнительный интервал для символа пробела.

• top_spacing, top

  Values	Число в пикселях.
  Default	Inherit (Наследовать)

  Дополнительный интервал в верхней части строки.

• bottom_spacing, bt

  Values	Число в пикселях.
  Default	Inherit (Наследовать)

  Дополнительный интервал внизу строки.

• embolden, emb

  Values	Число с плавающей точкой.
  Default	0.0

  Значение параметра Font embolden Strength (утолщение шрифта): если оно не равно нулю, то контуры шрифта становятся жирнее. Отрицательные значения уменьшают толщину контуров.

• face_index, fi

  Values	Целое число.
  Default	0

  Активный индекс шрифтов в коллекции TrueType/OpenType.

• slant, sln

  Values	Число с плавающей точкой.
  Default	0.0

  Сила наклона шрифта: положительные значения наклоняют глифы вправо, отрицательные — влево.

• opentype_variation, otv

  Values	Список тегов вариаций OpenType, разделенных запятыми (без пробела после каждой запятой).
  Default

  Координаты вариантов шрифта OpenType. См. Теги вариантов OpenType.

  Примечание: значение должно быть заключено в ", чтобы можно было использовать = внутри него:

[font otv="wght=200,wdth=400"] # Sets variable font weight and width.

• opentype_features, otf

  Values	Список тегов функций OpenType, разделенных запятыми (без пробела после каждой запятой).
  Default

  Возможности OpenType шрифтов. См. Теги возможностей OpenType.

  Примечание: значение должно быть заключено в ", чтобы можно было использовать = внутри него:

[font otf="calt=0,zero=1"] # Disable contextual alternates, enable slashed zero.

Именованные цвета

Для тегов, позволяющих задать цвет по имени, можно использовать имена констант из встроенного класса Color. Именованные классы можно указывать в различных стилях с использованием разных регистров: DARK_RED, DarkRed и darkred дадут один и тот же результат.

Список цветовых констант смотрите на этом изображении:

Просмотреть в полном размере

Шестнадцатеричные цветовые коды

Для непрозрачных цветов RGB поддерживается любой допустимый 6-значный шестнадцатеричный код, например, [color=#ffffff]white[/color]. Также поддерживаются сокращённые коды цветов RGB, такие как #6f2 (эквивалентно #66ff22).

Для прозрачных цветов RGB можно использовать любой 8-значный шестнадцатеричный код RGBA, например, [color=#ffffff88]прозрачный белый[/color]. Обратите внимание, что альфа-канал — это последний компонент кода цвета, а не первый. Также поддерживаются короткие коды цветов RGBA, такие как #6f28 (эквивалент #66ff2288).

Параметры ячеек

• shrink

  Values	false, true
  Default	true

  If true, cell can shrink to its contents.

• expand

  Values	Integer number (Целое число)
  Default	1

  Коэффициент расширения ячеек. Этот параметр определяет, какие ячейки будут пытаться расшириться пропорционально другим ячейкам и их коэффициентам расширения.

• border

  Values	Название цвета или цвет в шестнадцатеричном (HEX) формате
  Default	Inherit (Наследовать)

  Цвет границы ячейки.

• bg

  Values	Название цвета или цвет в шестнадцатеричном (HEX) формате
  Default	Inherit (Наследовать)

  Цвет фона ячейки. Для чередования фона чётных и нечётных строк можно использовать bg=odd_color,even_color.

• padding

  Values	4 числа с плавающей точкой, разделенных запятыми (без пробела после каждой запятой)
  Default	0,0,0,0

  Отступы ячеек слева, сверху, справа и снизу.

Маркер неупорядоченного списка

По умолчанию тег [ul] использует в качестве символа маркера глиф Unicode U+2022 "Bullet". Это поведение аналогично веб-браузерам. Символ маркера можно настроить с помощью [ul bullet={bullet}]. Если указан параметр {bullet}, он должен быть строкой без кавычек (например, [bullet=*]). Вы можете добавить пробелы после символа маркера, чтобы увеличить расстояние между маркером и текстом элемента списка.

См. Bullet (типографика) в Википедии для получения списка распространенных символов маркеров, которые можно вставить непосредственно в параметр bullet.

Типы упорядоченных списков

Упорядоченные списки можно использовать для автоматической маркировки элементов цифрами или буквами в порядке возрастания. Этот тег поддерживает следующие типы:

• 1 - Числа, по возможности с использованием специфической для языка системы нумерации.

• a, A - Строчные и прописные латинские буквы.

• i, I - Строчные и прописные римские цифры.

Текстовые эффекты

BBCode can also be used to create different text effects that can optionally be animated. Several customizable effects are provided out of the box, and you can easily create your own. By default, animated effects will pause when the SceneTree is paused. You can change this behavior by adjusting the RichTextLabel's Process > Mode property.

Во всех приведенных ниже примерах указаны значения по умолчанию для параметров в указанном формате тега.

Примечание

Текстовые эффекты, изменяющие положение символов, могут привести к тому, что символы будут обрезаны границами узла RichTextLabel.

Вы можете решить эту проблему, отключив Control > Layout > Clip Contents в инспекторе после выбора узла RichTextLabel или обеспечив достаточный отступ вокруг текста, используя разрывы строк выше и ниже строки с помощью эффекта.

Pulse (Эффект пульсации)

Эффект пульсации создаёт анимированный пульсирующий эффект, который увеличивает прозрачность и цвет каждого символа. Его можно использовать для привлечения внимания к определённому тексту. Формат тега: [pulse freq=1.0 color=#ffffff40 ease=-2.0]{text}[/pulse].

freq управляет частотой полупериода импульсов (чем выше, тем выше частота). Полный цикл импульсов занимает 2 * (1.0 / freq) секунд. color — целевой цветовой множитель для мигания. Значение по умолчанию почти полностью затухает текст, но не полностью. ease — показатель степени функции плавности. Отрицательные значения обеспечивают плавность при приближении и удалении, поэтому значение по умолчанию равно -2.0.

Wave (Волна)

Wave заставляет текст двигаться вверх и вниз. Формат тега: [wave amp=50.0 freq=5.0 connected=1]{text}[/wave].

amp управляет высотой и полом эффекта, а freq — скоростью подъёма и спада текста. Значение freq, равное 0, не создаст видимых волн, а отрицательные значения freq также не будут отображать никаких волн. Если connected равно 1 (по умолчанию), глифы с лигатурами будут перемещаться вместе. Если connected равно 0, каждый глиф перемещается отдельно, даже если они соединены лигатурами. Это может помочь обойти некоторые проблемы с отображением лигатур шрифтов.

Tornado (Торнадо)

Торнадо заставляет текст двигаться по кругу. Формат тега: [tornado radius=10.0 freq=1.0 connected=1]{text}[/tornado].

radius — это радиус окружности, управляющий смещением, freq — это скорость перемещения текста по окружности. Значение freq, равное 0, приостановит анимацию, а отрицательное значение freq будет воспроизводить её в обратном порядке. Если connected равно 1 (по умолчанию), глифы с лигатурами будут перемещаться вместе. Если connected равно 0, каждый глиф перемещается отдельно, даже если они соединены лигатурами. Это может помочь обойти некоторые проблемы с отображением лигатур шрифтов.

Shake (Встряхнуть)

Shake заставляет текст дрожать. Формат тега: [shake rate=20.0 level=5 connected=1]{text}[/shake].

rate управляет скоростью дрожания текста, level — смещением текста от начала координат. Если connected равно 1 (по умолчанию), глифы с лигатурами будут перемещаться вместе. Если connected равно 0, каждый глиф перемещается индивидуально, даже если они соединены лигатурами. Это может помочь обойти некоторые проблемы с отображением лигатур шрифтов.

Fade (Тускнеть)

Эффект плавного перехода создаёт статический эффект плавного перехода, увеличивая прозрачность каждого символа. Формат тега: [fade start=4 length=14]{text}[/fade].

start управляет начальной позицией затухания относительно места вставки команды затухания, length управляет количеством символов, на которые должно быть нанесено затухание.

Rainbow (Радуга)

Rainbow придаёт тексту радужный цвет, который меняется со временем. Формат тега: [rainbow freq=1.0 sat=0.8 val=0.8 speed=1.0]{text}[/rainbow].

freq определяет количество букв, на которые распространяется радуга, прежде чем она повторится, sat — насыщенность радуги, val — яркость радуги. speed — количество полных циклов радуги в секунду. Положительное значение speed воспроизводит анимацию вперёд, значение 0 приостанавливает анимацию, а отрицательное значение speed воспроизводит анимацию назад.

Эффект радуги не влияет на контуры шрифтов (они сохраняют свой исходный цвет). Существующие цвета шрифта переопределяются эффектом радуги. Однако свойства Modulate и Self Modulate объекта CanvasItem влияют на внешний вид эффекта радуги, поскольку модуляция умножает его конечные цвета.

Пользовательские теги BBCode и текстовые эффекты

Вы можете расширить тип ресурса RichTextEffect, чтобы создать собственные теги BBCode. Создайте новый файл скрипта, расширяющий тип ресурса RichTextEffect, и присвойте скрипту class_name, чтобы эффект можно было выбрать в инспекторе. Добавьте аннотацию @tool в файл GDScript, если хотите, чтобы эти пользовательские эффекты запускались в самом редакторе. RichTextLabel не требует присоединения скрипта и не должен запускаться в режиме tool. Новый эффект можно зарегистрировать в инспекторе, добавив его в массив Markup > Custom Effects или в коде с помощью метода install_effect():

Выбор пользовательского RichTextEffect после сохранения скрипта, расширяющего RichTextEffect с помощью class_name

Предупреждение

Если пользовательский эффект не зарегистрирован в свойстве RichTextLabel Markup > Custom Effects, эффект не будет виден, а исходный тег останется как есть.

Вам нужно расширить только одну функцию: _process_custom_fx(char_fx). При желании вы также можете указать собственный идентификатор BBCode, добавив имя элемента bbcode. Код автоматически проверит свойство bbcode или будет использовать имя файла для определения необходимого тега BBCode.

_process_custom_fx

Именно здесь реализуется логика каждого эффекта, которая вызывается один раз для каждого глифа во время фазы отрисовки при рендеринге текста. При этом передается объект CharFXTransform, содержащий несколько переменных для управления рендерингом соответствующего глифа:

• outline имеет значение true, если эффект вызывается для рисования контура текста.

• range сообщает в виде индекса, как далеко вы находитесь в заданном блоке пользовательских эффектов.

• elapsed_time — это общее время, в течение которого работает текстовый эффект.

• visible сообщает, виден ли глиф, а также позволяет скрыть заданную часть текста.

• offset — это позиция смещения относительно того места, где данный глиф должен отображаться при обычных обстоятельствах.

• color — это цвет данного глифа.

• glyph_index — это индекс отрисовываемого глифа, а font — ресурс шрифта, используемый для его отрисовки.

• Наконец, env — это Dictionary параметров, назначенных данному пользовательскому эффекту. Вы можете использовать метод get() с необязательным значением по умолчанию для извлечения каждого параметра, если он указан пользователем. Например, [custom_fx spread=0.5 color=#FFFF00]test[/custom_fx] будет иметь параметры spread типа float и color типа Color в своём словаре env. Дополнительные примеры использования смотрите ниже.

Последнее, что следует отметить в этой функции, — это то, что необходимо возвращать булево значение true для подтверждения корректной обработки эффекта. Таким образом, если при рендеринге глифа возникнет проблема, отрисовка пользовательских эффектов будет полностью прекращена до тех пор, пока пользователь не исправит ошибку, возникшую в логике его пользовательского эффекта.

Вот несколько примеров пользовательских эффектов:

Ghost (Призрак)

@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

Matrix (Матрица)

@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 = get_text_server().font_get_char_from_glyph_index(char_fx.font, 1, 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]