客户端 JS API 参考

本页描述 <script> 运行时的现行 JavaScript 公开面。脚本执行在 Forge 客户端的 V8 环境里，推荐优先使用 bui:* 内建模块。

最小示例

import { command } from "bui:action"
import { defineStore, watchEffect } from "bui:state"
import { document } from "bui:ui"
import { onMounted } from "bui:lifecycle"
import { play } from "bui:sound"

const store = defineStore("rpg.hud", { hp: 100, mp: 50 })

function castSkill(skillId) {
  command("rpg.skill.cast", { skillId }, (result) => {
    store.set("mp", result.currentMp)
    play("ui/confirm")
  }, () => {
    play("ui/error")
  })
}

watchEffect(() => {
  if ((store.get("hp") ?? 0) <= 20) {
    document.getElementById("hpPanel")?.setOpacity(0.7)
  }
})

onMounted(() => {
  document.getElementById("root")?.focus()
})

内建模块

模块	主要导出
bui:state	defineStore、useStore、local、computed、watch、watchEffect、ref、reactive
bui:query	use、useWithStore、prefetch、prefetchWithStore、invalidate、invalidateWithStore、setData、setDataWithStore、getData、getDataWithStore
bui:ui	open、close、requestClose、document
bui:action	command、query、event
bui:drag	useDraggable、useDroppable、start、getData、isDragging、cancel
bui:element	create、createComponent、createTranslatableComponent、createEmptyComponent
bui:texture	empty、color、resource、sprite、gradient、sdf、icon、builtinSprite、group
bui:sound	play、playAt、stop
bui:hotkeys	register、unregister、clear、list
bui:lifecycle	onMounted、onUnmounted、onActivated、onDeactivated、nextTick
bui:di	provide、inject、provideGlobal

全局函数与对象

除模块导入外，运行时还会注入一组全局对象：

名称	作用
document	当前模板的 UI 文档入口，可 getElementById()
ref(initialValue)	创建响应式 ref，读写走 .value
computed(...)	创建计算字段
watch(...)	监听状态键变化
watchEffect(...)	自动收集依赖并重复执行
reactive(value)	创建响应式对象 / 集合包装
nextTick(callback)	下一帧执行
onMounted / onUnmounted / onActivated / onDeactivated	生命周期回调
provide / inject / provideGlobal	依赖注入

internalSyncStore、store、query 等上下文对象在模板运行时会按当前页面环境提供。

本地响应式对象

ref() 和 reactive() 的语义接近 Vue：

const keyword = ref("")
const filters = reactive({
  rarity: "epic",
  tags: ["weapon"]
})

keyword.value = "sword"
filters.tags.push("fire")

• ref(initialValue) 返回带 .value 的响应式引用，适合标量。
• reactive(initialValue) 适合对象、数组和集合；深层修改会回流到同一个响应式 symbol。
• 元素查询不要用 ref()，元素访问走 document.getElementById()。

状态与查询

import { defineStore } from "bui:state"
import { use } from "bui:query"

const store = defineStore("quest.panel", { quests: [] })
const result = use("quest.list", "quest.list", { zone: "tower" })

watchEffect(() => {
  store.set("quests", result.data ?? [])
})

use() 返回的查询对象包含：

• data
• isLoading
• isSuccess
• error
• isStale
• isFetching
• refetch()
• invalidate()

如果调用 use() 时没有显式传 store，运行时会使用默认 store。默认 store 通常由 defineStore() 或 local() 建立。

动作与 UI 生命周期

import { command, event } from "bui:action"
import { requestClose } from "bui:ui"

function submitBuild(payload) {
  command("build.start", payload, () => {
    event("build.panel.close")
    requestClose()
  })
}

• command() 用于有副作用的请求。
• query() 用于直接回调式只读请求。
• event() 用于单向通知或上报。
• requestClose() 比直接强关更适合页面级关闭语义。

纹理与元素创建

import { color, resource, sdf } from "bui:texture"
import { create } from "bui:element"

const badge = create("Label", { text: "Rare" })
const frame = sdf(8, 0xFF243248, 0xFF4AA3FF, 1)
const bg = resource("behemiron:textures/ui/panel.png")

bui:texture 暴露的是稳定模块子集。更复杂的纹理对象在运行时仍可继续链式变换和组合。

额外脚本绑定

这组对象不是 bui:* 模块，但会直接注入脚本环境：

名称	作用
Placeholder	解析占位符文本
Scheduler	主线程 / 异步 / 渲染线程调度
Debounce	防抖
Throttle	节流
Chat	聊天发送与历史读取
Player	当前玩家快照
ItemStack	物品快照工具
PotionEffect	药水效果读取
Container	BUI 容器相关工具

热键与音效

import { register } from "bui:hotkeys"
import { play } from "bui:sound"

const hotkeyId = register({ key: "K" }, () => {
  play("ui/click")
})

音效 ID 使用相对路径，例如 ui/click，不要补 sounds/ 前缀。

远程模块

运行时支持 https: 远程 ESM 导入。适合复用共享脚本，但依赖加载、缓存和版本行为仍受客户端运行时控制。

配合服务端时的边界

• 客户端脚本负责页面逻辑、局部状态、交互触发。
• 服务端负责模板注册、权威 sync:* 写入、command/query/event 处理器。
• 需要查看模板语法和组件支持面时，回到 /BehemironEngine/ui/reference/directives 与 /BehemironEngine/ui/reference/components。