Розмітка форматованого тексту

Використовуйте розмітку в компонентах Label і текстових вузлах GUI, щоб застосовувати вкладені візуальні стилі й ефекти та інспектувати посилання й спрайти з Lua.

go.set("#label", "text", "Score: <color=#69D2E7>1200</color>")

Також можна визначити для шрифту іменований стиль об’єкта для повторного використання й вибрати його в посиланні:

local fontpath = "/fonts/ui.fontc"
font.set_style(fontpath, "menu_link", "<color=#69D2E7>")
go.set("#label", "text", "Open <link style=menu_link src=inventory>inventory</link>")

Довідник тегів

Тег	Призначення	Приклад
color	Задати колір заливки гліфа.
size	Змінити формування гліфів і розмір компонування.
gradient	Застосувати статичний або анімований колірний градієнт.
ul	Підкреслити текст.
strike	Закреслити текст.
outline	Задати товщину й колір обведення гліфа.
shadow	Додати тінь до тексту.
shake	Застосувати анімоване випадкове зміщення.
wave	Рухати текст анімованою синусоїдальною хвилею.
sprite	Додати вбудований об’єкт спрайта.
link	Додати інтерактивний об’єкт посилання.

Синтаксис

Назви тегів і атрибутів чутливі до регістру. Парний тег застосовується до видимого тексту UTF-32 усередині нього. Об’єкти спрайтів використовують самозакривні теги.

<color=#69D2E7>colored text</color>
<ul pattern=dashed>underlined text</ul>
<outline size=2 color=#000000>outlined text</outline>
<shadow x=2 y=-2 color=#00000080>shadowed text</shadow>
<sprite src=images/icon.png width=2em/>

Атрибути

Атрибути можна записувати без лапок, якщо вони не містять пробільних символів, або в одинарних чи подвійних лапках. color і size підтримують скорочений запис першого значення, а також іменовану форму value.

<color=#FF8800>Orange</color>
<color value="#FF8800">Orange</color>
<size='120%'>Larger</size>

Вкладеність

Теги мають закриватися у зворотному порядку до відкриття: останній відкритий закривається першим. Значення внутрішнього стилю перевизначають ту саму властивість зовнішнього стилю. Різні властивості поєднуються. Ефекти фрагментів залишаються активними незалежно, тому вкладені градієнти перемножують кольори, а вкладені ефекти позиції додають свої зміщення.

<color=#FFCC00>
    Gold <outline size=2 color=#000000>with a black outline</outline>
</color>

Символьні посилання

Для зарезервованих символів у видимому тексті використовуйте &, ', >, < і ". Числові символьні посилання наразі не підтримуються.

Теги

Теги форматованого тексту або оформлюють охоплений фрагмент тексту, або описують об’єкт, який можна інспектувати з Lua. Теги стилів мають відповідний закривний тег. Об’єкт sprite є самозакривним, а link охоплює текст посилання.

color

Задає колір заливки гліфа. Для кольорів використовуються #RRGGBB або #RRGGBBAA. Префікс решітки обов’язковий; 0xFF0000 і FF0000 недопустимі. Результат множиться на базовий колір напису або засобу рендерингу.

<color=#00FF00>Opaque green</color>
<color=#00FF0080>Half-alpha green</color>

size

Змінює формування гліфів і розмір компонування, а не лише масштаб вершин. Відносні значення завжди використовують базовий розмір шрифту компонування. Вони не накопичуються з охоплювальним тегом size.

<size=24px>Exactly 24 pixels</size>
<size=120%>120% of the layout base size</size>
<size=2em>Twice the layout base size</size>

gradient

Градієнт приймає рівно один повний набір атрибутів. Не можна змішувати набори або пропускати окремий атрибут набору.

Якщо fit не вказано, fit=span розподіляє градієнт по всьому тексту, охопленому тегом. fit=glyph незалежно вибирає колір для кожної позиції сформованого тексту. Необов’язковий hz задає кількість повних циклів анімації перетікання за секунду; його стандартне нульове значення залишає градієнт статичним. Повторювана дзеркальна шкала кольорів плавно перетікає й починається знову без стрибка кольору. За замовчуванням використовується direction=forward; задайте direction=reverse, щоб змінити напрямок перетікання.

<gradient left=#FF00FF right=#FFFFFF>Horizontal Gradient</gradient>

<gradient hz=0.25 fit=glyph bottom=#182848 top=#4B6CB7>Animated vertical glyphs</gradient>

<gradient hz=0.25 direction=reverse left=#FF0000 right=#0000FF>Reverse flow</gradient>

<gradient hz=0.25 direction=reverse fit=span left=#FF0000 right=#0000FF>One animated span color</gradient>

<gradient fit=glyph tl=#FF0000 tr=#00FF00 bl=#0000FF br=#FFFFFF>
    Four corners
</gradient>

За чотирма кутами

Анімований

Кольори градієнта множаться на поточний колір заливки. Тому градієнт усередині color=#808080 не може створити канал, яскравіший за цей базовий множник.

ul

Малює підкреслення, використовуючи метрики підкреслення шрифту, якщо вони доступні. Тег не має окремого кольору: лінія успадковує фактичний колір заливки, зокрема горизонтальні й вертикальні градієнти та градієнти за чотирма кутами.

<ul>Solid underline</ul>
<ul pattern=dashed>Dashed underline</ul>
<ul><gradient left=#FF00FF right=#FFFFFF>Gradient line</gradient></ul>

strike

Малює лінію крізь охоплений текст. Приймає ті самі значення pattern, що й ul, і так само успадковує фактичний колір заливки.

<strike>No longer available</strike>
<strike pattern=dashed>Dashed strikethrough</strike>

outline

Задає товщину обведення, його колір або обидва параметри. Потрібен щонайменше один атрибут. Нульова товщина явно вимикає обведення для фрагмента.

<outline size=3 color=#000000>Black outline</outline>
<outline color=#FF0000>Keep inherited width, change color</outline>
<outline size=0>Disable inherited outline</outline>

shadow

Додає чітку тінь до охопленого тексту. Потрібен щонайменше один атрибут. Атрибути, пропущені у вкладеному тегу, зберігають значення зовнішньої тіні; атрибути, пропущені в зовнішньому тегу найвищого рівня, зберігають базове значення тіні шрифту.

<shadow x=6 y=-6 blur=4 color=#000000A0>Shadow</shadow>
<shadow x=-2>Override only the horizontal offset</shadow>

shake

Застосовує детерміноване анімоване випадкове зміщення без зміни перенесення рядків або меж компонування. Ефект самостійно відстежує час; скриптам не потрібно змінювати текст напису для кожного кадру анімації.

<shake>Default shake</shake>
<shake hz=12 amplitude=0.8 fit=glyph>Glyph shake</shake>
<shake hz=12 amplitude=0.8 fit=span>Rigid span shake</shake>

wave

Рухає символи вгору й униз анімованою синусоїдальною хвилею без зміни перенесення рядків або меж компонування. Компонування накопичує час анімації під час оновлення.

<wave>Animated character wave</wave>
<wave amplitude=4 hz=3 wavelength=8 fit=glyph>Travelling wave</wave>
<wave amplitude=4 hz=3 wavelength=8 fit=glyph direction=reverse>Reverse travelling wave</wave>
<wave amplitude=4 hz=1 fit=span>Whole span moves together</wave>

sprite

Додає самозакривний об’єкт спрайта в поточній позиції видимого тексту. Його атрибути зберігаються як метадані для label.get_layout_objects() і gui.get_layout_objects().

A <sprite src=engine/engine/content/builtins/assets/images/logo/logo_256.png/> logo
<sprite src=images/banner.png width=4em height=2em/>
<sprite src=images/icons.atlas animation=coin width=2em/>

Розміри приймають додатні значення в одиницях компонування без суфікса, px, em або %. Як em, так і % використовують базовий розмір шрифту компонування тексту.

Кожен пропущений розмір незалежно приймає стандартне значення 1em. Якщо пропустити обидва, утвориться об’єкт 1em × 1em; якщо вказати лише ширину, висота не обчислюватиметься автоматично зі співвідношення сторін ресурсу.

link

Описує діапазон видимого тексту як об’єкт посилання. Охоплений текст компонується звичайним чином і за замовчуванням отримує іменований стиль link. Компоненти Label і GUI вибирають link:hover та link:active у відповідь на введення без повторного формування тексту. Про повідомлення, які виникають під час взаємодії з посиланням, читайте в розділі Повідомлення взаємодії.

<ul><link id=website src=https://www.defold.com>www.defold.com</link></ul>
<link id=inventory style=menu_link action=open_inventory item=sword>Iron sword</link>

Компонент відстежує стан вказівника для кожного посилання. Він застосовує link:hover, поки вказівник перебуває над посиланням, і link:active, поки натискання утримується. Коли жоден із цих станів не діє, компонент відновлює стиль, указаний атрибутом style посилання, або link, якщо атрибут відсутній.

Повідомлення взаємодії

Взаємодія з посиланнями використовує звичайну систему введення Defold. Додайте прив’язку Mouse Trigger для MOUSE_BUTTON_LEFT, яка також вмикає введення одним дотиком, і отримайте фокус введення у скрипті ігрового об’єкта або скрипті GUI:

function init(self)
    msg.post(".", "acquire_input_focus")
end

Докладні відомості про налаштування наведено в розділах Фокус введення і Введення мишею й дотиком.

Коли компонент напису або GUI отримує введення від вказівника, посилання породжують наведені нижче повідомлення. Повідомлення написів надсилаються ігровому об’єкту, якому вони належать; повідомлення GUI — скрипту GUI.

Кожне повідомлення містить такі поля:

function on_message(self, message_id, message)
    if message_id == hash("text_object_clicked") then
        assert(message.type == hash("link"))
        print(message.id, message.src)
    end
end

Іменовані стилі

Кожна колекція шрифтів містить іменовані стилі об’єктів, які впливають лише на рендеринг. Посилання використовує стиль, указаний його атрибутом style, або link, якщо атрибут відсутній. Загального тегу <style> для фрагментів немає.

Defold надає такі стандартні значення:

Визначте стиль текстовим рядком, що містить відкривні теги. Теги неявно закриваються у зворотному порядку, тому закривні теги й видимий текст не допускаються.

font.set_style("/fonts/ui.fontc", "link",
    "<color=#2673ff><outline color=#000000 size=1>")

font.set_style("/fonts/ui.fontc", "link:hover",
    "<color=#66b3ff><shake amplitude=0.2 hz=20>")

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

API об’єктів компонування

Використовуйте label.get_layout_objects() або gui.get_layout_objects(), щоб отримати об’єкти sprite і link зі скомпонованого тексту.

label.get_layout_objects()

objects = label.get_layout_objects(url)

gui.get_layout_objects()

objects = gui.get_layout_objects(node)

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

Поля поверненого об’єкта

Приклад Lua

local text = [[
Read the <link src=https://defold.com/manuals/ id=manual>manual</link>
or inspect <sprite src=images/info.png width=2em/> for more information.
]]

go.set("#label", "text", text)

local objects = label.get_layout_objects("#label")
for _, object in ipairs(objects) do
    if object.type == "link" then
        print("link", object.attributes.src)
        print("visible range", object.text_offset, object.text_length)
        print("position", object.x, object.y)
    elseif object.type == "sprite" then
        print("sprite", object.x, object.y, object.width, object.height)
        pprint(object.attributes)
    end
end

local gui_objects = gui.get_layout_objects(gui.get_node("rich_text"))

Корисні поєднання

Кольорове обведення з горизонтальним градієнтом

<outline size=2 color=#101820>
    <gradient left=#FEE715 right=#FF6F61>Gradient title</gradient>
</outline>

Градієнт множить лише колір заливки; обведення зберігає власний колір.

Тремтіння речення й градієнт одного слова

<shake hz=20 amplitude=0.5>
    This <gradient left=#FF00FF right=#FFFFFF>whole</gradient> text shakes!
</shake>

Зовнішній ефект позиції застосовується до кожного гліфа. Вкладений колірний ефект застосовується лише до «whole».

Перевизначення однієї властивості зі збереженням інших

<color=#FFFFFF><outline size=2 color=#000000>
    Normal <color=#FF4040>warning</color> normal
</outline></color>

Внутрішній колір змінює заливку, зберігаючи успадковані товщину й колір обведення.