一、为什么新手第一个组件选按钮
刚开始接触一个可视化开发平台,最容易迷失在一长串控件列表里。表格、树、图表、弹窗都很吸引人,但它们往往要等数据源、字段模型准备好才能跑通,新手很难在第一分钟看到反馈。按钮不一样:它是最小的一个完整交互单元------有外观、有事件、能在点击时把请求发到服务端,再把结果拿回来。把一个按钮从拖进页面到调起后端脚本走通,等于把平台的「声明式界面 → 客户端事件 → 服务端动作 → 数据返回」这条主链路走了一遍。
Geejing WebBuilder 的控件库一共定义了 83 个组件,Wb.Button 是其中属性最密集的一个:wb/system/controls.json 里给它列了 99 个属性和 23 个事件。听起来吓人,但真正上手只需要三四个属性;剩下的都是「需要时再查」的可选项。本文以平台自带的 wb/modules/example/comps/button.xwl(949 行,备注 Button and tool components usage.)为蓝本,按新手实际操作顺序,一步步把这个组件讲清楚。对企业级快速开发平台来说,能否让新人在一小时内做出第一个能点、能请求、能返回结果的页面,往往比组件总数更能说明它是否好用。
二、先把示例模块跑起来
示例文件在 wb/modules/example/comps/button.xwl,在 IDE 的文件树里展开 example → comps 就能找到;也可以按示例页顶部的提示,用 ide?openExample=1 打开官方示例集。它是一份 YAML 风格的声明式模块文件,设计器视图与源码视图指向同一份内容,改哪边都会同步到另一边------这是 Geejing WebBuilder 里最需要先建立的一个概念:界面不是一堆散落的 JS 文件,而是一棵可编辑的组件树。
示例的结构从外到内是:cls: Wb.Module(模块根)→ cls: Wb.Viewport(layout: grid1)→ Wb.Label 标题、Wb.DisplayField 提示条、Wb.Title 分组标题 → Wb.Container(frame: 'true'、layout: form)→ 一组 Wb.Button。顶部提示条写了一句 ready: if (parentApp?.inIDE) this.hide();,意思是非 IDE 环境下才显示引导信息;模块级还有 finalize: app.useIdeTipField.highlight();,在加载结束时高亮提示字段。
在 IDE 里打开后,左侧是控件库与文件树,中间是设计画布,右侧属性面板按 properties 与 events 两组展示当前选中组件的可编辑项;把 Wb.Button 从控件库拖进 Wb.Container,源码里就会多出上面那一段声明。文件里还有一些以下划线开头的键,例如 _icon、_expanded 和每个节点末尾的 text,它们属于 IDE 的树形展示元数据,不参与运行时渲染,初学时不改也不会影响效果。
新手第一步不用改任何东西:直接运行这个模块,点第一行的 Common Button,屏幕上会弹出 Wb.tip 提示。看到提示,就说明「组件渲染 + 事件绑定 + 客户端脚本执行」三段已经通了,后面所有复杂功能都是在这个基础上叠加的。
三、最小可用按钮:cid、text 与 click
把示例里最基础的那个按钮单独摘出来,只有十行左右:
yaml
- _icon: button
cls: Wb.Button
events:
click: 'Wb.tip(this.cid + '' clicked'');'
properties:
cid: commonBtn
text: Common Button
text: commonBtn
三个关键点:
cls: Wb.Button声明组件类型,IDE 从控件库拖进来的也是这一行;properties.cid是组件在模块内的唯一标识,运行时通过app.commonBtn就能访问这个实例。示例源码里的注释写得很直白:Wb.tip(this.cid + ' clicked')等价于Wb.tip(app.commonBtn.cid + ' clicked');events.click里写的就是点击后要执行的客户端脚本。事件脚本里的this指向当前组件,所以this.cid、this.text、this.disabled都能直接读写。
事件脚本运行在浏览器上下文里,可以直接访问 app、Wb.tip、Wb.toast、Wb.confirm 这些客户端能力;而 Params 属于服务端上下文,只在模块的服务端脚本里可用。把两者记混,是新手从示例页跳到自己写模块时最容易出现的一类错误:Wb.tip 能立刻弹提示说明客户端链路通了,但要读请求参数、访问数据库,必须走到服务端脚本。
再加一个 icon: gear 就是带图标按钮,加 tip: 'Press Ctrl+Shift+K to fire click event' 就是悬停提示。cid 在同一个模块里必须唯一,重名会让 app.xxx 指向不确定的对象------这是新手最常踩的第一个坑。注意 YAML 里脚本含单引号时要写成两个单引号('' clicked''),或者直接改用 |- 块写法,避免字符串提前结束。
四、事件不止一个 click
controls.json 给 Wb.Button 定义了 23 个事件:init、ready、resize、click、dblclick、beforeclose、close、beforeshow、show、beforehide、hide、subadd、subadded、added、removed、subremoved、beforesubremove、subremove、destroy、beforeshowmenu、activate、deactivate、toggle。日常用得最多的是下面这些:
| 事件 | 触发时机 | 典型用途 |
|---|---|---|
init / ready |
组件创建 / 渲染完成 | 初始化状态、读取默认配置 |
click / dblclick |
单击 / 双击 | 主业务逻辑入口 |
activate / deactivate / toggle |
开关型按钮状态变化 | 切换视图、开关筛选条件 |
beforeshowmenu |
菜单展开前 | 动态拼菜单项 |
destroy |
组件销毁 | 清理定时器与自定义监听 |
resize |
尺寸变化 | 自适应布局 |
示例里的 Events 分组给了最直观的写法:
yaml
events:
activate: Wb.tip('activate');
deactivate: Wb.tip('deactivate');
toggle: 'Wb.tip(''toggle: '' + active);'
properties:
active: 'true'
cid: button2
text: Toggle
这里 active 是事件脚本里可直接使用的状态变量。另外,属性表里还有一个 listeners(类型 Object),它和 events 的区别是:events 属于设计期声明,写在模块文件里;listeners 更偏向运行时挂接,后面第八节会讲到用 on / mon 动态增删监听。把两者混在一起重复绑定,是「点一次弹两次提示」的常见原因。
五、外观属性速查表
新手不必记 99 个属性,先把这张表里的常用项认清就够了(类型一列取自 controls.json 的真实定义):
| 属性 | 类型 | 作用与示例取值 |
|---|---|---|
text |
String | 按钮文字,如 Common Button |
icon / img |
IconString / ImgString | 内置图标名(如 gear、bell)、图片名,也支持字符图标 icon: 🌻 |
iconAlign |
Enum | left / right / top / bottom 四种图文排布 |
iconSize |
Number | 图标尺寸,示例里有 iconSize: 2.8em |
tip |
Mix | 悬停提示文本 |
type |
Enum | primary / plain / tool 三种语义样式 |
shape |
Enum | circle / rect / round 三种外形 |
cname |
Enum | 预设外观类,如 tool、iconButton、lightButton |
badgeText |
Boolean | 角标数字,示例中 badgeText: 'true' 配 icon: bell |
disabled |
Boolean | 禁用状态,disabled: 'true' |
focusable / tabIndex |
Boolean / Enum | 是否参与键盘焦点与 Tab 顺序 |
keys / keysTextTip |
String / Boolean | 快捷键,如 keys: Ctrl+Shift+K |
tapClick / repeatInterval |
Boolean | 按下即触发 / 长按连续触发 |
groupName / active |
String / Boolean | 分组互斥与选中态 |
noVerify |
Boolean | 跳过所在表单的校验 |
menu |
Wb.Menu | 内嵌菜单对象 |
一段配套的样式示例:
yaml
properties:
cid: primary
icon: address-book
text: Primary
type: primary
---
properties:
cid: circleBtn
icon: gear
shape: circle
tip: Circle
type、shape、cname 三者都影响外观,但定位不同:type 管语义(主按钮 / 朴素 / 工具按钮),shape 管轮廓,cname 是平台预置的样式类。初学时选一个用即可,不必叠加,否则容易出现样式互相覆盖。企业级快速开发平台把这类视觉约定收进控件定义里,好处是同一团队的页面天然长得一致,不必每个项目重写一套 CSS。
六、让按钮「好用」的几个交互细节
示例的第二到第五组按钮,演示的都是真实项目里马上会用到的细节:
yaml
# 快捷键触发点击
properties:
cid: keyBtn
icon: keyboard
keys: Ctrl+Shift+K
keysTextTip: 'false'
text: Ctrl+Shift+K
tip: Press Ctrl+Shift+K to fire click event
# 按下即触发(不等 mouseup)
properties:
cid: tapBtn
tapClick: 'true'
text: MouseDown Click
# 长按连续触发
events:
click: |-
app.repeatCt ??= 0;
Wb.toast(this.cid + ' clicked ' + (app.repeatCt++));
properties:
cid: repeatBtn
repeatInterval: 'true'
text: Repeat Click
keys 让按钮拥有全局快捷键,keysTextTip: 'false' 表示不在按钮文字旁显示快捷键提示;tapClick 把触发时机从 mouseup 提前到 mousedown;repeatInterval 配合 Wb.toast 可以做连续加减、翻页这类操作,app.repeatCt ??= 0 用 ??= 给模块级的计数器做一次性初始化,避免每次点击都重置。
分组与开关态是另一组高频用法。给同组按钮设置相同的 groupName 和 active: 'false',其中一个设为 'true',它们就变成互斥的单选按钮组;父容器上可以直接接住状态变化:
yaml
events:
buttontoggle: Wb.tip(button.cid + ' is ' + active);
items:
- cls: Wb.Button
properties: { cid: button1, groupName: group1, active: 'false', text: Button 1 }
- cls: Wb.Button
properties: { cid: button2, groupName: group1, active: 'false', text: Button 2 }
菜单按钮则是在 Wb.Button 的 items 里放一个 cls: Wb.Menu(菜单对象要写 isProperty: 'true'),再往菜单里放若干 cls: Wb.Item;如果希望「主体可点、箭头另出菜单」,用 Wb.SplitButton,它同时带 click 事件和内嵌菜单。示例里 splitButton1 就是这么做的。Geejing WebBuilder 把「按钮 + 菜单」做成嵌套的组件树,而不是两个互不相关的控件,新手在 IDE 里直接往按钮里拖菜单即可。
七、从点击到后端:把一次请求跑通
按钮真正的价值是触发业务。平台自带的 example/ai/crud-dialog.xwl 给出了标准写法:客户端在 click 事件里用 Wb.ajax 请求当前模块地址,带上一个动作名;服务端按动作名分派。
javascript
// 客户端:新增按钮的 okHandler 里发起请求
Wb.ajax({
url: xpath + '&xaction=add',
params: values,
json: true,
success(resp) {
app.grid1.appendRecord(Wb.apply(values, resp));
win.hide();
},
failure(resp) {
app.checkExists(resp);
}
});
// 删除前先确认,避免误操作
if (!recs.length) {
Wb.tipSelect();
return;
}
Wb.confirm(Wb.getActionHint(recs, 'code'), f => {
Wb.ajax({
url: xpath + '&xaction=del',
params: { del: grid.originData },
success() { grid.delRecords(); }
});
});
xpath 指向当前模块,&xaction=add 是动作参数;params 携带表单值;success / failure 分别处理成功与失败。危险操作先用 Wb.confirm 拦一道,没选中记录时用 Wb.tipSelect() 提示------这些细节在真实业务里比「能发请求」更重要。
服务端对应同一份 .xwl 文件的 serverScript:
javascript
let action = Params.xaction;
if (!action) return;
let actions = {
select() {
let sql = 'select sid,user_name from wb_user';
Wb.sendRows(sql);
},
add() {
let rec = { sid: Wb.getId() };
Wb.set(rec);
Wb.sync({ tableName: 'wb_staff', insert: Params });
Wb.send(rec);
},
del() {
Wb.sync({ tableName: 'wb_staff', del: Wb.getObject('del') });
}
};
actions[action]();
客户端一侧的 json: true 让响应按 JSON 解析,Wb.apply(values, resp) 把服务端回传的新记录(例如自动生成的主键)合并进表单值,再追加到表格;failure 回调交给 app.checkExists(resp) 处理唯一性冲突之类的错误。Wb.sync 把参数对象直接映射成表的新增 / 更新 / 删除,Wb.send(rec) 把新记录回传给客户端,Wb.sendRows(sql) 直接把查询结果作为响应。也就是说,一个模块文件同时容纳界面声明、客户端事件和服务端动作,不需要另建 Controller、路由表和 DTO。这正是企业级快速开发平台压缩交付环节的地方;Geejing WebBuilder 把前后端闭环收敛到一个文件里,新手不必先理解整套分层框架也能做出能用的功能。
需要提醒的是:服务端用 actions[action]() 分派时,动作名来自请求参数,务必限定在预先定义好的 actions 对象内,不要拼接成任意函数名调用。示例开头 if (!action) return; 就是第一道收口。
八、运行时用代码控制按钮
示例最后的 Coding 分组,演示了「不靠设计器、用代码操作组件」的几种基本手法,非常适合新手建立对象模型:
javascript
// 往容器里动态加一个按钮
app.demoCt.add({ cname: 'button', icon: 'gear', text: 'New Button' });
// 改文字与图标
let btn = app.demoButton;
if (btn) {
btn.text = 'Changed Text';
btn.icon = 'earth';
}
// 改状态、销毁、增删事件
app.demoButton?.setter('disabled', true);
app.demoButton?.destroy();
app.demoBtnOnClick ??= f => Wb.tip('clicked');
app.demoButton?.on('click', app.demoBtnOnClick); // 同一函数只能注册一次
app.demoButton?.un('click', app.demoBtnOnClick);
app 是按 cid 索引当前模块组件的命名空间;setter('disabled', true) 与直接赋值 btn.disabled = true 等价,但走 setter 会触发平台内部的属性更新流程;?. 保证组件被销毁后脚本不报错。on / un 管理组件事件,mon / mun 管理 DOM 级别的托管监听(示例里绑的是 mouseenter),源码注释特别写明「The same function can only be registered once」,所以示例用 ??= 把函数存在 app 上再复用,避免每次点击都产生一个新的函数引用导致解绑失败。
理解这一节之后,再看设计器里的属性面板就通透了:面板改的是同一批属性,只是把运行时赋值提前到了模块声明里。Geejing WebBuilder 的组件不是黑盒 DOM 片段,而是有明确生命周期、可读写属性的对象。
九、新手常见坑与检查清单
| 现象 | 原因 | 处理 |
|-----------------|--------------------------------------|----------------------------------------------|------------------|
| 点一次弹两次提示 | events 与 on() 重复绑定,或同一函数被注册多次 | 用 app.xxx ??= fn 复用函数,必要时先 un |
| app.xxx 取不到组件 | cid 重名、组件在弹窗 / 未渲染容器内 | 检查 cid 唯一性,用 ?. 做空值保护 |
| 事件脚本报语法错 | YAML 单引号未转义、多行脚本没用 ` | -` | 单引号写成 '',或用块写法 |
| 菜单不显示 | 内嵌 Wb.Menu 少了 isProperty: 'true' | 在设计器里把菜单作为按钮属性添加 |
| 表单里点按钮也触发校验 | 按钮位于表单容器内 | 按需设置 noVerify: 'true' |
| 禁用后仍可点击 | 只改了样式没改状态 | 用 setter('disabled', true) 或直接赋 disabled |
| 请求没到服务端 | xaction 缺失或动作名拼写不一致 | 核对 url 与 actions 键名,服务端先判空 |
| 快捷键不生效 | keys 格式不对或与浏览器快捷键冲突 | 用 Ctrl+Shift+K 这类组合,检查 keysTextTip |
还有两个偏工程化的习惯值得从第一个组件就养成:一是给按钮起有业务含义的 cid,例如 saveBtn、delBtn,不要沿用 button1、button2,否则模块稍微长大就难以维护;二是把可复用的提示文案、动作名集中到一处,避免客户端 &xaction=add 与服务端键名各写一遍后逐渐漂移。
收尾建议按这个顺序自查:先看 cid 与组件树层级,再看 events 是否重复注册,然后确认 Wb.ajax 的 url / params 与服务端 Params.xaction 对齐,最后检查禁用、校验、确认弹窗这些边界。走完这套流程,一个新人在企业级快速开发平台上就有了可复用的第一块积木:以后换成表格工具栏按钮、弹窗确定按钮、批量操作按钮,套路完全一致,只是 cid、事件脚本和 xaction 不同。
回头看,按钮这一课覆盖的东西其实不少:声明式组件树、app 命名空间、事件生命周期、属性 setter、Wb.ajax 与服务端动作分派。Geejing WebBuilder 把这些放在同一个易读的模块文件里,新手只要顺着「拖进去 → 点一下 → 发个请求 → 拿回结果」这条线走,就能自然过渡到更复杂的业务页面,而不必先啃完整套框架文档。