客户端模板指令参考

本页描述客户端模板里的现行指令语法、事件别名和插槽写法。

模板语法总览

语法	作用
:prop="expr"	属性绑定
@event="handler"	事件绑定
b-if / b-else-if / b-else	条件渲染
b-for	列表渲染
b-show	显隐控制（不移除节点）
b-model	双向绑定
:key="expr"	key 绑定
#slot / b-slot	插槽语法

说明：@、:、# 在解析阶段会做预处理并还原，模板中直接使用即可。

内置结构指令

b-if / b-else-if / b-else

用于同级条件链渲染。

<Label b-if="store.get('mode') === 'battle'" text="战斗中" />
<Label b-else-if="store.get('mode') === 'safe'" text="安全区" />
<Label b-else text="探索中" />

b-else-if / b-else 必须跟在 b-if 后面，条件链按顺序命中第一项后停止。

b-for

支持三种写法：

<Label b-for="item in store.get('quests')" :text="item.title" />
<Label b-for="(item, index) in store.get('quests')" :text="index + '. ' + item.title" />
<Label b-for="store.get('quests')" :text="item.title" />

简写 b-for="source" 时，默认迭代变量名为 item。b-for 在渲染阶段优先于 b-if 处理。

b-show

只控制可见性，不销毁节点。

<Panel b-show="store.get('showSkills')">
  <Label text="技能面板" />
</Panel>

b-model

在 TextField / TextArea / Toggle / Switch 上做双向绑定。

<TextField b-model="store.playerName" placeholder="输入角色名" />
<Toggle b-model="store.autoFight" text="自动战斗" />

绑定键会统一去除 store. 前缀。输入变化会直接写回 store，对应键变化也会反向更新控件。

:key

用于列表节点稳定标识。

<Panel b-for="item in store.get('inventory')" :key="item.uuid">
  <Label :text="item.name" />
</Panel>

事件绑定（@event）

基本写法

<Button @click="onUsePotion" text="使用药水" />
<Button @click="usePotion(2)" text="使用 2 号药水" />

写函数名时会自动补 () 调用；复杂表达式按 JS 表达式执行。

支持事件名

模板事件名	运行时事件
click	UIEvents.CLICK
mousedown	UIEvents.MOUSE_DOWN
mouseup	UIEvents.MOUSE_UP
mouseenter	UIEvents.MOUSE_ENTER
mouseleave	UIEvents.MOUSE_LEAVE
mousemove	UIEvents.MOUSE_MOVE
keydown	UIEvents.KEY_DOWN
keyup	UIEvents.KEY_UP
keypress / chartyped	UIEvents.CHAR_TYPED
focus	UIEvents.FOCUS
blur	UIEvents.BLUR
scroll / wheel / mousewheel	UIEvents.MOUSE_WHEEL
input / change / inputchange	UIEvents.INPUT_CHANGE
submit	UIEvents.SUBMIT
dragenter	UIEvents.DRAG_ENTER
dragleave	UIEvents.DRAG_LEAVE
dragend	UIEvents.DRAG_END
dragupdate / dragover	UIEvents.DRAG_UPDATE
dragperform / drop	UIEvents.DRAG_PERFORM
dragsourceupdate	UIEvents.DRAG_SOURCE_UPDATE
doubleclick	UIEvents.DOUBLE_CLICK
mousedrag	UIEvents.MOUSE_DRAG

事件回调中可直接读取 event。

import { command } from "bui:action"

function onUsePotion() {
  if (event?.button === 1) {
    command("rpg.item.use", { slot: 2 })
  }
}

自定义指令

语法：b-xxx[:arg][.mod1.mod2]="value"

<TextField b-focus />
<Panel b-tooltip:top.delay.important="store.get('hint')" />

解析结果字段：

• name：指令名（不含 b-）
• arg：参数（: 后）
• modifiers：修饰符集合（. 后）
• value：表达式值

内置自定义指令

b-focus

挂载后自动聚焦。

<TextField b-focus placeholder="搜索物品" />

b-disabled

根据布尔值启停元素交互。

<Button b-disabled="store.get('casting')" text="施法中..." />

b-visible

和 b-show 类似，走自定义指令流程。

<Panel b-visible="store.get('showDebug')">
  <Label text="调试信息" />
</Panel>

插槽相关语法

声明插槽

<slot name="header" />
<slot name="default" />

使用插槽（#slot）

<MyCard>
  <template #header>
    <Label text="角色信息" />
  </template>
  <template #default>
    <Label :text="store.get('playerName')" />
  </template>
</MyCard>

b-slot

<template b-slot="header">
  <Label text="标题" />
</template>

常见错误

1. b-else 前面没有 b-if。
2. b-model 绑到不支持输入监听的组件。
3. @event 使用未支持的事件名。
4. 自定义指令未注册（会被跳过并输出日志）。