猹件开发组

Appearance

On this page

变量与条件 ​

变量可以让页面记住当前会话中的选择、计数和开关状态。页面根级 vars 提供默认值，脚本使用 vars.<名称> 读取或修改它们；中文写法为 变量.<名称>。

页面变量 ​

变量名称可以使用 Unicode 字母、数字和下划线，但必须以字母或下划线开头。变量值支持字符串、数字和布尔值。

yaml
vars:
  page: 1 # 当前页码
  selected: "none" # 当前选择
  ready: false # 是否准备完成
  计数: 0 # 中文变量名同样可用
text
vars.page = vars.page + 1
vars.selected = "item_a"
变量.ready = true
变量.计数 = 变量.计数 + 1

变量修改只影响当前打开的页面会话。重新打开页面后，会重新使用页面文件中的默认值，除非服务端业务再次下发新的变量状态。

页面 open、组件 create、页面 close 和自定义方法共享同一份会话变量。因此可以在 open 中准备默认状态，在方法中集中修改，再让文字、布局和条件自动响应。

text
方法.初始化()
yaml
methods:
  初始化: |-
    vars.ready = true
    vars.title = "加载完成"

响应式文字 ​

文本组件的 text.value 与按钮的 button.label 可以使用 {...} 读取变量。变量变化后，文字会自动显示最新值。

text
当前页：{vars.page}
当前选择：{vars.selected}
已完成：{vars.ready}

花括号内支持四则运算和括号，例如 {vars.current / vars.total * 100}%。需要显示普通花括号时，连续写两个左花括号或两个右花括号。

完整用法请阅读响应式变量与实时文字。

只读数据 ​

vals 是 ChaUI 提供的只读常量，适合在条件和赋值右侧读取。它包含玩家状态、36 格背包汇总、主手/副手/盔甲物品、鼠标状态和 PlaceholderAPI 结果。

例如，可以根据玩家当前生命值切换警告文字：

text
if vals.player.health < vals.player.maxHealth * 0.3 {
  component("health_warning").visible = true
} else {
  component("health_warning").visible = false
}

鼠标常量也能直接用于条件：

text
if vals.mouse.leftDown {
  vars.status = "鼠标左键正按下"
}

所有玩家、背包、装备、鼠标和 PAPI 字段及中文写法统一收录在只读常量。

条件中常用的值 ​

值类型示例说明
布尔值vars.ready == true判断开关状态
数字vars.page >= 2判断数值范围
字符串vars.selected == "item_a"判断当前选择
玩家状态vals.player.food < 6根据玩家本地状态显示内容

条件表达式是只读判断。需要改变状态时，应在条件块内写入赋值语句。

数字表达式 ​

数字变量和布局属性支持四则运算及括号。建议使用括号明确运算顺序；取整、限制范围、插值和小数格式化请查看数学函数。

text
vars.total = (vars.base + 5) * 2
component("panel").layout.width = formula(window.width * 0.5)
component("panel").layout.x = formula((window.width - self.width) * 0.5)

这里必须区分两种赋值：vars.total = ... 会立即算出一个普通变量值；layout.width = formula(...) 会保存响应式布局公式。若写成 component("panel").layout.width = window.width * 0.5，脚本只会保存执行当时算出的固定宽度，之后调整窗口不会继续变化。

组件也可以读取其他组件的当前值或原始公式：

yaml
events:
  leftClick: |-
    vars.panelWidth = component("panel").layout.width
    vars.panelWidthFormula = component("panel").layout.expression("width").source

布局公式中还可以使用以下上下文：

英文写法中文写法含义
window.width窗口.宽当前 GUI 缩放坐标宽度
window.height窗口.高当前 GUI 缩放坐标高度
parent.x / parent.y父级.x / 父级.y父布局的位置
parent.width / parent.height父级.宽 / 父级.高父布局的尺寸
self.width / self.height自身.宽 / 自身.高当前组件自身尺寸

变量变化后，引用该变量的布局公式、显隐条件、文本内容和按钮文字会重新计算并刷新。

循环次数和计时器间隔也可以使用数字表达式，并在启动时读取一次当前值：

text
repeat(vars.pageSize * 2, vars.i) { vars.total = vars.total + vars.i }
timer("refresh", vars.refreshTicks) { vars.refreshCount = vars.refreshCount + 1 }

完整限制和生命周期请阅读循环与计时器。

页面条件字段与脚本条件 ​

如果组件需要长期跟随变量自动显隐，优先使用组件的 visibleWhen 或 enabledWhen。如果只需要在某次点击时执行一组动作，则使用脚本 if。

yaml
- id: ready_tip
  type: text
  visibleWhen: "vars.ready == true" # 变量变化后自动重新判断
  enabledWhen: "vars.page >= 1"
  layout:
    x: 20
    y: 20
    width: 120
    height: 20
  text:
    value: "准备完成"

下一页只读常量列出了页面能读取的玩家、背包、鼠标和 PAPI 数据；语法与事件介绍脚本可以在哪些事件中执行。