基础语法¶
本篇说明 .sil 文件的组成、节点与属性的写法、值如何被分类,以及数字、颜色、字符串和注释的规则。
文档结构¶
一份文档由两类内容组成:
- 顶层定义:
Var、Style、Component、@keyframes。它们不直接产生控件,只供后面的节点引用。 - 界面节点:一个或多个顶层控件。最常见的是一棵以
Container为根的树。
// 顶层定义
Var accent: #5CD65C;
Style Card {
background: #171B1F;
border: 1 solid #2A3036;
padding: 8;
}
// 界面节点
Container {
name: root;
layout: vertical;
width: 360;
height: 200;
Container {
class: "card";
height: 60;
Label { text: "样式与变量"; height: 16; color: $accent; }
}
}
定义可以出现在界面节点之前或之后;引用在编译时解析,不要求先声明。文档至少要有一个顶层节点,否则编译报错 the document does not define any component。
如果写了多个顶层节点,Silica 会把它们依次放进一个垂直 Container,避免全部叠在 (0, 0)。需要精确控制时,建议始终只保留一个根节点。
节点¶
节点语法:
类型 参数列表? { 属性; 子节点... }
- 类型:内置控件名(
Container、Panel、Label、Button、Image、ScrollView、Checkbox、Slider、TextBox、Dropdown、ForEach、Part),或文档中定义的Component名。 - 参数列表:仅
ForEach与Component使用,形如(data: @rows, item: @row)。普通控件的参数列表没有意义。 - 属性:
键: 值;,写在花括号内。 - 子节点:属性之后直接写下一个节点即可,不需要逗号。
Container {
layout: horizontal;
height: 28;
Label { text: "名称"; width: 80; height: 16; margin-top: 6; }
Button { text: "确定"; width: 72; height: 24; onClick: "confirm"; }
}
节点类型不是内置控件、也不是已定义组件时,编译产生错误 unknown component '...',该节点不会创建。
属性与值的分类¶
同一行 键: 值; 会根据值的写法被归为四类,行为不同:
| 写法 | 类别 | 示例 | 行为 |
|---|---|---|---|
以 @ 开头 |
响应式绑定 | text: @health; |
解析为表达式;DataStore 相关键变化时重新求值 |
包含 {{ ... }} |
模板 | text: "生命:{{@health}}" |
仅替换花括号内的表达式,其余文本原样保留 |
值是 { ... } |
事件脚本 | onClick: { @health = 100; } |
绑定到事件名;触发时执行语句 |
| 其他 | 字面属性 | width: 120; |
直接交给控件的属性处理器 |
只有事件属性能挂脚本
脚本必须写在事件属性上,例如 onClick、onChange、onSubmit。写成 text: { ... } 会得到警告:scripts attach to an event property (...). 脚本不支持 $变量 替换,$ 在脚本内是本次执行的局部变量。
字面属性里的 $name 会在编译期被 Var 的值替换:
Var gap: 8;
Var accent: #5CD65C;
Container {
padding: $gap;
background: #171B1F;
Label { text: "编译期替换"; color: $accent; }
}
字符串¶
- 使用双引号包围:
text: "保存并关闭"; - 支持转义:
\"、\\、\n、\t。 - 文本里的
;、:、{等字符只有出现在引号外才会被当作语法符号。 - 需要在文本里显示双引号时写
\"。
Label {
text: "提示:按 \"确定\" 继续";
height: 16;
}
数字与尺寸¶
数字按 GUI 单位解释,可带 px、em、pt、dp 后缀,后缀只是书写方便,不改变数值:
width: 120;
height: 24px;
padding: 8dp;
font-size: 0.9;
负值在多数尺寸属性上无效(视为不合法,产生警告)。margin-* 的负值表示“回退到 margin 默认值”,而不是负边距。
0 有特殊含义,取决于属性:
width: 0/height: 0:尺寸交给布局或控件自身决定。垂直于布局方向时为 0 会被父容器拉伸;沿布局方向为 0 的子控件按 0 计算,只有容器自身沿布局方向为 0 时才按内容自动计算;有默认尺寸的控件(Button、Slider…)回落到默认值(见布局)。x: 0/y: 0:绝对坐标为零,只在绝对布局中有效。
颜色¶
支持以下写法:
| 形式 | 示例 | 说明 |
|---|---|---|
#RGB |
#5C5 |
每位扩展为两位 |
#RGBA |
#5C58 |
末位为透明度 |
#RRGGBB |
#5CD65C |
常用形式 |
#RRGGBBAA |
#0F1215F2 |
末两位为透明度,F2 接近不透明 |
| 颜色名 | white、black、red、green、blue、yellow、orange、purple、pink、cyan、magenta、gray / grey |
固定色调 |
| 透明 | transparent、none |
完全透明;none 也用于清除阴影/边框等可选效果 |
透明度与 opacity 属性相乘:一个 #FFFFFF80 的控件再设置 opacity: 0.5,最终绘制透明度约为 25%。
布尔值¶
true / false 之外,1 / 0、yes / no、on / off 也可作为布尔值使用,大小写不敏感。常见于 visible、disabled、wrap、smooth 等属性。
注释¶
支持两种注释:
// 单行注释
/*
多行注释
/* 不支持嵌套 */
*/
注释可以出现在顶层、节点内或属性之间,也可以写在事件脚本的语句之间。
name 属性¶
name(也接受 id)给节点一个标识,便于 C++ 用 FindByName 查找,或在测试与日志中识别:
Container {
name: settings_panel;
// ...
}
名字不参与布局,也不会自动成为数据键。整棵树中建议保持唯一;重复不会报错,但查找只会返回第一个匹配项。
属性覆盖顺序¶
同一个属性可能来自多处,最终生效顺序为(后者覆盖前者):
- 控件默认值。
Style基样式(extends链最底层)。- 派生样式。
- 节点内联属性 / 绑定 / 模板。
样式与绑定按“键”覆盖,且 margin-left 与 marginLeft 被视为同一个键来比较优先级。不过实际应用属性时仍应写标准形式 margin-left,否则控件不认识。
常见的语法错误¶
| 日志信息 | 原因 | 处理 |
|---|---|---|
expected ':' after ... |
属性名后缺少冒号 | 补 : |
missing ';' after property '...' |
下一行新属性前缺少分号 | 每条属性以 ; 结束 |
expected '{' after ... |
节点或定义后缺少花括号 | 补 { ... } |
property '...' expects a value, not a block |
在非事件属性上写了 { ... } |
改成字面值或绑定 |
unknown component '...' |
类型名拼错,或组件未定义 | 检查大小写与定义 |
unknown property '...' on '...' |
控件没有这个属性 | 查控件参考 |
错误与警告的区别
语法错误会让文档无法编译;未知属性、未知样式、缺少组件参数等只是警告,会保留其余界面继续构建。日志中以 error: / warning: 区分。