客户端组件参考

本页是客户端模板组件标签、别名和关键绑定面的现行清单。

校验范围

• project/runtime-forge/.../bui/core/BUIParser.kt
• project/runtime-forge/.../bui/core/BUIRenderer.kt

模板结构

客户端模板文件支持四个顶层块：

• <template>
• <properties>
• <style>
• <script>

最小示例：

<template>
  <Panel id="root">
    <Label text="RPG 面板" />
  </Panel>
</template>

<style>
#root { padding: 6px; }
</style>

<script>
import { onMounted } from "bui:lifecycle"

onMounted(() => {
  // init
})
</script>

标签匹配时不区分大小写，但文档示例统一使用 PascalCase。

基础组件

Panel / div

通用容器。

<Panel class="card">
  <Label text="角色信息" />
</Panel>

Row

行容器。

Column

列容器。

Label / text / span

文本显示，可配合 插值。

<Label :text="'HP: ' + store.get('hp')" />

Button

按钮组件。

<Button text="释放技能" @click="castSkill" />

输入组件

TextField / input

<TextField b-model="store.playerName" placeholder="角色名" />

TextArea

<TextArea b-model="store.chatDraft" />

Toggle / checkbox

<Toggle b-model="store.autoFight" text="自动战斗" />

Switch

<Switch b-model="store.hudVisible" />

Selector / select

关键绑定：:options、:value

<Selector :options="store.get('jobs')" :value="store.get('job')" />

SearchComponent / search

关键绑定：:config

<SearchComponent :config="searchConfig" />

ColorSelector / colorpicker

<ColorSelector ref="themeColorPicker" />

TagField

<TagField ref="nbtEditor" />

容器组件

ScrollerView / scroll

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

VScroller / HScroller

<VScroller />
<HScroller />

SplitView

关键属性：orientation="horizontal|vertical"（也可 :orientation）

<SplitView orientation="horizontal">
  <Panel><Label text="左侧" /></Panel>
  <Panel><Label text="右侧" /></Panel>
</SplitView>

TabView + Tab

<TabView>
  <Tab text="背包" />
  <Tab text="技能" />
</TabView>

TreeList / tree

关键绑定：:data（ITreeNode）

<TreeList :data="store.get('treeRoot')" />

Menu

关键绑定：:data（ITreeNode）

<Menu :data="store.get('menuRoot')" />

VirtualList

关键绑定：:items、:item-height、:buffer、:render-item

<VirtualList
  :items="store.get('damageLogs')"
  :item-height="18"
  :render-item="renderLogItem"
/>

Dialog / modal

<Dialog b-show="store.get('confirmOpen')">
  <Label text="确定退出？" />
</Dialog>

Form + Field

Form 支持 :initial-values / initial-values；Field 支持 name、:rules、validate-on-change、validate-on-blur。

<Form :initial-values="store.get('formInit')">
  <Field name="nickname" :rules="nicknameRules">
    <TextField b-model="store.nickname" />
  </Field>
</Form>

展示组件

ProgressBar / progress

<ProgressBar :value="store.get('hpPercent')" />

GraphView / graph

<GraphView id="skillTree" />

ChatHistoryView / chat-history / chathistory

<ChatHistoryView id="chatPanel" />

EntityView / entityviewer / entitydisplay / entity-preview

<EntityView :entity="store.get('previewEntity')" />

VideoPlayer / video

支持 src / path / videopath。

<VideoPlayer src="behemiron:video/intro.mp4" />

槽位组件

DisplaySlot

支持 :item-scale / item-scale。

<DisplaySlot :item-scale="1.25" />

ItemSlot / item-slot

支持 slot / slotindex / slot-index。

<ItemSlot slot-index="12" />

InventorySlots

<InventorySlots />

Ponder 组件

Ponder / PonderElement

支持 scene / sceneid。

<Ponder scene="rpg/forge_tutorial" />

PonderPlayer / PonderUI

支持 scene / sceneid / component / componentid。

<PonderPlayer sceneid="rpg_scene" componentid="skill_panel" />

PonderRuntime / PonderRuntimeUI / PonderIndex

<PonderRuntime />

特殊组件

Teleport / portal

支持：

• to / :to
• disabled / :disabled

<Teleport to="#overlay-root">
  <Panel><Label text="传送到 Overlay" /></Panel>
</Teleport>

KeepAlive

支持：include、exclude、max / :max

<KeepAlive include="InventoryPanel,SkillPanel" :max="4">
  <component :is="store.get('currentPanel')" />
</KeepAlive>

Suspense

支持：timeout / :timeout，以及 #default、#fallback、#error 插槽。

使用说明

• 组件标签的别名由运行时解析，例如 Label、text、span 会指向同一类文本组件。
• 某些复杂组件依赖绑定值类型，例如 TreeList / Menu 需要 ITreeNode，SearchComponent 需要搜索配置对象。
• 组件有没有某个属性，并不等于它一定参与 retained 组合；组合语义最终仍由样式层的 opacity、overflow-clip、post-process、backdrop、blend 决定。