Waylee：新建客户端 Lua 接口页：全局函数、对象方法、窗口操作与客户端事件

2026-10-24T06:36:02Z

新建客户端 Lua 接口页：全局函数、对象方法、窗口操作与客户端事件

Waylee：新建客户端 Lua 接口页：全局函数、对象方法、窗口操作与客户端事件

2026-10-24T06:26:11Z

新建客户端 Lua 接口页：全局函数、对象方法、窗口操作与客户端事件

新页面

__NOTOC__
<div class="lua-reference">
[[首页|首页]] · [[Lua接口/客户端函数索引|客户端接口]] · [[Lua接口/客户端界面索引|客户端界面]] · [[Lua接口/客户端界面布局|界面布局]]
<div class="lua-lead lua-accent-amber">
<div role="heading" aria-level="2" class="lua-h1">客户端界面布局 XML</div>
<div class="lua-sub">351 个 <code>.layout.xml</code> · 13538 个控件 · 142 种控件类型 · 5991 条事件绑定</div>
</div>
== 一个界面是两个文件 ==
{| class="wikitable"
! scope="col" class="lua-w38" | 文件
! scope="col" | 作用
|-
| <code><目录>/<脚本>.lua</code>
| 界面逻辑：注册事件、改文字、调接口。所有判断与数据都写在这里。
|-
| <code><目录>/<布局>.layout.xml</code>
| 控件层级与外观：摆在哪、多大、什么样式、点了调哪个函数。
|}

哪个功能对应哪两个文件，见[[Lua接口/客户端界面索引|客户端界面索引]]；本页只讲 <code>.layout.xml</code> 里能写什么、它和 Lua 怎么接。

== 加载顺序 ==
界面第一次显示时按下面顺序走一遍（实现见客户端 <code>CEGUISystem/UIWindowMng.cpp</code>）：

# 创建界面对象，把 <code>this</code> 注入脚本环境（<code>this</code> 可调[[Lua接口/客户端窗口操作|窗口操作]]里的方法）。
# 执行 <code><界面名>_PreLoad()</code>：此时控件还不存在，只能做准备（取配置、置标记）。
# 读取并解析 <code>.layout.xml</code>，挂到屏幕上并先隐藏。
# 递归注册控件：布局里每个 <code><Window Name="X"></code> 都成为脚本里的一个变量 <code>X</code>。
# 执行 <code><界面名>_OnLoad()</code>：这时才能安全地改控件。

所以脚本里可以直接写 <code>DressPaint_Text:SetText("")</code> —— <code>DressPaint_Text</code> 不是脚本里声明的局部变量，而是加载布局时按控件名注册进来的。'''在 <code>_PreLoad</code> 里访问控件会拿到 <code>nil</code>'''。

== 三条接缝 ==
{| class="wikitable"
! scope="col" class="lua-w46" | 布局里写的
! scope="col" | 脚本里对应的
|-
| <code><Window Name="DressPaint_Text"></code>
| 同名全局变量，直接 <code>DressPaint_Text:方法(...)</code> 使用
|-
| <code><Event Name="Clicked" Function="DressPaint_TurnLeft(1);"></code>
| 全局函数 <code>function DressPaint_TurnLeft(n)</code>（可带实参）
|-
| <code><Property Name="Text" Value="#{SZPR_XML_13}" /></code>
| 不写脚本，取值来自 <code>Data/Config/StrDictionary.txt</code> 的 <code>SZPR_XML_13</code>
|}

事件绑定实测 5144 条指向具体全局函数，其中 '''5081 条'''能在同目录的 <code>.lua</code> 里找到 <code>function 同名</code> 定义；剩下 63 条要么在别的脚本里定义，要么是引擎内建回调。

== 布局文件长什么样 ==
以 <code>DressPaint/DressPaint.layout.xml</code> 开头几行为例（属性只留关键几条）：

<pre data-xml="1"><?xml version="1.0" ?>
<GUILayout>
<Window Type="TLBB_MainFrame1" Name="DressPaint_Frame">
<Property Name="UnifiedPosition" Value="{{0.5,-250},{0.5,-200}" />
<Property Name="AbsoluteSize" Value="w:500 h:365" />
<Event Name="Hidden" Function="DressPaint_OnHiden();" />
<Window Type="TLBB_DragTitle" Name="DressPaint_DragTitle">
<Property Name="DragTarget" Value="DressPaint_Frame" />
<Window Type="TLBB_SimpleText" Name="DressPaint_Title">
<Property Name="Text" Value="#{SZPR_XML_13}" />
</Window>
</Window>
</Window>
</GUILayout></pre>

要点：<code><Window></code> 可以嵌套（子控件坐标相对父控件）；<code>Type</code> 决定控件类（决定它有哪些方法可用）；<code>Name</code> 决定脚本里的变量名，'''同一界面内必须唯一'''。

== 控件类型（最常见）==
共 142 种类型。括号里是布局中出现的控件个数：

{| class="wikitable"
! scope="col" class="lua-w46" | 类型
! scope="col" | 个数
|-
| <code>TLBB_SimpleText</code>
| 2123
|-
| <code>TLBB_StaticImageNULL</code>
| 1848
|-
| <code>TLBB_ActionButton</code>
| 1438
|-
| <code>TLBB_ButtonCommon</code>
| 974
|-
| <code>TLBB_SimpleMulitiTextFrame</code>
| 901
|-
| <code>DefaultWindow</code>
| 836
|-
| <code>TLBB_DragTitle</code>
| 302
|-
| <code>TLBB_ButtonClose</code>
| 300
|-
| <code>TLBB_ButtonHelp</code>
| 292
|-
| <code>TLBB_ButtonNULL</code>
| 285
|-
| <code>TLBB_Money</code>
| 283
|-
| <code>TLBB_MainFrame1</code>
| 214
|-
| <code>TLBB_Frame_Lace5</code>
| 184
|-
| <code>TLBB_Frame_Lace1</code>
| 170
|-
| <code>TLBB_ButtonCheck</code>
| 164
|-
| <code>TLBB_StopWatch</code>
| 150
|-
| <code>TLBB_MenuItem</code>
| 149
|-
| <code>TLBB_MainFrameNULL</code>
| 144
|-
| <code>TLBB_SimpleTextFrame</code>
| 140
|-
| <code>TLBB_ActionButtonNULL</code>
| 133
|}

名字带 <code>TLBB_</code> 前缀的是本项目的皮肤控件（外观在 <code>Data/Interface/Schema/</code> 里定义）；<code>DefaultWindow</code> 是 CEGUI 原生空容器，常用来做分组与对齐。控件上可用的方法见[[Lua接口/客户端窗口操作|窗口操作]]。

== 常用属性（最常见）==
共 138 个属性名：

{| class="wikitable"
! scope="col" class="lua-w46" | 属性
! scope="col" | 出现次数
|-
| <code>UnifiedPosition</code>
| 8371
|-
| <code>UnifiedSize</code>
| 7420
|-
| <code>AbsoluteSize</code>
| 5141
|-
| <code>Text</code>
| 4773
|-
| <code>HorzFormatting</code>
| 3636
|-
| <code>AbsolutePosition</code>
| 3531
|-
| <code>VertFormatting</code>
| 2714
|-
| <code>TextColor</code>
| 2452
|-
| <code>RiseOnClick</code>
| 2099
|-
| <code>MouseHollow</code>
| 2053
|-
| <code>Image</code>
| 1469
|-
| <code>MouseMoveHollow</code>
| 1449
|-
| <code>Position</code>
| 1367
|-
| <code>Visible</code>
| 1112
|-
| <code>DraggingEnabled</code>
| 885
|-
| <code>MouseRButtonHollow</code>
| 868
|-
| <code>AlwaysOnTop</code>
| 836
|-
| <code>MouseLButtonHollow</code>
| 829
|-
| <code>Size</code>
| 818
|-
| <code>Empty</code>
| 801
|}

* <code>UnifiedPosition</code> / <code>UnifiedSize</code> 是'''相对父控件的比例 + 像素偏移'''，写作 <code>{{0.5,-250},{0.5,-200}}</code> 表示「横向 50% 再左移 250px，纵向 50% 再上移 200px」；<code>AbsolutePosition</code> / <code>AbsoluteSize</code> 则是绝对坐标，窗口拉伸时不会跟着变。
* <code>RiseOnClick</code> 与 <code>MouseHollow</code> / <code>MouseMoveHollow</code> 影响点击穿透，叠放控件时最容易出问题。
* 颜色属性写 <code>#AARRGGBB</code> 形式的十六进制。

== 事件（最常见）==
共 41 种事件名、5991 条绑定：

{| class="wikitable"
! scope="col" class="lua-w46" | 事件
! scope="col" | 绑定次数
|-
| <code>Clicked</code>
| 3204
|-
| <code>RBClicked</code>
| 530
|-
| <code>MouseLButtonDown</code>
| 451
|-
| <code>MouseButtonUp</code>
| 258
|-
| <code>MouseRClick</code>
| 245
|-
| <code>Hidden</code>
| 200
|-
| <code>MouseEnter</code>
| 196
|-
| <code>MouseLeave</code>
| 181
|-
| <code>MouseButtonDown</code>
| 161
|-
| <code>CaptureLost</code>
| 109
|-
| <code>MouseLClick</code>
| 90
|-
| <code>MouseDoubleClick</code>
| 69
|}

<code>Hidden</code> 是界面被隐藏时触发（用于收尾清理），<code>Clicked</code> / <code>RBClicked</code> 是左/右键点击，<code>CaptureLost</code> 常用于「按住拖动后松手」的收尾。

== 命名约定 ==
* 框架窗口用 <code><界面>_Frame</code>，标题栏 <code><界面>_DragTitle</code>，标题文字 <code><界面>_Title</code>，关闭 <code><界面>_Close</code>，帮助 <code><界面>_Help</code>。界面索引里的大多数中文名正是靠 <code>_Frame</code> / <code>_DragTitle</code> / <code>_Title</code> 这三个名字反查到的。
* 控件名一律带界面前缀（<code>DressPaint_Text</code> 而不是 <code>Text</code>）：注册成全局变量后，不带前缀极易和别的界面撞名。
* 布局里的可见文字'''不写中文'''，写 <code>#{键名}</code> 并在 <code>StrDictionary.txt</code> 里给键值；直接写中文不会进字符串表，改字与多语言都会失控。

== 改界面时会踩的坑 ==
* '''界面目录名 ≠ 窗口名'''：<code>OpenWindow("X")</code> 用的是窗口名，而窗口名由创建界面的代码给出。改目录名不会改窗口名，两者不一致是常态（如 <code>Materalcompose/MaterialCompound.lua</code>）。
* '''一个目录可能有多套界面'''（如 <code>GuildLeague</code> 下 4 个脚本各自一套），改布局前先确认改的是对的那个 <code>.layout.xml</code>。
* 客户端脚本里的数值（成功率、花费、坐标）'''只决定界面怎么显示'''，真正的判定在服务端；想让玩法变，改的不是这里。
* 新增控件后如果脚本里取到 <code>nil</code>，先确认 <code>Name</code> 拼写、是否重复、以及是否在 <code>_PreLoad</code> 阶段就访问了。

</div>

Lua接口/客户端界面布局 - 版本历史

Waylee：​新建客户端 Lua 接口页：全局函数、对象方法、窗口操作与客户端事件

Waylee：​新建客户端 Lua 接口页：全局函数、对象方法、窗口操作与客户端事件

Waylee：新建客户端 Lua 接口页：全局函数、对象方法、窗口操作与客户端事件

Waylee：新建客户端 Lua 接口页：全局函数、对象方法、窗口操作与客户端事件