Weft 语法
本文是 .weft 语言的规范语法,解析器(weft_ui_parser::parse)按此实现。语义规则(作用域、类型、依赖)见文末语义约束。
- 源码为 UTF-8。换行与其他空白一样不敏感,只用来分隔 token。
- 注释:
// 行注释、/* 块注释 */(块注释不嵌套)。 - 标识符:
[A-Za-z_][A-Za-z0-9_]*。 - 保留关键字:
ifelseforintruefalsenull。 - 上下文关键字(其他位置是普通标识符,例如 Demo 中的参数
model):import(后跟字符串)、model/event/component(后跟标识符)只在顶层开启声明;state(后跟标识符)只在组件体内开启状态声明;key只在for头部出现。
- 整数:
[0-9]+,范围为i64。浮点:[0-9]+ "." [0-9]+ ([eE] [+-]? [0-9]+)?或[0-9]+ [eE] [+-]? [0-9]+。 - 字符串:
"...",转义\n\r\t\0\\\"\$\u{XXXX}。${ 表达式 }为插值,插值内部可以再写字符串。字符串不能跨行。 - 符号:
( ) { } [ ] , : ; . ?. ? ?? = += -= == != < <= > >= + - * / % ! && || ->
EBNF 记法:X? 可选,X* 零或多次,X+ 一或多次,"tok" 为 token。
File = Import* Item* EOF ;Import = "import" STRING ; (* 不允许插值 *)Item = Model | Event | Component ;
Model = "model" IDENT "{" FieldList? "}" ;Event = "event" IDENT ( "(" FieldList? ")" )? ;FieldList = Field ( "," Field )* ","? ;Field = IDENT ":" Type ;
Component = "component" IDENT "(" ParamList? ")" "{" StateDecl* Node* "}" ;ParamList = Param ( "," Param )* ","? ;Param = IDENT ":" Type ( "=" Expr )? ;StateDecl = "state" IDENT ( ":" Type )? "=" Expr ;
Type = IDENT TypeSuffix* ;TypeSuffix = "[" "]" | "?" ;
Block = "{" Node* "}" ;Node = ElementNode | IfNode | ForNode ;ElementNode = Path ( "(" ArgList? ")" )? Block? ;Path = IDENT ( "." IDENT )* ;IfNode = "if" "(" Expr ")" Block ( "else" ( IfNode | Block ) )? ;ForNode = "for" "(" IDENT "in" Expr ( ";" "key" "=" Expr )? ")" Block ;
ArgList = Arg ( "," Arg )* ","? ;Arg = ( IDENT "=" )? Expr ; (* 命名参数必须在位置参数之后 *)
Expr = IfExpr | Binary ;IfExpr = "if" "(" Expr ")" Expr "else" Expr ;Binary = Unary ( BinOp Unary )* ; (* 按下方优先级结合 *)Unary = ( "!" | "-" ) Unary | Postfix ;Postfix = Primary ( "." IDENT | "?." IDENT | "(" ArgList? ")" )* ;Primary = INT | FLOAT | STRING | "true" | "false" | "null" | IDENT | "(" Expr ")" | Lambda ;Lambda = "{" ( IDENT "->" )? ( Assign ";"? )* "}" ;Assign = IDENT ( "=" | "+=" | "-=" ) Expr ;二元运算符优先级(从低到高,全部左结合):
| 优先级 | 运算符 |
|---|---|
| 1 | ?? |
| 2 | || |
| 3 | && |
| 4 | == != |
| 5 | < <= > >= |
| 6 | + - |
| 7 | * / % |
说明:
state只能写在组件体顶层,并且在所有节点之前。- 节点之间不需要分隔符。
Name后面紧跟的(和{都属于这个节点,包括换行之后的{。 if出现在节点位置时是条件渲染,分支是节点块;出现在表达式位置时是条件表达式,必须带else,分支是表达式。- 调用只允许出现在标识符或成员访问之后:
Remove(todo.id)、name.trim()。 - Lambda 只能直接作为事件参数的值使用。
for头部的key在语法上可以省略,缺失时由语义分析报错,以便给出更准确的提示。
解析器在出错后继续解析,尽量报告所有错误:
- 顶层:跳到下一个
import/model/event/component。 - 节点块:跳过无法识别的 token(括号成对跳过),直到下一个节点起始 token 或
}。 - 参数/字段列表:跳到下一个
,或右括号。 - 同一位置只报告第一个错误。
所有 AST 节点都带源码区间(文件 + 字节偏移),诊断以 文件:行:列 定位并附带源码片段。
作用域与导入
Section titled “作用域与导入”- 每个文件可见:本文件声明 + 直接
import的文件声明。导入不传递。 - 导入闭包内
model、event、component共用一个命名空间,任何重名都报错;也不能与内置元素重名。 - 宿主侧的事件注册方法由事件名派生(
onFooBar/on_foo_bar),因此忽略大小写和下划线后相同的两个事件名(如FooBar与foo_bar)也报错。 - 循环导入、找不到的文件都报错。
- 组件内名称查找顺序:lambda 参数 →
for变量 →state→ 组件参数。组件内不允许遮蔽已有名称。
- 基础类型
IntFloatBoolString,复合类型T[]、T?,以及model名。 - 组件参数还可以是
Children(插槽,每个组件至多一个)。调用方用尾随块填充,组件体内以参数名作为节点使用。 - 赋值兼容:相同类型;
Int→Float;null→T?;T→T?。 - 算术:
Int op Int → Int(整除),含Float时为Float;String + String → String。 - 比较
< <= > >=只用于数值或字符串;== !=只用于标量及其可空类型。 a ?? b要求a: T?;a?.f要求a可空,结果可空。对非空值用?.给出警告。- 字符串插值只接受
IntFloatBoolString。 model不允许不经过数组或可空类型的直接递归。
| 接收者 | 成员 |
|---|---|
String |
length: Int isEmpty: Bool trim() uppercase() lowercase() contains(String): Bool |
T[] |
length: Int isEmpty: Bool contains(T): Bool(T 为标量) |
Int Bool |
toString(): String |
Float |
toString(): String toFixed(Int): String |
length / isEmpty 是属性,其余是方法。
元素的事件参数有载荷类型(onClick 无载荷,Input.onChange 载荷为 String)。可接受的值:
Event:事件名当函数用,事件参数个数必须等于载荷个数(0 或 1),载荷填充唯一参数。Event(args):直接构造事件实例,参数在渲染时绑定,忽略载荷。{ stmts }/{ v -> stmts }:内联 lambda,只能给state赋值;v接收载荷。onMount/onUnmount只接受事件,不接受 lambda。
if条件为Bool。for必须有key,类型为Int或String;被迭代对象必须是数组。- 自定义组件不允许不经过
if/for的递归实例化。
内置元素与布局
Section titled “内置元素与布局”所有平台支持同一组内置元素和属性(P2 定稿)。只保证布局语义一致,外观贴近各平台原生风格。
| 元素 | 属性(位置参数加粗) | 事件 | 子节点 |
|---|---|---|---|
Column |
padding gap width height: Int,background: Color |
— | 有 |
Row |
同 Column |
— | 有 |
Text |
value: String,color: Color,size: Int,bold: Bool |
— | 无 |
Button |
disabled: Bool |
onClick |
有 |
Input |
value: String,placeholder: String,disabled: Bool |
onChange(String) |
无 |
Checkbox |
checked: Bool,disabled: Bool |
onChange(Bool) |
无 |
Image |
src: String,width height: Int |
— | 无 |
所有元素另有 onMount / onUnmount。
- 长度:
Int,单位是逻辑像素:iOS / macOS 的 pt、Android 的 dp、Windows 的 DIP、Web 的 CSS px;小程序用px,不用rpx。 Column/Row:子元素沿主轴(Column纵向、Row横向)从起点依次排列,交叉轴对齐起点,不拉伸、不自动撑满;gap是相邻子元素的间距,padding是四边相同的内边距,语义同 CSS。平台默认值不同时由后端显式设置,例如 Web 和小程序写align-items:flex-start,SwiftUI 写VStack(alignment: .leading)。width/height:固定尺寸;不写时由内容决定。- 颜色:
Color属性接受#RGB、#RRGGBB或#RRGGBBAA(十六进制,大小写不限),在类型检查中按String处理。字面量在编译期校验,不合法时报错,并预解析为 RGBA 写进视图布局;动态值由平台在运行时解析,不合法时按透明处理,在开发构建中打警告。 Image:src是图片 URL,没有内置网络图片控件的平台由内核下载。
- 依赖是“根 + 字段路径”:根为组件参数、
state或for变量,例如model.user.name、expanded、todo.name。 路径只穿过非空model字段,遇到数组、可空类型、基础类型或内置成员(如length)即截止。 - 脏位:组件参数和
state按上述规则展开到叶子,每个叶子一位;每个for另有一套按元素类型展开的逐项脏位。 依赖覆盖所有以它为前缀的叶子,例如把model.user传给子组件会依赖model.user下的每一位。 - 绑定点:元素属性、组件实参、
if条件(整条if / else if链的条件并集)、for列表与 key、带参数的事件构造(参数在渲染时绑定)。 没有依赖的值是静态的,不生成绑定;lambda 在触发时求值,也不生成绑定。