리치 텍스트 마크업

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>

중첩

태그는 나중에 연 것을 먼저 닫는 순서로 닫아야 합니다. 안쪽 스타일 값은 바깥쪽 스타일의 같은 프로퍼티를 오버라이드합니다. 서로 다른 프로퍼티는 함께 적용됩니다. 텍스트 구간(span)의 효과는 독립적으로 계속 활성화되므로 중첩된 그라디언트는 색상을 곱하고, 중첩된 위치 효과는 오프셋을 더합니다.

<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는 초당 완전한 흐름 애니메이션 주기 수를 지정하며, 기본값 0은 그라디언트를 정적으로 유지합니다. 거울처럼 반사되어 반복되는 색상 변화가 연속적으로 흐르며 색상이 갑자기 바뀌지 않고 순환합니다. 기본값은 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

둘러싼 텍스트를 가로지르는 선을 그립니다. ul과 같은 pattern 값을 받으며, 마찬가지로 최종적으로 적용된 면 색상을 상속합니다.

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

outline

외곽선 너비, 색상 또는 둘 다 설정합니다. 속성을 하나 이상 지정해야 합니다. 너비를 0으로 지정하면 해당 텍스트 구간의 외곽선을 명시적으로 비활성화합니다.

<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_BUTTON_LEFT에 대한 Mouse Trigger 바인딩을 추가하면 단일 터치 입력도 활성화됩니다. 게임 오브젝트의 스크립트나 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

배치된 텍스트에서 sprite와 link 오브젝트를 가져오려면 label.get_layout_objects() 또는 gui.get_layout_objects()를 사용합니다.

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>

안쪽 색상은 상속된 외곽선 너비와 색상을 유지하면서 면 색상을 바꿉니다.