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.

Checking the stable version of the documentation...

BBCode у RichTextLabel

Вступ

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

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

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

Зауважте, що теги BBCode також можна певною мірою використовувати для інших випадків використання:

• BBCode можна використовувати для format comments in the XML source of the class reference.

• BBCode можна використовувати в GDScript documentation comments.

• BBCode можна використовувати, коли printing rich text to the Output bottom panel.

Дивись також

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

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

By default, class_RichTextLabel functions like a normal Label. It has the text property, which you can edit to have uniformly formatted text. To be able to use BBCode for rich text formatting, you need to turn on the BBCode mode by setting bbcode_enabled. After that, you can edit the text property using available tags. Both properties are located at the top of the inspector after selecting a RichTextLabel node.

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

Більшість 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-й рядок)

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

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 не рекомендується для введення користувачами, оскільки це може змінити відображуваний текст, а користувачі не зрозуміють, чому частину їхнього повідомлення було видалено. Escaping user input.

Швидкодія

У більшості випадків ви можете використовувати 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 class reference для повного списку функцій 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 посилання на клас. Для отримання додаткової інформації див. Class reference 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]
код Змушує {text} використовувати монофонічний шрифт RichTextLabel.	[code]{text}[/code]
символ Додає символ Unicode із шістнадцятковим UTF-32 {codepoint}.	[char={codepoint}]
p Додає новий абзац із {text}. Підтримує параметри конфігурації, див. Параметри абзацу.	[p]{text}[/p] [p {options}]{text}[/p]
br Додає розрив рядка в тексті без додавання нового абзацу. Якщо використовується всередині списку, це не створить новий елемент списку, а натомість додасть розрив рядка всередині поточного елемента.	[br]
hr Додає нову горизонтальну лінію для розділення контенту. Підтримує параметри конфігурації, див. Варіанти горизонтальної лінійки.	[hr] [hr {options}]
центр Робить {text} горизонтально по центру. Те саме, що [p align=center].	[center]{text}[/center]
left Робить {text} горизонтальним вирівнюванням за лівим краєм. Те саме, що [p align=left].	[left]{text}[/left]
праворуч Робить {text} горизонтально вирівняним за правим краєм. Те саме, що [p align=right].	[right]{text}[/right]
заповнення Змушує {text} заповнювати всю ширину RichTextLabel. Те саме, що [p align=fill].	[fill]{text}[/fill]
відступ Відступ {text} один раз. Ширина відступу така ж, як і для [ul] або [ol], але без маркера.	[indent]{text}[/indent]
адреса Створює гіперпосилання (підкреслений текст, на який можна натискати). Може містити необов'язковий {text} або відображати {link} як є. Підтримує параметри конфігурації, див. Параметри URL-адреси. Потрібно обробляти сигнал "meta_clicked", щоб мати ефект, див. Обробка кліків тегом [url].	[url]{link}[/url] [url={link}]{text}[/url] [url {options}]{text}[/url]
hint Створює підказку, яка відображається під час наведення курсора миші на текст. Хоча це не обов'язково, рекомендується розміщувати текст підказки між подвійними або одинарними лапками. Зверніть увагу, що неможливо екранувати лапки за допомогою \" або \'. Щоб використовувати одинарні лапки для апострофів у рядку підказки, потрібно використовувати подвійні лапки, щоб оточити рядок.	[hint="{tooltip text displayed on hover}"]{text}[/hint]
img Вставляє зображення з {path} (може бути будь-яким дійсним ресурсом class_Texture2D). Якщо вказано {width}, зображення намагатиметься відповідати цій ширині, зберігаючи співвідношення сторін. Якщо надано і {width}, і {height}, зображення буде масштабовано до цього розміру. Додайте % до кінця значення {width} або {height}, щоб указати його у відсотках від ширини елемента керування замість пікселів. Add em to the end of {width} or {height} value to specify it as a ratio of the current font size. For example, height=1em will make the image as tall as the surrounding text. Якщо надається конфігурація {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] підтримує кілька символів. Значення полей розділяються комами та можуть бути додатними, нульовими або від’ємними. Значення не повинні бути розділені пробілами; інакше значення не будуть оброблятися правильно. Від’ємні верхній та нижній поля особливо корисні, щоб решта абзацу могла відображатися під буквицею.	[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 у class_RichTextLabel. {code} має бути ISO кодом мови. Це можна використати для примусового використання певного сценарію для мови без початку нового абзацу. Деякі файли шрифтів можуть містити замінники, специфічні для сценарію, і в цьому випадку вони будуть використані.	[lang={code}]{text}[/lang]
колір Змінює колір {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} – це назва таблиці для допоміжних (програм зчитування з екрана).	[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]{текст}[/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

  Цінності	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)
  Замовчуванням	default

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

• 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

  Опція вирівнювання (вирівнюванні заливки). Додаткову інформацію див. у class_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
  Замовчуванням	Color(1, 1, 1, 1)

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

• Height

  Цінності	Ціле число
  Замовчуванням	2

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

• Width

  Цінності	Ціле число
  Замовчуванням	90%

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

• align

  Цінності	ліворуч (або l), центр (або c), праворуч (або r)
  Замовчуванням	left

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

Параметри URL-адреси

• underline

  Цінності	always, never, hover
  Замовчуванням	always

  Режим підкреслення URL-адреси.

• підказка

  Цінності	Рядок.
  Замовчуванням

  Підказка URL-адреси.

• href

  Цінності	Рядок.
  Замовчуванням

  Цільова URL-адреса.

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

• колір

  Цінності	Назва кольору або колір у форматі HEX
  Замовчуванням	Успадкувати

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

• Height

  Цінності	Floating-point number
  Замовчуванням	Успадкувати

  Target height of the image in pixels.

  Alternative units to pixels can be specified:

  • Add % to the end of the value to specify it as a percentage of the control width instead of pixels. For example, height=50% will make the image half as tall as the control is wide.

  • Add em to the end of the value to specify it as a ratio of the surrounding font size instead of pixels. For example, height=1em will make the image as tall as the surrounding text.

• Width

  Цінності	Floating-point number
  Замовчуванням	Успадкувати

  Target width of the image in pixels.

  Alternative units to pixels can be specified:

  • Add % to the end of the value to specify it as a percentage of the control width instead of pixels. For example, width=50% will make the image take up half of the control width.

  • Add em to the end of the value to specify it as a ratio of the surrounding font size instead of pixels. For example, width=1em will make the image as wide as the surrounding text is tall.

• Region

  Цінності	x,y,ширина,висота в пікселях
  Замовчуванням	Успадкувати

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

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

  Цінності	false, true
  Замовчуванням	false

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

• підказка

  Цінності	Строка (рядок, текст)
  Замовчуванням

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

• align

  Цінності	див. Вертикальне вирівнювання зображення та таблиці
  Замовчуванням	center,center

  Вирівнювання зображення відносно навколишнього тексту.

• alt

  Цінності	Строка (рядок, текст)
  Замовчуванням

  Опис зображення для допоміжних програм (програма зчитування з екрана).

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

Якщо значення вертикального вирівнювання вказано разом із тегом [img] або [table], зображення/таблиця спробує вирівняти себе відносно навколишнього тексту. Вирівнювання виконується за вертикальною точкою зображення і вертикальною точкою тексту. Існує 3 можливі точки на зображенні (верх, центр і низ) і 4 можливі точки на тексті та таблиці (верх, центр, базова лінія і низ), які можна використовувати в будь-якій комбінації.

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

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.

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

Скорочені назви для значень: t (top), c (center), l (baseline) та b (bottom).

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

• 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.

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

Для тегів, які дозволяють вказувати колір за назвою, ви можете використовувати назви констант із вбудованого класу Color. Іменовані класи можна вказати в кількох стилях, використовуючи різні регістри: DARK_RED, DarkRed і darkred дадуть той самий точний результат.

Перегляньте це зображення, щоб переглянути список колірних констант:

Переглянути в повному розмірі

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

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

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

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

• shrink

  Цінності	false, true
  Замовчуванням	ture

  Якщо true, комірка може стиснутися до свого вмісту.

• expand

  Цінності	Ціле число
  Замовчуванням	1

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

• border

  Цінності	Назва кольору або колір у форматі HEX
  Замовчуванням	Успадкувати

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

• bg

  Цінності	Назва кольору або колір у форматі HEX
  Замовчуванням	Успадкувати

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

• padding

  Цінності	4 числа з плаваючою комою, розділені комами (без пробілу після кожної коми)
  Замовчуванням	0,0,0,0

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

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

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

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

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

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

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

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

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

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

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

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

Примітка

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

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

Пульс

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

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

Хвиля

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

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

Торнадо

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

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

Струсіть

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

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

Зникати

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

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

Веселка

Веселка надає тексту веселковий колір, який змінюється з часом. Його формат тегу: [rainbow freq=1.0 sat=0.8 val=0.8 speed=1.0]{text}[/rainbow].

freq визначає, на скільки літер простягається веселка, перш ніж вона повториться, sat - це насиченість веселки, val - це значення веселки. швидкість - це кількість повних циклів веселки за секунду. Додатне значення швидкості відтворюватиме анімацію вперед, значення 0 призупинить анімацію, а від’ємне значення швидкості відтворюватиме анімацію назад.

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

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

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

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

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

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

Існує лише одна функція, яку потрібно розширити: _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 і параметри 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 = 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]