富文本标记

在 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

在包围的文本上绘制删除线。此标记接受与 ul 相同的 pattern 值，同样会继承实际生效的填充颜色。

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

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

内部颜色改变填充颜色，同时保留继承的轮廓宽度和颜色。