Geejing WebBuilder 新手指导:用 Wb.Button 按钮组件跑通企业级快速开发平台的前后端闭环

3 阅读12分钟

一、为什么新手第一个组件选按钮

刚开始接触一个可视化开发平台,最容易迷失在一长串控件列表里。表格、树、图表、弹窗都很吸引人,但它们往往要等数据源、字段模型准备好才能跑通,新手很难在第一分钟看到反馈。按钮不一样:它是最小的一个完整交互单元——有外观、有事件、能在点击时把请求发到服务端,再把结果拿回来。把一个按钮从拖进页面到调起后端脚本走通,等于把平台的「声明式界面 → 客户端事件 → 服务端动作 → 数据返回」这条主链路走了一遍。

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

把示例里最基础的那个按钮单独摘出来,只有十行左右:

- _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 分组给了最直观的写法:

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 的真实定义):

属性类型作用与示例取值
textString按钮文字,如 Common Button
icon / imgIconString / ImgString内置图标名(如 gear、bell)、图片名,也支持字符图标 icon: 🌻
iconAlignEnumleft / right / top / bottom 四种图文排布
iconSizeNumber图标尺寸,示例里有 iconSize: 2.8em
tipMix悬停提示文本
typeEnumprimary / plain / tool 三种语义样式
shapeEnumcircle / rect / round 三种外形
cnameEnum预设外观类,如 tool、iconButton、lightButton
badgeTextBoolean角标数字,示例中 badgeText: 'true' 配 icon: bell
disabledBoolean禁用状态,disabled: 'true'
focusable / tabIndexBoolean / Enum是否参与键盘焦点与 Tab 顺序
keys / keysTextTipString / Boolean快捷键,如 keys: Ctrl+Shift+K
tapClick / repeatIntervalBoolean按下即触发 / 长按连续触发
groupName / activeString / Boolean分组互斥与选中态
noVerifyBoolean跳过所在表单的校验
menuWb.Menu内嵌菜单对象

一段配套的样式示例:

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。

六、让按钮「好用」的几个交互细节

示例的第二到第五组按钮,演示的都是真实项目里马上会用到的细节:

# 快捷键触发点击
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',它们就变成互斥的单选按钮组;父容器上可以直接接住状态变化:

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 请求当前模块地址,带上一个动作名;服务端按动作名分派。

// 客户端:新增按钮的 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:

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 分组,演示了「不靠设计器、用代码操作组件」的几种基本手法,非常适合新手建立对象模型:

// 往容器里动态加一个按钮
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 把这些放在同一个易读的模块文件里,新手只要顺着「拖进去 → 点一下 → 发个请求 → 拿回结果」这条线走,就能自然过渡到更复杂的业务页面,而不必先啃完整套框架文档。