设置绑定

普通页面的表单组件通常绑定 vars.*。原版菜单页面还可以把表单直接绑定到可写的 原版.设置.*，让拖动条、开关和选择框操作 Minecraft 的真实设置。

这种绑定不会依赖页面作者手写“设置音乐音量”之类的专用函数。ChaUI 会根据属性目录检查组件种类、值类型、范围、步长和允许值，错误配置不会产生隐式行为。

可直接复制的设置页

把下面内容保存为 plugins/ChaUI/pages/tutorial_video_options.yml。它替换 video_options，同时演示数字、布尔和枚举属性。

yaml

id: tutorial_video_options
version: 1
title: 教程视频设置
size:
  width: window.width
  height: window.height
coordinateMode: absolute
display:
  mode: vanilla
  vanilla:
    target: video_options
vars: {}
events: {}
methods: {}
elements:
  - id: music_volume
    type: slider
    layout:
      x: "window.width * 0.5 - 100"
      y: "window.height * 0.5 - 55"
      width: 200
      height: 16
    slider:
      bind: 原版.设置.声音.音乐音量
      orientation: horizontal
      thumbWidth: 10
      thumbHeight: 16
    events:
      input: 'log("音乐音量预览：{原版.设置.声音.音乐音量}")'
      change: 'log("音乐音量已提交：{原版.设置.声音.音乐音量}")'

  - id: fullscreen
    type: toggle
    layout:
      x: "window.width * 0.5 - 100"
      y: "window.height * 0.5 - 25"
      width: 200
      height: 20
    toggle:
      bind: 原版.设置.视频.全屏
      options:
        - label: 全屏：关闭
          value: false
        - label: 全屏：开启
          value: true
      align: center
    events: {}

  - id: graphics
    type: dropdown
    layout:
      x: "window.width * 0.5 - 100"
      y: "window.height * 0.5 + 5"
      width: 200
      height: 20
    dropdown:
      bind: 原版.设置.视频.图像品质
      maxVisibleOptions: 3
      options:
        - label: 流畅
          value: fast
        - label: 高品质
          value: fancy
        - label: 极佳
          value: fabulous
      align: center
    events: {}

  - id: back
    type: button
    layout:
      x: "window.width * 0.5 - 60"
      y: "window.height * 0.5 + 45"
      width: 120
      height: 20
    button:
      label: 返回
      align: center
    events:
      leftClick: "close()"

图片路径全部省略时，三个表单组件都会使用内置基础样式。手工保存文件后先执行 /chaui reload；如果通过编辑器保存，菜单包会立即发布，不需要 reload。随后从设置页进入视频设置即可测试。

为什么滑块可以省略范围

绑定 原版.设置.* 时，属性描述符已经给出了权威约束。上例音乐音量自动使用：

最小值 0.0；
最大值 1.0；
步长 0.01；
可写数字类型。

因此 slider.min、slider.max 和 slider.step 可以省略。显式填写时不能放宽或改变描述符，例如把音乐音量写成 0..100 会让页面校验失败。

绑定 vars.* 时没有原版描述符兜底，仍需按普通拖动条规则完整填写范围。

数字、布尔和枚举如何选择组件

属性类型	适用组件	可以省略	显式配置规则
数字	`slider`	描述符已有的 `min`、`max`、`step`	范围和步长必须与描述符兼容
布尔	`toggle`	`options`	显式选项只能使用布尔值 `false`、`true`，不能写字符串
枚举	`toggle`、`dropdown`	由描述符提供的选项	可以自定义显示文字，但每个 `value` 必须来自允许集合

例如图像品质允许写入 fast、fancy、fabulous。不能把显示文字“高品质”直接当成值，也不能写入目录中没有的 ultra。完整属性、范围和允许值见原版状态参考。

交互和保存顺序

有效交互按固定顺序执行：

组件先把合法新值写入 Minecraft 的实时设置状态；
再触发 events.input 或 events.change；
事件脚本读取到的已经是新值。

滑块拖动时会实时更新运行状态，让声音、亮度等设置立即产生预览效果。为了避免每跨一个 step 都写一次配置文件，ChaUI 会合并脏状态，并在以下时机保存：

滑块触发 change；
原版菜单正常关闭；
页面正常切换。

如果设置通过其他原版入口发生变化，绑定组件会继续从实时状态源读取新值，而不是永久保留页面打开时的旧副本。

编辑器预览不会改真实设置

原版菜单的编辑器预览会复制当前设置到一个可丢弃沙箱。你可以拖动音乐音量、切换全屏和选择画质来验证页面，但退出预览后，真实 Minecraft 设置不会被修改。

预览中的 input / change 顺序与真实页面一致。要确认声音实时预览和设置持久化，仍需保存后在真实替换页测试。

常见错误

现象	原因	修正
滑块显示但不能写入	路径只读、路径拼错或组件不是 `slider`	从属性目录复制完整可写数字路径
音量写成 `50` 被拒绝	音量范围是 `0.0..1.0`	使用 `0.5` 表示 50%
全屏选项没有绑定	`"true"` / `"false"` 被写成字符串	YAML 布尔值不要加引号
图像品质显示回退项	当前值不在页面选项中，或设备使用 `custom`	补齐允许选项；`custom` 只能读取，不能通过公共目录写入
`fabulous` 没有生效	当前设备或版本无法使用该画质	保留原值并给玩家可选的 `fast` / `fancy`

编辑器如何筛选绑定候选、验证冲突和隔离动作，见编辑器与隔离预览。

设置绑定 ​

可直接复制的设置页 ​

为什么滑块可以省略范围 ​

数字、布尔和枚举如何选择组件 ​

交互和保存顺序 ​

编辑器预览不会改真实设置 ​

常见错误 ​