星火 2.0 开发文档

主题

Label 富文本与链接指南 ​

Label.Text 支持一组轻量富文本标签，可在同一个 Label 中设置粗体、斜体、下划线、颜色、换行和可点击链接。该语法是 GameUI 提供的标记子集，不是完整 HTML。

支持的标签 ​

标签作用示例
<b>...</b>粗体<b>重要</b>
<i>...</i>斜体<i>提示</i>
<u>...</u>下划线<u>可交互文本</u>
<color value="#RRGGBB">...</color>RGB 颜色<color value="#48C9FF">蓝色</color>
<color value="#RRGGBBAA">...</color>带透明度的 RGBA 颜色<color value="#48C9FFCC">半透明蓝色</color>
<br/>换行第一行<br/>第二行
<link id="link_id">...</link>可点击链接<link id="open_shop">打开商店</link>

标签可以嵌套。链接包裹样式、样式包裹链接都可以保留链接标识：

text
<link id="open_shop"><color value="#48C9FF"><b>打开商店</b></color></link>
<color value="#FFCB57"><link id="show_details">查看详情</link></color>

监听链接点击 ​

链接点击使用 Label 自己的 OnLinkClicked 事件。只有 <link> 范围内的文字会触发该事件，点击同一 Label 中的普通文字不会触发。

csharp
#if CLIENT
var label = new Label
{
    Text = "普通文字<br/>" +
           "<link id=\"open_shop\"><color value=\"#48C9FF\"><b>打开商店</b></color></link>",
    FontSize = 20,
    TextWrap = true,
    Width = 420,
};

label.OnLinkClicked += (_, args) =>
{
    Game.Logger.LogInformation("Label link clicked: {LinkId}", args.LinkId);

    switch (args.LinkId)
    {
        case "open_shop":
            OpenShop();
            break;
    }
};

label.AddToRoot();
#endif

LinkClickedEventArgs 提供：

  • LinkId：对应 <link id="..."> 中的标识。
  • PointerButtons：触发点击的指针按钮，继承自 PointerEventArgs。

OnLinkClicked 是客户端 UI 事件，创建 Label、订阅事件和处理界面跳转的代码应放在 #if CLIENT 中。

LinkId 设计建议 ​

  • 使用稳定的语义标识，例如 open_shop、show_item_details、accept_invite。
  • 始终给 id 加引号。
  • 把 LinkId 当作操作标识，在事件处理器中路由业务逻辑；不要把代码或回调表达式写进文本。
  • 多个链接可以共用同一个 Label 和同一个事件处理器，通过 args.LinkId 区分操作。

与普通指针事件的选择 ​

需要区分 Label 内部不同链接时，使用 OnLinkClicked。普通指针事件只能说明控件被点击，不能直接表达用户点击了哪一段富文本。

如果整个区域都是一个操作，优先使用 Button / TextButton 等具有明确交互语义的控件。富文本链接适合一段说明文字中包含少量局部操作的场景，例如“查看详情”“打开商店”或“阅读规则”。

常见问题 ​

点击普通文字也会触发吗？ ​

不会。只有 <link> 开始和结束标签之间的文字会触发 OnLinkClicked。

可以使用 href 或任意 HTML 标签吗？ ​

不可以。使用 <link id="..."> 和本文列出的标签；未列出的 HTML 标签不属于公开支持范围。

嵌套颜色或粗体后会丢失 LinkId 吗？ ​

不会。受支持的样式标签可以嵌套在 <link> 内，也可以包裹 <link>。

如何验证？ ​

  1. 编译客户端配置：dotnet build src/GameEntry.csproj -c Client-Debug。
  2. 启动客户端调试并确认富文本样式正确。
  3. 点击链接文字，检查界面状态或客户端日志中的 LinkId。

需要系统化运行验证时，参考 纯客户端调试 和 预览与验收闭环 Skill。