Znaczniki tekstu formatowanego

Używaj znaczników w komponentach Label i węzłach tekstowych GUI, aby stosować zagnieżdżone style wizualne i efekty oraz odczytywać odnośniki i obrazy ze skryptów Lua.

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

Możesz też zdefiniować w foncie nazwany styl obiektu wielokrotnego użytku i wybrać go w odnośniku:

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>")

Przegląd znaczników

Znacznik	Przeznaczenie	Przykład
color	Ustawia kolor wypełnienia glifu.
size	Zmienia kształtowanie glifów i rozmiar układu.
gradient	Stosuje statyczny lub animowany gradient kolorów.
ul	Podkreśla tekst.
strike	Przekreśla tekst.
outline	Ustawia szerokość i kolor obrysu glifu.
shadow	Dodaje cień do tekstu.
shake	Stosuje animowane przesunięcie losowe.
wave	Porusza tekstem w animowanej fali sinusoidalnej.
sprite	Dodaje obiekt sprite w wierszu tekstu.
link	Dodaje interaktywny obiekt odnośnika.

Składnia

W nazwach znaczników i atrybutów wielkość liter ma znaczenie. Znacznik z parą otwierającą i zamykającą dotyczy widocznego tekstu UTF-32 wewnątrz niego. Obiekty sprite używają znaczników samozamykających.

<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/>

Atrybuty

Wartości atrybutów mogą być zapisane bez cudzysłowów, jeśli nie zawierają białych znaków, lub ujęte w pojedyncze albo podwójne cudzysłowy. color i size obsługują skrótowy zapis pierwszej wartości oraz postać z nazwą value.

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

Zagnieżdżanie

Znaczniki trzeba zamykać w kolejności odwrotnej do ich otwierania. Wartości stylu wewnętrznego nadpisują tę samą właściwość stylu zewnętrznego. Różne właściwości łączą się ze sobą. Efekty fragmentów tekstu pozostają aktywne niezależnie, więc zagnieżdżone gradienty mnożą kolory, a zagnieżdżone efekty pozycji sumują przesunięcia.

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

Encje

Dla zastrzeżonych znaków w widocznym tekście używaj &, ', >, < oraz ". Encje numeryczne nie są obecnie obsługiwane.

Znaczniki

Znaczniki tekstu formatowanego stylizują otaczany fragment tekstu albo opisują obiekt, który można odczytać ze skryptu Lua. Znaczniki stylów używają odpowiadającego im znacznika zamykającego. Obiekt sprite jest samozamykający, natomiast link otacza tekst odnośnika.

color

Ustawia kolor wypełnienia glifu. Kolory mają postać #RRGGBB lub #RRGGBBAA. Prefiks z symbolem hasza jest wymagany; 0xFF0000 i FF0000 są nieprawidłowe. Wynik mnoży kolor bazowy etykiety lub mechanizmu renderującego.

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

size

Zmienia kształtowanie glifów i rozmiar układu, a nie tylko skalę wierzchołków. Wartości względne zawsze odnoszą się do bazowego rozmiaru fontu układu. Nie łączą się kumulatywnie z otaczającym znacznikiem 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

Gradient przyjmuje dokładnie jeden kompletny zestaw atrybutów. Łączenie zestawów lub pominięcie jednego z atrybutów jest nieprawidłowe.

Gdy fit jest pominięte, fit=span rozkłada gradient na całym tekście objętym znacznikiem. fit=glyph próbkuje niezależnie każdą pozycję ukształtowanego tekstu. Opcjonalne hz określa liczbę pełnych cykli animacji przepływu na sekundę; domyślna wartość zero pozostawia gradient nieruchomy. Powtarzająca się, lustrzanie odbita rampa kolorów płynie bez przerwy i zawija się bez skoku koloru. Domyślnie używane jest direction=forward; użyj direction=reverse, aby odwrócić przepływ.

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

Cztery narożniki

Animowany

Kolory gradientu mnożą bieżący kolor wypełnienia. Gradient wewnątrz color=#808080 nie może więc utworzyć kanału jaśniejszego niż ten mnożnik bazowy.

ul

Rysuje podkreślenie, korzystając z metryk podkreślenia fontu, jeśli są dostępne. Znacznik nie ma osobnego koloru: linia dziedziczy wynikowy kolor wypełnienia, w tym gradienty poziome, pionowe i czterech narożników.

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

strike

Rysuje linię przekreślającą otoczony tekst. Przyjmuje te same wartości pattern co ul i tak samo dziedziczy wynikowy kolor wypełnienia.

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

outline

Ustawia szerokość obrysu, jego kolor lub oba parametry. Wymagany jest co najmniej jeden atrybut. Szerokość zero jawnie wyłącza obrys dla fragmentu tekstu.

<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

Dodaje twardy cień do otoczonego tekstu. Wymagany jest co najmniej jeden atrybut. Atrybuty pominięte przez zagnieżdżony znacznik zachowują wartości otaczającego cienia; atrybuty pominięte przez znacznik zewnętrzny zachowują bazowe wartości cienia fontu.

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

shake

Stosuje deterministyczne animowane przesunięcie losowe bez zmiany łamania wierszy ani granic układu. Efekt sam śledzi czas; skrypty nie muszą zmieniać tekstu etykiety w każdej klatce animacji.

<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

Porusza znakami w górę i w dół w postaci animowanej fali sinusoidalnej, nie zmieniając łamania wierszy ani granic układu. Układ kumuluje czas animacji podczas aktualizacji.

<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

Dodaje samozamykający obiekt sprite w bieżącej pozycji widocznego tekstu. Jego atrybuty są zachowywane jako metadane dla label.get_layout_objects() i 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/>

Wymiary przyjmują dodatnie wartości w jednostkach układu bez przyrostka albo z px, em lub %. Zarówno em, jak i % używają bazowego rozmiaru fontu układu tekstu.

Każdy pominięty wymiar domyślnie przyjmuje niezależnie wartość 1em. Pominięcie obu tworzy obiekt 1em × 1em; podanie samej szerokości nie wyznacza automatycznie wysokości na podstawie proporcji zasobu.

link

Opisuje zakres widocznego tekstu jako obiekt odnośnika. Otoczony tekst jest układany normalnie i domyślnie otrzymuje nazwany styl link. Komponenty Label i GUI wybierają link:hover i link:active w odpowiedzi na wejście, bez ponownego kształtowania tekstu. Wiadomości powstające podczas obsługi wejścia odnośnika opisano w sekcji wiadomości interakcji.

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

Komponent śledzi stan wskaźnika dla każdego odnośnika. Stosuje link:hover, gdy wskaźnik znajduje się nad odnośnikiem, i link:active, gdy wskaźnik jest naciśnięty. Gdy żaden z tych stanów nie występuje, komponent przywraca styl wskazany przez atrybut style odnośnika albo link, jeśli atrybut jest nieobecny.

Wiadomości interakcji

Interakcja z odnośnikami korzysta ze zwykłego systemu wejścia Defold. Dodaj wiązanie Mouse Trigger dla MOUSE_BUTTON_LEFT, które włącza też obsługę pojedynczego dotyku, i przejmij fokus wejścia w skrypcie obiektu gry lub skrypcie GUI:

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

Szczegóły konfiguracji znajdziesz w sekcjach fokus wejścia oraz wejście myszy i dotyku.

Gdy komponent etykiety lub GUI otrzymuje wejście wskaźnika, odnośniki generują poniższe wiadomości. Wiadomości etykiety trafiają do obiektu gry, do którego należy komponent; wiadomości GUI trafiają do skryptu GUI.

Każda wiadomość zawiera następujące pola:

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

Nazwane style

Każda kolekcja fontów zawiera nazwane style obiektów wpływające wyłącznie na renderowanie. Odnośnik używa stylu wskazanego przez atrybut style albo link, jeśli atrybut jest nieobecny. Nie ma ogólnego znacznika fragmentu tekstu <style>.

Defold dostarcza następujące ustawienia domyślne:

Zdefiniuj styl za pomocą ciągu tekstowego zawierającego znaczniki otwierające. Znaczniki są niejawnie zamykane w odwrotnej kolejności, dlatego znaczniki zamykające i widoczny tekst są niedozwolone.

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>")

Znaczniki są stosowane od lewej do prawej, jak gdyby były zagnieżdżone wokół tekstu obiektu. Styl obiektu wybrany przez wywołującego jest stosowany po stylu domyślnym. Gdy kilka znaczników ustawia tę samą właściwość renderowania, późniejsza wartość nadpisuje wcześniejsze. Efekty są dodawane w kolejności od lewej do prawej.

API obiektów układu

Użyj label.get_layout_objects() lub gui.get_layout_objects(), aby pobrać obiekty sprite i link z ułożonego tekstu.

label.get_layout_objects()

objects = label.get_layout_objects(url)

gui.get_layout_objects()

objects = gui.get_layout_objects(node)

Obie funkcje zwracają nowo utworzoną tablicę zawierającą bieżące obiekty układu w kolejności źródłowej. Zwracają pustą tablicę, jeśli tekst nie zawiera znaczników obiektów. Ponieważ obiekty i ich atrybuty są kopiowane do Lua przy każdym wywołaniu, zapisz wynik w pamięci podręcznej i pobierz go ponownie po zmianie tekstu lub innej właściwości wpływającej na jego układ.

Pola zwracanego obiektu

Przykład 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"))

Przydatne połączenia

Kolorowy obrys z poziomym gradientem

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

Gradient mnoży tylko kolor wypełnienia; obrys zachowuje własny kolor.

Drżenie zdania z gradientem jednego słowa

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

Zewnętrzny efekt pozycji dotyczy każdego glifu. Zagnieżdżony efekt koloru dotyczy tylko słowa „whole”.

Nadpisywanie jednej właściwości z zachowaniem pozostałych

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

Kolor wewnętrzny zmienia wypełnienie, zachowując odziedziczoną szerokość i kolor obrysu.