常用控件¶
本篇按“拿来就用”的方式介绍内置控件:什么时候用、最小写法是什么、有哪些容易踩的行为。完整属性表见控件参考。
一览¶
| 控件 | 用途 | 交互 |
|---|---|---|
Container |
排版容器 | 本身不响应点击(可挂 Part) |
Panel |
纯色块 / 边框 / 分隔线 | 无子控件 |
Label |
单行或自动换行文本 | 无 |
Button |
按钮 | 点击、回车/空格激活 |
Checkbox |
勾选或开关 | 点击、空格切换 |
Slider |
连续数值 | 拖动、方向键 |
TextBox |
单行文本输入 | 点击聚焦、键入、回车提交 |
Dropdown |
下拉选择 | 点击展开、选择、Esc 收起 |
ScrollView |
裁剪滚动区域 | 滚轮、拖动滚动条 |
Image |
纹理或图片文件 | 无 |
Part |
装饰层 | 不参与布局、不响应点击 |
ForEach |
按数组生成行 | 行内控件各自交互 |
下面的示例默认放在一个竖排 Container 中,省略外层容器。
Label¶
显示一行文本。默认不换行,超宽会被截断并加省略号。
Label {
text: "生命值:{{@health}} / 100";
height: 16;
font-size: 0.85;
color: #C8CFD5;
}
需要多行时开启 wrap,并给出高度;高度决定最多显示几行,超出部分不绘制:
Label {
text: "这是一段较长的说明,开启 wrap 后按控件宽度折行。";
width: 260;
height: 40;
font-size: 0.6;
wrap: true;
color: #87919A;
}
- 高度为
0时:普通 Label 取一行高度;wrap: true取 3 行高度。 text-align支持left/center/right。- 颜色、字体、透明度等通用属性对文字生效。
Button¶
Button {
text: "应用设置";
width: 112;
height: 24;
background: #2F6B37;
border: 1 solid #5CD65C;
color: #D9F2D9;
hover-background: #3C8446;
pressed-background: #275B2E;
onClick: "apply_settings";
}
- 点击判定:在按钮内按下并在按钮内释放。
- 事件可以写回调名(字符串)或脚本(
{ ... })。脚本优先;脚本存在时不会再调用同名 C++ 回调。 - 悬停与按下的默认高亮会被
hover-background/pressed-background覆盖。 - 通过焦点环选中后,回车或空格会触发点击。
Checkbox¶
既可用于勾选,也可把方块隐藏后当作开关:
Checkbox {
text: "启用绿色主题";
width: 150;
height: 18;
checked: @theme_green;
accent: #5CD65C;
onChange: { @theme_color = event.checked ? "#5CD65C" : "#E05252"; };
}
checked是布尔绑定;用户切换时会写回绑定的数据键(两向绑定)。- 事件脚本内读
event.checked(布尔)或event.value。 - 使用回调名时,值以文本
true/false传入。 box-size、text-gap、check-inset、show-box: false、accent控制外观。- 隐藏方块 +
Part可以做成拨动开关,示例见示例集锦。
Slider¶
Slider {
width: 220;
height: 20;
min: 0;
max: 100;
value: @health;
step: 1;
accent: #5CD65C;
smooth: true;
onChange: { @health = event.value; };
}
- 拖动时连续更新;
step会吸附到最近的刻度;smooth让滑块位置平滑追随数值。 - 事件脚本内读
event.value(数字)。 - 使用回调名时,值以格式化文本传入(如
42.5)。 - 获得焦点后可用左右方向键调整。
TextBox¶
TextBox {
width: 180;
height: 22;
text: @player_name;
placeholder: "输入名称";
max-length: 32;
onChange: { @player_name = event.text; };
onSubmit: "rename_player";
}
- 点击获得焦点后开始输入;
Backspace删除,Esc放弃焦点。 onChange在每次文本变化时触发;失去焦点时若文本有变化,会再通知一次。onSubmit在回车时触发,脚本读event.text。max-length按字节截断,中文等多字节字符会按完整字符边界处理。- 获得焦点时方向键、字符键由输入框消费,不会触发宿主快捷键。
输入法与光标
Silica 自己绘制光标,不接管系统输入法候选框。需要中文等复杂输入时,宿主应提供可用的字符事件或输入框接管;框架只接收逐字符输入。
Dropdown¶
Dropdown {
width: 160;
height: 24;
options: "低, 中, 高";
selected: @quality;
onChange: { @quality = event.index; };
}
options是逗号分隔的纯文本列表,首尾空白会被去掉;选项内不能包含逗号。selected(别名index/value)是索引,从0开始;绑定到数据键时用户选择会写回。- 展开时点击列表项选择;点击外部或按
Esc收起;失去焦点自动收起。 - 展开后的列表可以超出控件原高度,点击判定会同步扩展。
- 事件脚本读
event.index/event.value(数字)与event.text(选项文字);回调名收到的是索引文本。
ScrollView¶
ScrollView {
name: scroll_area;
width: 0;
height: 240;
padding: 6;
scroll-step: 28;
scrollbar-width: 3;
scrollbar-inset: 3;
scrollbar-radius: 0;
// 子节点会进入垂直内容区,依次向下排列
Label { text: "第一行"; height: 16; margin-bottom: 4; }
Label { text: "第二行"; height: 16; margin-bottom: 4; }
// ...
}
- 子控件放入内部内容容器,始终垂直排列;在
ScrollView上写layout会被忽略。 - 视口外的内容不绘制、不可点击。
- 滚轮滚动与滚动条拖动都先改变目标偏移,再由每帧缓动逼近;
smooth-scroll: false可立即跳转。 show-scrollbar: false可隐藏滚动条,滚轮仍然可用。- 内容高度由子控件自动计算;不要给内部内容设置固定高度。
Image¶
Image {
src: "textures/items/diamond";
width: 32;
height: 32;
}
Image {
src: "file:ui/logo.png";
width: 24;
height: 24;
}
src可以是游戏内部纹理路径,也可以是file:开头的图片文件(也接受绝对路径与.png/.tga相对路径)。- 图片会被拉伸到控件矩形,不保持比例;需要保持比例时自行计算宽高。
- 文件图片由 Silica 复制到生成的资源包中,路径必须位于模组根目录内。
- 加载失败时绘制暗色占位块,并在日志中记录一次。
详见图片。
Part¶
Part 是挂在任意控件上的装饰层:它不参与布局,每帧按锚点贴合宿主,并可用宿主状态控制显示。适合做高亮条、角标、开关滑块、贴图皮肤。
Button {
name: fav_button;
text: "收藏";
width: 96;
height: 24;
Part {
anchor: right;
width: 20;
height: 20;
inset-right: 2;
src: "textures/ui/icon_star";
tint: #FFD75A;
when: "hovered";
}
}
常用锚点:fill、top、bottom、left、right、center 与四个角。inset 控制内缩(1–4 个数字,按上/右/下/左的 CSS 规则),dx / dy 做额外偏移。
when 用空格分隔多个条件,全部满足才显示;! 表示取反:
Part { anchor: left; width: 2; background: #5CD65C; when: "checked"; layer: under; }
Part { anchor: fill; background: #FFFFFF07; when: "hovered !pressed"; layer: under; }
- 可用状态由宿主控件决定:所有控件都有
hovered、pressed、focused、visible、disabled;Checkbox额外有checked,Dropdown有open/collapsed,TextBox有empty/filled/editing。 layer: under画在宿主自身内容之下,默认画在其上。Part自身不接收点击;它只是视觉层。
控件与数据的分工¶
控件只负责显示与用户输入,不保存业务规则。建议:
- 界面状态(当前页、是否展开)可以放在
DataStore,由脚本修改。 - 业务状态(背包内容、配置项)由 C++ 写入
DataStore,界面只读绑定。 - 需要跨帧保持的输入值通过双向绑定写回,而不是在 C++ 里轮询控件。
下一章介绍绑定的完整规则。