换一换 
XML用户界面简介。需具备XML和Lua基础知识。 简介 本指南将简要概述新引入的XML界面的基础知识，包括可用元素、实用属性、布局、元素默认状态定义以及与Lua脚本的通信。本指南不会教授XML的一般基础知识。如果您不熟悉XML的原理或其基本结构，请访问众多在线教程之一（一个似乎合适的示例：点击[www.w3schools.com]）。 属性 属性可用于修改元素的外观或行为。虽然有多种不同的属性可用，但本指南将列出最重要的一些属性，以帮助快速入门。通用属性 通用属性用于设置元素的基本信息或对其进行分组，以便后续识别。 | 名称 | 描述 | |------------|----------------------------------------------------------------------| | active | 指定该元素是否处于激活状态。可通过Lua脚本用于隐藏元素 | | class | 允许对元素进行分组 | | id | 用作特定UI元素的标识符 | | visibility | 指定哪些颜色的玩家能够看到此元素 | **注意**：visibility允许四种不同的值： - Host（主机）：仅对游戏主机可见。 - Admin（管理员）：仅对主机和任何已提升权限的玩家可见。 - Red（红色）：仅对该座位颜色的玩家可见。适用于所有颜色名称。不同颜色可通过在颜色之间添加“|”进行拼接。俱乐部：仅对该玩家群组的成员可见。适用于所有队伍名称。不同队伍可通过在每个队伍之间添加 | 进行拼接。 文本属性 文本属性会影响元素的（文本）内容及其外观。 | 名称 | 描述 | |------------|----------------------------------------------------------------------| | text | 指定文本内容 | | alignment | 指定元素中文本的对齐方式。共有6种可能的值，由垂直方向描述符（上、中、下）和水平方向描述符（左、中、右）组合而成 | | color | 指定文本颜色 | | fontStyle | 指定字体样式 |可能的值：常规、粗体、斜体、粗斜体 字体大小：指定字体的尺寸。 ### 尺寸与定位 为了给元素设置合适的尺寸，至少需要设置元素的宽度和高度。否则元素将自动调整大小，这通常不是理想的结果。不过，布局元素内的子元素始终会调整大小以适应其父元素（面板除外）。 | 名称 | 描述 | | --- | --- | | 宽度/高度 | 设置对象占据的宽度/高度 | | 最小宽度/高度 | 设置对象占据的最小宽度/高度 |宽度/高度不能减小到设定值以下 首选宽度/高度：设置对象的首选宽度/高度（目前大多数布局会忽略此设置） 偏移量XY：按给定的偏移量更改对象位置，对放置元素很重要 灵活宽度/高度：决定元素的宽度/高度是否灵活，即是否可以动态更改 可见性：指定哪些颜色能够看到此元素 动作监听器 动作监听器，也称为“事件属性”，可用于向脚本发送有关特定用户交互（如点击）发生的信息。 |名称|描述| |----|----| |onClick|点击元素时|.onMouseEnter 指针进入元素边界。 .onMouseExit 指针离开元素边界。 .onDrag 元素拖动事件。 .onBeginDrag 元素开始被拖动。 .onEndDrag 元素拖动结束并被释放。 .onMouseDown 鼠标点击动作。 .onMouseUp 鼠标点击完成动作。 .onSubmit 元素 文本 文本元素是字符串的表现形式。它们可用作简单标签，并可用于预格式化文本以在其他元素中使用。
图像 图像正如其名：图像。它们必须通过资源管理器提供。 ### 有用属性 | 名称（Name） | 描述（Description） | |--------------|---------------------| | name | 资源管理器中文件的名称 | | Type | 似乎与图像的裁剪方式有关。目前尚未测试。可能的4个值：简单（Simple）、切片（Sliced）、填充（Filled）、平铺（Tiled） | 进度条 进度条可用于指示某事物的进展情况。
### 有用属性 |名称|描述| |----|----| |percentage|用于显示的百分比数值| |showPercentageText|是否同时用文字显示百分比？| |textColor|百分比文字的颜色| |color|进度条的背景颜色| |fillImageColor|进度条实际填充部分的颜色| ### 输入项 输入项是可接收信息的元素。这些信息可以是文本，也可以是鼠标点击、指针进入元素边界等事件。 ### 按钮 按钮可用作激活特定功能的简单触发器。
可通过以下方式创建： <Button> 文本 </Button> ### 常用属性 | 名称 | 描述 | | --- | --- | | onClick | 点击时将调用的Lua函数名称 | | icon | 按钮可使用的图形图标路径 | | interactable | 指示按钮是否可用 | ### 开关 开关可用于让用户激活或停用某些功能/行为。 有两种不同类型的开关可用： - 切换开关（Toggles）：
切换按钮
两者用途相同，只是样式不同。 可通过以下方式创建： <ToggleButton> 文本 </ToggleButton> <Toggle> 文本 </Toggle> ### 常用属性 | 名称 | 描述 | | --- | --- | | onValueChanged | 当切换状态改变时将调用的Lua函数 | | interactable | 指示切换是否可用 | | icon | 按钮可使用的图形图标路径 | | isOn | 指示开关当前是否处于切换状态 | ### 切换组 切换组允许将切换按钮进行分组，使其可以用作单选按钮，让用户在不同可用选项中进行选择（当一次只能选择一个选项时适用）。可通过以下方式创建： <ToggleGroup> <VerticalLayout> <Toggle>切换按钮 A</Toggle> <Toggle>切换按钮 B</Toggle> <Toggle>切换按钮 C</Toggle> </VerticalLayout> </ToggleGroup> ### 常用属性 | 名称 | 描述 | | --- | --- | | text | 输入框的内容 | | onValueChanged | 每次编辑输入框时将调用的 Lua 函数名称 | | onEndEdit | 输入框失去焦点时将调用的 Lua 函数名称 | | interactable | 指示输入框是否可用 | | readOnly | 指示输入框是否可编辑 |输入框可用于显示和编辑文本。
可通过以下方式创建： <InputField> Text </InputField> ### 常用属性 |名称|描述| |----|----| |text|输入框的内容| |onValueChanged|每次编辑输入框时将调用的Lua函数名称| |onEndEdit|输入框失去焦点时将调用的Lua函数名称| |interactable|指示输入框是否可用| |readOnly|指示输入框是否可编辑| ### 滑块 滑块可用于便捷地选择给定最小值和最大值之间的数值。
可通过以下方式创建： <Slider minValue = "?" maxValue = "?" value = "?" /> ### 可用属性 |名称|描述| |----|----| |onValueChanged|输入框每次编辑时将调用的Lua函数名称| |interactable|指示输入框是否可用| |minValue|最小可能值| |maxValue|最大可能值| |value|当前值| |wholeNumbers|指示滑块是否只能返回整数| |direction|滑块的方向|可能有 4 种不同的值：从左到右、从右到左、从上到下、从下到上。 下拉菜单 A：可用于构建可展开的选择菜单栏。下拉菜单有两种状态：已关闭。
已打开
可通过以下方式创建 <Dropdown> <Option>选项 1</Option> </Dropdown> ### 可用属性 |名称|描述| |----|----| |onValueChanged|输入框每次编辑时将调用的 Lua 函数名称| |interactable|指示输入框是否可用| |itemHeight|指示下拉菜单打开后可用选项的高度| ### 布局 通用布局元素用于以特定方式对其他元素进行分组。除了它们的差异外，它们还共享许多属性来定义特定特征，如内边距、间距、单元格大小等。现在我们将深入探讨最实用的属性： **内边距（Padding）** 内边距定义了元素内容与其边框之间的距离。它用于美化界面，可通过以下方式指定： padding = "左值 右值 上值 下值"
所有布局元素均可使用内边距。 对齐方式 对齐方式是用于定义尺寸小于父元素的子元素在父元素内的定位方式的属性。共有6种可能的值，由垂直方向描述符（上、中、下）和水平方向描述符（左、中、右）组合而成。 示例： childAlignment = "UpperLeft"（左上） 注意：文本元素也使用对齐方式来组织其文本显示。在此情况下，对齐方式应按以下方式设置： alignment = "UpperLeft"（左上） 除面板外，所有布局元素均使用对齐方式。
间距 间距用于告知父元素各个子元素之间应保留多少空间，主要用于美化界面。可通过以下方式进行设置： spacing = "数值"
除面板外，所有布局元素均使用间距。因此，表格布局使用cellSpacing属性来定义单元格之间的间距。 单元格尺寸 单元格尺寸由表格布局和网格布局用于将其空间组织成均匀子空间（单元格）的网格。 这两种布局类型都有调整单元格大小的已知属性。 网格布局使用cellSize属性，可通过以下方式指定： cellSize = "宽度 高度" 表格布局使用columnWidths属性来定义单元格的宽度。行的高度取决于该行中最高的子元素。其定义方式如下： columnWidths = "列1宽度 列2宽度 列3宽度 列4宽度 等"此属性也可使用“auto-size”来自动确定相应列所需的宽度。
面板 面板是一个可用于容纳子元素的空白窗口。它是最基本的布局元素，不会对子元素进行排序。所有子元素都堆叠在面板中央。如果设置了“padding”（内边距）属性，面板会表现得像“layout-group”（布局组），其效果与水平布局非常相似。 可通过以下方式定义： <Panel> <Element> 元素内容 </Element> </Panel> 布局 游戏内
水平布局 水平布局会将其子元素按水平方向排列。 可通过以下方式定义： <HorizontalLayout> <Element> 元素内容 </Element> </HorizontalLayout> 布局 游戏内
垂直布局 垂直布局会将其子元素垂直排列。 可通过以下方式定义： <VerticalLayout> <Element> 元素内容 </Element> </VerticalLayout> 布局 游戏内
网格布局 网格布局会将子元素按类似棋盘的网格形式排列。子元素可占用的空间可通过“cellSize”属性进行限制。网格布局会先水平填充单元格，当水平方向没有空间容纳更多单元格时，会在第一行下方开始新的一行。 可通过以下方式定义： <VerticalLayout> <Element> 元素内容 </Element> </VerticalLayout> 布局 游戏内
表格布局 表格布局是目前可用的最复杂布局。它使用行和单元格元素来排列其子元素。每行和每个单元格都可以通过默认值和属性进行更改，这使得表格布局成为排列元素时用途最广泛的布局。 其定义方式如下： <TableLayout> <Row> <Cell><Element> 元素内容 </Element></Cell> <Cell><Element> 元素内容 </Element></Cell> </Row> </TableLayout> 布局 游戏内
滚动视图 滚动视图可用于将内容适配到其他布局元素中，这些布局元素的高度、宽度或两者都比父元素大，且不会裁剪或换行元素内容。 它们可以通过以下方式定义： <VerticalScrollView> <Element> 元素内容 </Element> </VerticalScrollView> <HorizontalScrollView> <Element> 元素内容 </Element> </HorizontalScrollView> 垂直方向 水平方向
尽管它们主要用作布局元素，但也可作为输入元素使用，这意味着它们能在发生变化时触发lua函数。 需要注意的事项： 目前，布局元素会调整其子元素的大小以适应自身边界。遗憾的是，这使得它们不适合嵌套使用，尤其是在使用水平或垂直布局时，这一问题更为明显。它们会完全忽略子元素设置的尺寸，这意味着必须将布局元素的尺寸设置为精确匹配的大小才能达到预期效果。 例如：假设你想要一个包含10个按钮的列表，每个按钮的尺寸为30x30。如果你想用垂直布局对它们进行分组，那么该垂直布局的尺寸必须设置为：宽度 = 30 + 左内边距 + 右内边距；高度 = 30×10 + 上内边距 + 下内边距 + 间距。由于在复杂布局中追踪这些内容可能比较麻烦，因此我建议，如果要构建更复杂的界面，且这些界面不是由Lua脚本构建和维护的，那么应避免使用布局组来构建复杂用户界面。相反，使用面板来设置窗口，因为它们不会出现这种奇怪的行为。 高级功能：默认值 默认值用于为元素设置标准值。这可用于为按钮或滑块等元素设置默认外观，或应用于指定类别的元素。默认值与CSS描述非常相似。 如何定义默认值：以下示例将把所有文本元素的标准颜色定义为白色，字体大小定义为18。所有属于“red”类的文本元素将被设为红色。<Defaults> <Text color="#FFFFFF" fontSize="18" /> <Text class="red" color="#FF0000" /> </Defaults> 高级功能：与Lua脚本通信 与Lua脚本的通信主要通过事件触发器来实现，例如按钮按下、滑块数值变化或输入框文本更改（有关可能的事件列表，请参见“动作监听器”段落下的“属性”部分）。UI与脚本之间的通信对于使UI具备实际功能是必不可少的。 要开始与脚本通信，首先UI必须知道在特定事件发生时应调用哪个函数。假设我们希望在按钮点击时执行某个操作。首先，我们需要为按钮设置onClick属性来指定onClickListener： <Button onClick="clickFunction"> 点击我执行操作！ </Button> 现在，当我们点击按钮时，名为“clickFunction”的Lua函数将被调用。每个元素会自动向函数传递参数，以便识别调用元素和触发事件的玩家。 传递给函数的参数如下： 参数 描述 player 指示触发事件的玩家 value 输入发送的值。可以是字符串或数字。按钮不使用此参数。 id 仅在元素指定了ID时发送。有助于识别触发元素，进而实现函数重载。 在Lua中，代码如下所示： function clickFunction(player,value,id) -- 一些功能代码 end 通过Lua脚本操作界面 Lua脚本不仅可以从界面获取信息，还能对界面进行操作。以下函数对于完成该任务最为有用： 函数 描述 getAttributes(id) 返回用户为该ID元素设置的属性 getAttributes(id, attribute) 返回用户为该ID元素设置的特定属性 setAttributes(id, attribute, value) 为该ID元素设置特定属性 setAttributes(id, data) 为该ID元素设置属性（表格数据） hide(id) 隐藏该ID元素 show(id) 显示该ID元素
