Форматированная текстовая разметка

Используйте разметку в компонентах Label и GUI-нодах Text, чтобы применять вложенные визуальные стили и эффекты и получать сведения о ссылках и спрайтах из 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

Подробнее о настройке см. в разделах Фокус ввода и Ввод с помощью мыши и касаний.

Когда компонент Label или GUI получает ввод указателя, ссылки создают следующие сообщения. Сообщения Label отправляются игровому объекту, которому принадлежит компонент; сообщения 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>

Внутренний цвет меняет заполнение, сохраняя унаследованные ширину и цвет обводки.