← 返回索引

范围：框架源码阅读与代码修改中的常见问题。

前置：元素系统。

交互类

Q: 元素的命中检测是怎么分层的？

A: 分层规则、各层职责与「哪一层可以覆盖」的完整表见 交互引擎。判断「该覆盖哪个方法」时以该表为准。

Q: mousePressed 的事件路由顺序是什么？

A: 固定优先级清单（事件接收顺序与消费判定）以 交互引擎 为准。排查点击未送达时按该清单的顺序检查。

Q: pressFlags 是什么？为什么 Slider 要那一串标志？

A: pressFlags 是按下期间控制事件去向的位标志，其定义、逐项含义与 Slider 的组合示例都在 元素系统。

布局类

Q: 惰性布局与立即布局的差异是什么，框架为何选择惰性？

A: 链式 setter 只调用 markDirty() 将脏标记向上传播，真正的 measure/arrange 推迟到渲染前的 layout() 一次性完成，因为连续修改多个属性只计算一遍，可避免中间态。完整机制、脏标记传播路径与容器行为见 布局系统。

覆盖层类

Q: OverlayTree 的「多根森林」是什么意思？

A: 每个覆盖层元素都是独立的根，根按加入顺序向上堆叠，同一元素重复推入会移动到最上层；结构与遍历细节见 覆盖层系统。

Q: 什么是四象限？

A: 四象限是覆盖层交互的划分模型，讲解见 Developer: 覆盖层。

Q: overlays().push 的各重载分别表示什么？

A: 推入浮层统一经 InteractionManager.overlays() 取 Screen 持有的 OverlayManager：push(el) 用默认值，点击外部自动关闭；指定标志时调用 push(el, dismissOnOutsideClick)；移除调用 overlays().remove(el)。语义与选择指南见 Developer: 覆盖层。

组件类

Q: 如何添加一个新的 UI 组件？

A: 见 常见实现模式: 添加新组件。

Q: 为什么 Screen 是元素的单一所有者？root/overlays/interactionManager 该由谁持有？

A: 所有权模型（谁构造、谁持有、InteractionManager 为什么不拥有覆盖层）的权威在 根树与层级系统。

Q: 为什么要用自界定泛型 Element<T extends Element<T>>？

A: 它使链式 setter 返回具体子类型，例如 new Button(...).size(100, 24) 仍可继续调用 .action(...) 而不丢失类型。定义与完整讨论见 元素系统。

Q: visible(false) 和 setEnabled(false) 是一回事吗？

A: 不是。visible(false) 隐藏整个子树，既不渲染也不参与命中，子元素随之隐藏；setEnabled(false) 只作用于该组件本身，组件照常渲染（按钮画成灰色），但不再消费鼠标事件，点击会落到下层元素。移除交互但保留在画面上时调用 setEnabled，彻底隐藏时调用 visible(false)。

Q: removeFromParent() 和 setParent() 有什么区别？

A: setParent() 只修改元素自身的父引用，不从父容器的子列表中移除元素，该操作供框架内部记录使用；removeFromParent() 将本元素从父容器的 children 中实际移除。元素从布局宿主迁移到浮层树时应调用 removeFromParent()，使旧宿主不再持有该元素，详见 元素系统。

Q: 创建 ItemView 时为何崩溃？

A: ItemView 需要读取所属 ItemStack，因此承载该组件的屏幕必须运行在游戏内（进入世界或至少游戏实例已就绪）；在主菜单或游戏外构造时无法取得 ItemStack，会直接崩溃。确认方式：将构造代码放在实际调用 setScreen 的时机，或先判断 Minecraft.getInstance().level != null。

Q: TextBox 的撤销步数上限是多少？

A: 撤销栈上限是 50 条记录（MAX_UNDO = 50），继续编辑会淘汰最旧的记录；AutoCompleteBox 用的是同一个上限值。

Q: AutoCompleteBox 的下拉何时弹出，最多显示多少条？

A: 下拉只在过滤出结果时打开，空查询或零命中时保持关闭；过滤渲染上限是 20 条，下拉面板最大高度 MAX_DD_H = 150 像素，超出部分滚动查看。

文档约定

  • 成表内容一律链接：命中分层、事件优先级、pressFlags、Screen 所有权、四象限这类成表内容一律以链接指向专篇，不在 FAQ 复制；该去重约定为文档维护不变量，修改时不得将表复制回 FAQ。
  • 链接只写文件名，不锚行号：被链接的专篇（交互引擎、元素系统、根树与层级系统 等）内容更新时，对应链接无需修改；若某篇改名或职责转移，FAQ 中所有对应链接需一并替换。

相关文档