Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

BBCode у RichTextLabel

Вступ

Вузли Label чудово підходять для відображення основного тексту, але вони мають обмеження. Якщо ви хочете змінити колір тексту або його вирівнювання, ви можете зробити це лише для всієї мітки. Ви не можете зробити частину тексту іншим кольором або вирівняти частину тексту по центру. Щоб обійти ці обмеження, ви повинні використовувати RichTextLabel.

RichTextLabel дозволяє виконувати складне форматування тексту за допомогою синтаксису розмітки або вбудованого API. Він використовує коди BBCodes для синтаксису розмітки, систему тегів, які визначають правила форматування для частини тексту. Можливо, ви з ними знайомі, якщо колись користувалися форумами (також відомими як «дошки оголошень», звідси «BB» у «BBCode»).

На відміну від Label, RichTextLabel також має власну вертикальну смугу прокручування. Ця смуга прокручування автоматично відображається, якщо текст не вміщується в розмір елемента керування. Смугу прокручування можна вимкнути, знявши прапорець біля властивості Scroll Active в інспекторі RichTextLabel.

Note that the BBCode tags can also be used to some extent for other use cases:

Дивись також

Ви можете побачити, як BBCode у RichTextLabel працює в дії, використовуючи демонстраційний проект Rich Text Label with BBCode.

Використання BBCode

За замовчуванням RichTextLabel функціонує як звичайний Label. Він має властивість property_text, яку ви можете редагувати, щоб мати однорідно відформатований текст. Щоб мати можливість використовувати BBCode для форматування форматованого тексту, вам потрібно ввімкнути режим BBCode, встановивши bbcode_enabled. Після цього ви можете редагувати властивість text за допомогою доступних тегів. Обидві властивості розташовані у верхній частині інспектора після вибору вузла RichTextLabel.

../../_images/bbcode_in_richtextlabel_inspector.webp

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

../../_images/bbcode_in_richtextlabel_basic_example.webp

Більшість BBCodes складається з 3 частин: початкового тегу, вмісту та закриваючого тегу. Відкриваючий тег розмежовує початок відформатованої частини, а також може містити деякі параметри конфігурації. Деякі відкриваючі теги, як-от показаний вище 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 (оскільки гравці можуть створювати активні посилання на фішингові сайти тощо).

Використовуючи теги 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 в іншому елементі керування, який не підтримує 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() в один тег. Перегляньте посилання на клас RichTextLabel для повного списку функцій push_[tag]().

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

Зразок

Дивись також

Деякі з цих тегів BBCode можна використовувати у підказках для змінних сценарію @export, а також у джерелі XML посилання на клас. Для отримання додаткової інформації див. Посилання на клас BBCode.

Теґ

Приклад

b
Використовує для {text} жирний (або жирний курсив) шрифт RichTextLabel.

[b]{текст}[/b]

i
Змушує {text} використовувати курсив (або жирний курсив) шрифту RichTextLabel.

[i]{текст}[/i]

u
Робить {text} підкресленим.

[u]{текст}[/u]

s
Робить {текст} закресленим.

[s]{текст}[/s]

код
Змушує {text} використовувати монофонічний шрифт RichTextLabel.

[code]{текст}[/code]

символ
Додає символ Unicode із шістнадцятковим UTF-32 {codepoint}.

[char={codepoint}]

p
Додає новий абзац із {text}. Підтримує параметри конфігурації, див. Параметри абзацу.
[p]{текст}[/p]
[p {options}]{text}[/p]
центр
Робить {text} горизонтально по центру.
Те саме, що [p align=center].

[center]{текст}[/center]

left
Робить {text} горизонтальним вирівнюванням за лівим краєм.
Те саме, що [p align=left].

[left]{текст}[/left]

праворуч
Робить {text} горизонтально вирівняним за правим краєм.
Те саме, що [p align=right].

[right]{текст}[/right]

заповнення
Змушує {text} заповнювати всю ширину RichTextLabel.
Те саме, що [p align=fill].

[fill]{заповнення}[/fill]

відступ
Відступ {text} один раз. Ширина відступу така ж, як і для [ul] або [ol], але без маркера.

[indent]{текст}[/indent]

адреса
Створює гіперпосилання (підкреслений текст, який можна натиснути). Може містити необов’язковий {text} або відображати {link} як є.
Потрібно обробляти сигнал "meta_clicked", щоб мати ефект, див. Обробка кліків тегом [url].
[url]{link}[/url]
[url={link}]{text}[/url]
hint
Створює підказку підказки, яка відображається при наведенні миші на текст. Текст спливаючої підказки не повинен брати в лапки (інакше лапки відображатимуться як є у спливаючій підказці).
[hint={tooltip text displayed on hover}]{text}[/hint]
img
Вставляє зображення з {path} (може бути будь-яким дійсним ресурсом Texture2D).
Якщо вказано {width}, зображення намагатиметься відповідати цій ширині, зберігаючи співвідношення сторін.
Якщо надано і {width}, і {height}, зображення буде масштабовано до цього розміру.
Додайте % до кінця значення {width} або {height}, щоб указати його у відсотках від ширини елемента керування замість пікселів.
Якщо надається конфігурація {valign}, зображення спробує вирівняти навколишній текст, див. Вертикальне вирівнювання зображення та таблиці.
Підтримує параметри конфігурації, див. Параметри зображення.
[img]{шлях}[/img]
[img={width}]{path}[/img]
[img={width}x{height}]{path}[/img]
[img={valign}]{path}[/img]
[img {options}]{path}[/img]
шрифт
Змушує {text} використовувати ресурс шрифту з {path}.
Підтримує параметри конфігурації, див. Параметри шрифту.
[font={path}]{text}[/font]
[font {options}]{text}[/font]
font_size
Використовуйте спеціальний розмір шрифту для {text}.

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

dropcap
Використовуйте інший розмір і колір шрифту для {text}, а вміст тегу має займати кілька рядків, якщо він достатньо великий.
Буквиця <https://www.computerhope.com/jargon/d/dropcap.htm>`__ зазвичай є одним великим символом, але [dropcap] підтримує кілька символів. Значення margin розділяються комами та можуть бути додатними, нульовими або від’ємними. Негативні верхнє та нижнє поля особливо корисні, щоб дозволити решті абзацу відображатися під заголовком.

[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}. Функції мають бути надані у вигляді {списку}, розділених комами.
[opentype_features={list}]
{text}
[/opentype_features]
lang
Замінює мову для {text}, встановлену властивістю BiDi > Language у RichTextLabel. {code} має бути ISO кодом мови. Це можна використати для примусового використання певного сценарію для мови без початку нового абзацу. Деякі файли шрифтів можуть містити замінники, специфічні для сценарію, і в цьому випадку вони будуть використані.

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

колір
Змінює колір {text}. Колір має бути надано загальною назвою (див. Названі кольори) або у форматі HEX (наприклад, #ff00ff, див. Шістнадцяткові коди кольорів).

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

bgcolor
Малює колір позаду {text}. Це можна використовувати для виділення тексту. Приймає ті самі значення, що й тег color.

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

fgcolor
Малює колір перед {text}. Це можна використовувати для "редагування" тексту за допомогою непрозорого кольору переднього плану. Приймає ті самі значення, що й тег color.

[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} (від нуля).
[table={number}]{cells}[/table]
[table={number},{valign}]{cells}[/table]
[table={number},{valign},{alignment_row}]{cells}[/table]
cell
Додає клітинку з {text} до таблиці.
Якщо вказано {ratio}, клітинка намагатиметься розширити до цього значення пропорційно до інших клітинок та їхніх значень співвідношення.
Підтримує параметри конфігурації, див. Варіанти комірки.
`` [cell] {текст} [/cell] ``
[cell={ratio}]{text}[/cell]
[cell {options}]{text}[/cell]
ul
Додає невпорядкований список. Список {items} має бути наданий шляхом розміщення одного елемента на рядок тексту.
Точку маркера можна налаштувати за допомогою параметра {bullet}, див. Наведене вище зображення було створено за допомогою наступного скрипта.
[ul]{текст}[/ul]
[ul bullet={bullet}]{items}[/ul]
ol
Додає впорядкований (нумерований) список заданого {type} (див. Типи впорядкованих списків). Список {items} має бути наданий шляхом розміщення одного елемента на рядок тексту.

[ol type={type}]{items}[/ol]

lb, rb
Додає [ і ] відповідно. Дозволяє екранувати розмітку BBCode.
Це самозакриваючі теги, що означає, що вам не потрібно їх закривати (і немає закриваючих тегів [/lb] або [/rb]).
[lb]b[rb]текст[lb]/b[rb] відображатиметься як [b]текст[/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

    Цінності

    left (or l), center (or c), right (or r), fill (or f)

    Замовчуванням

    left

    Горизонтальне вирівнювання тексту.

  • Bidi_override, st

    Цінності

    default (of d), uri (or u), file (or f), email (or e), list (or l), none (or n), custom (or c)

    Замовчуванням

    Замовчуванням

    Перевизначення структурованого тексту.

  • Justification_flags, jst

    Цінності

    Список таких значень, розділених комами: kashida (або k), word (або w), trim (або tr) , after_last_tab (або lt), skip_last (або sl), skip_last_with_chars (або sv), do_not_skip_single (або ns).

    Замовчуванням

    word,kashida,skip_last,do_not_skip_single

    Опція вирівнювання (вирівнюванні заливки). Додаткову інформацію див. у TextServer.

  • Direction, dir

    Цінності

    ltr (or l), rtl (or r), auto (or a)

    Замовчуванням

    Успадкувати

    Базовий напрямок BiDi.

  • Language, lang

    Цінності

    Мовні коди ISO. Дивіться Локальні коди

    Замовчуванням

    Успадкувати

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

  • Tab_stops

    Цінності

    Список чисел з плаваючою комою, напр. 10.0,30.0

    Замовчуванням

    Ширина пробілу в шрифті

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

Обробка кліків тегом [url]

За замовчуванням теги [url] нічого не роблять після натискання. Це дозволяє гнучко використовувати теги [url], а не обмежувати їх відкриттям 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 runtime.
    OS.shell_open(str(meta))

Для більш складних випадків використання також можна зберігати JSON у параметрі тегу [url] і аналізувати його у функції, яка обробляє сигнал meta_clicked. Наприклад:

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

Параметри зображення

  • колір

    Цінності

    Назва кольору або колір у форматі HEX

    Замовчуванням

    Успадкувати

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

  • Height

    Цінності

    Ціле число

    Замовчуванням

    Успадкувати

    Цільова висота зображення в пікселях, додайте % до кінця значення, щоб вказати його у відсотках від контрольної ширини замість пікселів.

  • Width

    Цінності

    Ціле число

    Замовчуванням

    Успадкувати

    Цільова ширина зображення, додайте % до кінця значення, щоб вказати його у відсотках від контрольної ширини замість пікселів.

  • Region

    Цінності

    x,y,ширина,висота в пікселях

    Замовчуванням

    Успадкувати

    Область прямокутника зображення. Це можна використовувати для відображення окремого зображення зі спрайт-таблиці.

  • Неправильно

    Цінності

    false, true

    Замовчуванням

    false

    Якщо встановлено значення true і розмір зображення менший за розмір, визначений width і height, замість масштабування додається відступ зображення, щоб відповідати розміру.

  • tooltip

    Цінності

    Строка (рядок, текст)

    Замовчуванням

    Підказка зображення.

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

When a vertical alignment value is provided with the [img] or [table] tag the image/table will try to align itself against the surrounding text. Alignment is performed using a vertical point of the image and a vertical point of the text. There are 3 possible points on the image (top, center, and bottom) and 4 possible points on the text and table (top, center, baseline, and bottom), which can be used in any combination.

Щоб указати обидві точки, використовуйте їх повні або короткі назви як значення тегу зображення/таблиці:

text [img=top,bottom]...[/img] text
text [img=center,center]...[/img] text
../../_images/bbcode_in_richtextlabel_image_align.webp
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.
../../_images/bbcode_in_richtextlabel_table_align.webp

Ви також можете вказати лише одне значення (верх, центр або низ), щоб використовувати відповідний стиль (верх-верх, центр-центр , і bottom-bottom відповідно).

Короткі назви значень: t (верх), c (центр), l (базова лінія) і b` ` (``низ).

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

  • Name, n

    Цінності

    Дійсний шлях ресурсу шрифту.

    Замовчуванням

    Успадкувати

    Шлях до ресурсів шрифту.

  • Size, s

    Цінності

    Число в пікселях.

    Замовчуванням

    Успадкувати

    Нестандартний розмір шрифту.

  • Glyph_spacing, gl

    Цінності

    Число в пікселях.

    Замовчуванням

    Успадкувати

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

  • space_spacing, sp

    Цінності

    Число в пікселях.

    Замовчуванням

    Успадкувати

    Додатковий інтервал для символу пробілу.

  • Top_spacing, top

    Цінності

    Число в пікселях.

    Замовчуванням

    Успадкувати

    Додатковий інтервал у верхній частині рядка.

  • Bottom_spacing, bt

    Цінності

    Число в пікселях.

    Замовчуванням

    Успадкувати

    Додатковий інтервал у нижній частині рядка.

  • Embolden, emb

    Цінності

    Число з плаваючою комою.

    Замовчуванням

    0.0

    Сила підкреслення шрифту, якщо вона не дорівнює нулю, підкреслює контури шрифту. Від’ємні значення зменшують товщину контуру.

  • Face_index, fi

    Цінності

    Ціле число.

    Замовчуванням

    0

    Активний індекс обличчя в колекції TrueType / OpenType.

  • Slant, sln

    Цінності

    Число з плаваючою комою.

    Замовчуванням

    0.0

    Сила нахилу шрифту, позитивні значення нахиляють гліфи праворуч. Від’ємні значення ліворуч.

  • Opentype_variation, otv

    Цінності

    Розділений комами список тегів варіантів OpenType.

    Замовчуванням

    Координати варіації шрифту OpenType. Перегляньте Теги варіантів OpenType.

    Примітка: значення має бути укладено в ", щоб можна було використовувати = всередині нього:

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

    Цінності

    Розділений комами список тегів функцій OpenType.

    Замовчуванням

    Особливості шрифту OpenType. Перегляньте Теги функцій OpenType.

    Примітка: значення має бути укладено в ", щоб можна було використовувати = всередині нього:

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

Названі кольори

For tags that allow specifying a color by name, you can use names of the constants from the built-in Color class. Named classes can be specified in a number of styles using different casings: DARK_RED, DarkRed, and darkred will give the same exact result.

See this image for a list of color constants:

../../_images/color_constants.png

View at full size

Шістнадцяткові коди кольорів

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

Для прозорих кольорів RGB можна використовувати будь-який 8-значний шістнадцятковий код RGBA, напр. [color=#ffffff88]напівпрозорий білий[/color]. Зауважте, що альфа-канал є останнім компонентом колірного коду, а не першим. Короткі коди кольорів RGBA, такі як #6f28 (еквівалент #66ff2288), також підтримуються.

Варіанти комірки

  • expand

    Цінності

    Ціле число

    Замовчуванням

    1

    Коефіцієнт розширення клітин. Це визначає, які клітини намагатимуться розширитися пропорційно іншим клітинам, і їхні коефіцієнти розширення.

  • border

    Цінності

    Назва кольору або колір у форматі HEX

    Замовчуванням

    Успадкувати

    Колір рамки клітинки.

  • bg

    Цінності

    Назва кольору або колір у форматі HEX

    Замовчуванням

    Успадкувати

    Колір фону клітинки. Для чергування тла парних/непарних рядків можна використовувати bg=odd_color,even_color.

  • padding

    Цінності

    4 числа з плаваючою комою, розділених комами

    Замовчуванням

    0, 0, 0, 0

    Заповнення лівої, верхньої, правої та нижньої клітинок.

Наведене вище зображення було створено за допомогою наступного скрипта

За замовчуванням тег [ul] використовує U+2022 гліф Unicode "Bullet" як символ маркера. Така поведінка подібна до веб-браузерів. Символ маркера можна налаштувати за допомогою [ul bullet={bullet}]. Якщо надано, цей параметр {bullet} має бути одним символом без лапок (наприклад, [bullet=*]`). Додаткові символи ігноруються. Ширина маркера не впливає на форматування списку.

Перегляньте Bullet (типографіка) у Вікіпедії, щоб отримати список поширених символів маркерів, які можна вставити безпосередньо в параметр bullet.

Типи впорядкованих списків

Упорядковані списки можна використовувати для автоматичного позначення елементів цифрами або літерами в порядку зростання. Цей тег підтримує наступні параметри типу:

  • 1 – числа, якщо можливо, використовуючи систему нумерації для певної мови.

  • a, A - малі та великі латинські літери.

  • i, I - малі та великі римські цифри.

Текстові ефекти

BBCode також можна використовувати для створення різних текстових ефектів, які за бажанням можна анімувати. П’ять настроюваних ефектів надаються з коробки, і ви можете легко створити свій власний. За замовчуванням анімаційні ефекти призупинятимуться коли SceneTree призупинено. Цю поведінку можна змінити, налаштувавши властивість Process > Mode RichTextLabel.

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

Примітка

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

Ви можете вирішити цю проблему, вимкнувши Керування > Макет > Вміст кліпу в інспекторі після вибору вузла RichTextLabel або переконавшись, що навколо тексту додано достатнє поле, використовуючи розриви рядків над і під рядком за допомогою ефекту.

Пульс

../../_images/bbcode_in_richtextlabel_effect_pulse.webp

Pulse створює анімований пульсуючий ефект, який збільшує непрозорість і колір кожного символу. Його можна використовувати, щоб привернути увагу до конкретного тексту. Його тег має формат [pulse freq=1.0 color=#ffffff40 ease=-2.0]{text}[/pulse].

freq контролює частоту циклу напівпульсу (чим вище, тим швидше). Повний цикл пульсації займає 2 * (1,0 / частота) секунди. color — цільовий множник кольору для миготіння. За умовчанням текст здебільшого зникає, але не повністю. ease - це показник функції пом'якшення для використання. Від’ємні значення забезпечують пом’якшення входу-виходу, тому за замовчуванням встановлено -2.0.

Хвиля

../../_images/bbcode_in_richtextlabel_effect_wave.webp

Хвиля змушує текст підніматися і опускатися. Його формат тегу: [wave amp=50.0 freq=5.0connected=1]{text}[/wave].

amp контролює, наскільки високим і низьким буде ефект, а freq контролює, як швидко текст піднімається і опускається. Значення freq, що дорівнює 0, призведе до відсутності видимих хвиль, а від’ємні значення freq також не відображатимуть жодних хвиль. Якщо connected 1 (за замовчуванням), гліфи з лігатурами буде переміщено разом. Якщо connected дорівнює 0, кожен гліф переміщується окремо, навіть якщо вони з’єднані лігатурами. Це може вирішити певні проблеми візуалізації з лігатурами шрифтів.

Торнадо

../../_images/bbcode_in_richtextlabel_effect_tornado.webp

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

radius — це радіус кола, який контролює зміщення, freq — швидкість руху тексту по колу. Значення freq 0 призупинить анімацію, а негативне freq відтворить анімацію назад. Якщо connected 1 (за замовчуванням), гліфи з лігатурами буде переміщено разом. Якщо connected дорівнює 0, кожен гліф переміщується окремо, навіть якщо вони з’єднані лігатурами. Це може вирішити певні проблеми візуалізації з лігатурами шрифтів.

Струсіть

../../_images/bbcode_in_richtextlabel_effect_shake.webp

Shake змушує текст тремтіти. Його тег має такий формат: [shake rate=20.0 level=5 connected=1]{text}[/shake].

rate контролює, наскільки швидко текст тремтить, level контролює, наскільки далеко текст зсувається від початку. Якщо connected 1 (за замовчуванням), гліфи з лігатурами буде переміщено разом. Якщо connected дорівнює 0, кожен гліф переміщується окремо, навіть якщо вони з’єднані лігатурами. Це може вирішити певні проблеми візуалізації з лігатурами шрифтів.

Зникати

../../_images/bbcode_in_richtextlabel_effect_fade.webp

Зникнення створює статичний ефект згасання, який збільшує непрозорість кожного символу. Його тег має такий формат: [fade start=4 length=14]{text}[/fade].

start контролює початкову позицію спаду відносно того, куди вставлено команду fade, length контролює кількість символів, які мають відбуватися fade out.

Веселка

../../_images/bbcode_in_richtextlabel_effect_rainbow.webp

Rainbow gives the text a rainbow color that changes over time. Its tag format is [rainbow freq=1.0 sat=0.8 val=0.8 speed=1.0]{text}[/rainbow].

freq determines how many letters the rainbow extends over before it repeats itself, sat is the saturation of the rainbow, val is the value of the rainbow. speed is the number of full rainbow cycles per second. A positive speed value will play the animation forwards, a value of 0 will pause the animation, and a negative speed value will play the animation backwards.

На контури шрифту не впливає ефект веселки (вони зберігають свій початковий колір). Існуючі кольори шрифтів перекриваються ефектом веселки. Однак властивості CanvasItem Modulate і Self Modulate впливатимуть на вигляд ефекту веселки, оскільки модуляція помножує його кінцеві кольори.

Власні теги BBCode і текстові ефекти

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

Вибір спеціального RichTextEffect після збереження сценарію, який розширює RichTextEffect за допомогою ``class_name``

Вибір спеціального RichTextEffect після збереження сценарію, який розширює RichTextEffect за допомогою class_name

Попередження

Якщо спеціальний ефект не зареєстровано у властивості Розмітка > Спеціальні ефекти RichTextLabel, ефект не буде видно, а вихідний тег залишиться без змін.

There is only one function that you need to extend: _process_custom_fx(char_fx). Optionally, you can also provide a custom BBCode identifier by adding a member name bbcode. The code will check the bbcode property automatically or will use the name of the file to determine what the BBCode tag should be.

_process_custom_fx

Тут відбувається логіка кожного ефекту, який викликається один раз для кожного гліфа під час фази малювання тексту. Це передається в об’єкт CharFXTransform, який містить кілька змінних, щоб керувати відображенням відповідного гліфа:

  • identity вказує, який спеціальний ефект обробляється. Ви повинні використовувати це для керування потоком коду.

  • outline має значення true, якщо ефект викликається для малювання контуру тексту.

  • діапазон повідомляє вам, наскільки далеко ви знаходитесь у певному спеціальному блоці ефекту як індекс.

  • минулий_час - це загальний час роботи текстового ефекту.

  • visible повідомить вам, чи є гліф видимим чи ні, а також дозволить вам приховати певну частину тексту.

  • offset – це позиція зсуву відносно місця, де даний гліф має відображатися за звичайних обставин.

  • колір - це колір даного гліфа.

  • glyph_index і font - це гліф, що малюється, і ресурс даних шрифту, який використовується для його малювання.

  • Нарешті, env - це Dictionary параметрів, призначених даному спеціальному ефекту. Ви можете використовувати get() з додатковим значенням за замовчуванням для отримання кожного параметра, якщо це вказано користувачем. Наприклад, [custom_fx spread=0.5 color=#FFFF00]test[/custom_fx] матиме плаваючу форму spread і параметри Color color у словнику env. Більше прикладів використання див. нижче.

Останнє, що слід зауважити щодо цієї функції, це те, що необхідно повернути логічне значення 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]