DSL 使用教程¶
.sil 是 Silica 的界面描述语言。它接近 QML 的节点结构,又借用了 QSS 的属性写法:一个节点是一层界面,属性写成 键: 值;,以 @ 开头的值是响应式绑定,以 { ... } 作为值的是事件脚本。
本教程按主题拆分,建议按顺序阅读;已经熟悉某个主题时可以直接跳转。
章节导航¶
| 章节 | 内容 | 适合 |
|---|---|---|
| 基础语法 | 节点、属性、值类型、颜色与数字、注释、顶层定义 | 所有人 |
| 布局 | 垂直/水平/绝对布局、尺寸与边距、内边距、层叠顺序 | 所有人 |
| 常用控件 | 文本、按钮、勾选、滑动条、输入框、下拉框、滚动视图的用法 | 所有人 |
| 响应式绑定 | @key、表达式、模板、双向绑定、控件状态 |
所有人 |
| 事件脚本 | onClick: { ... }、赋值、if/else、event 载荷 |
所有人 |
| 组件 | Component、参数默认值、Slot、实例覆盖 |
界面作者 |
| 样式 | Var、Style、extends、class、内联覆盖 |
界面作者 |
| 动画与过渡 | transition、@keyframes、缓动、可动画属性 |
界面作者 |
| 列表 | ForEach、行作用域、增删改数据、性能边界 |
界面作者 |
| 图片 | 游戏纹理名、file: 图片、资源包、失败表现 |
所有人 |
书写约定¶
- 文件使用 UTF-8 编码,扩展名
.sil。 - 节点类型区分大小写,使用内置类型名(
Container、Label、Button…)。 - 属性名使用小写加连字符:
font-size、margin-left、z-order。大小写与下划线不会自动换算成连字符。 - 事件属性允许
onClick、on-click、ONCLICK等写法,内部会统一成同一个事件名。 - 样式名与
class名不区分大小写,并忽略-与_:DemoRowBox、demo-row-box、demo_row_box指向同一个样式。 - 字符串使用双引号。文本包含空格、冒号或特殊字符时务必加引号。
- 颜色支持
#RGB、#RGBA、#RRGGBB、#RRGGBBAA与少量颜色名(white、black、red、green、blue、gray等)。 - 数字是 GUI 单位,可带
px、em、pt、dp后缀,后缀不改变数值含义,只便于书写。 - 每条属性以
;结尾。最后一条属性可以省略分号,但统一加上更不容易出错。
属性值与源码文本
绑定与脚本保留原始表达式文本:字符串的引号、运算符两侧的空格都会原样交给求值器。因此 text: @health > 0 ? "存活" : "死亡"; 与 text:@health>0?"存活":"死亡"; 等价。
一个完整的最小文档¶
Var accent: #5CD65C;
Container {
name: demo_panel;
layout: vertical;
width: 300;
height: 150;
padding: 12;
background: #0F1215F2;
border: 1 solid #353A40;
Label {
text: "生命值:{{@health}}";
height: 16;
font-size: 0.8;
color: $accent;
}
Slider {
height: 20;
margin-top: 8;
min: 0;
max: 100;
value: @health;
onChange: { @health = event.value; };
}
Button {
text: "重置";
width: 80;
height: 22;
margin-top: 10;
onClick: { @health = 100; };
}
}
这段文档同时用到了 Var、绑定、模板、事件脚本与控件状态。各部分的细节见后续章节。
学习建议¶
- 先结构,后数据:先用普通的字面值把界面摆出来,确认布局正确,再把需要随数据变化的值改成
@绑定。 - 命名稳定:给需要 C++ 查找或测试的节点加
name,例如name: settings_panel;。名字在整棵树内应唯一。 - 先看日志:属性拼错只会产生警告,控件会保留默认值;编译错误会在日志中指明行与列。遇到“没生效”先查日志。
- 小步重载:宿主支持重载时(示例为
F5),一次只改一小块,避免把多个问题混在一起。