控件总览（按钮 / 文本 / 滑条 / 进度）

基本信息

属性	值
包路径	`com.cleanroommc.modularui.widgets`
顶层文件数	29（另有 `layout/` 6、`menu/` 6、`slot/` 10、`textfield/` 6）
公共基类	`Widget<W>`（`widget/Widget.java:47`）、`AbstractParentWidget<I,W>`、`DelegatingWidget`
交互接口	实现 `Interactable` 的控件可响应输入（`api/widget/Interactable.java`）

这一页把「行为相近、共享同一基类」的一族控件合并成表格，而不是每个控件一页——它们之间只有外观或取值范围差异，没有独立的扩展契约。

功能

按钮族（共享 `AbstractCycleButtonWidget`）

控件	文件	继承	说明
`AbstractCycleButtonWidget<W>`	`widgets/AbstractCycleButtonWidget.java:27`	`SingleChildWidget<W>` `implements Interactable`	在若干候选值间循环的基类
`CycleButtonWidget`	`widgets/CycleButtonWidget.java`	`AbstractCycleButtonWidget<CycleButtonWidget>`	单击切换到下一个候选值
`ToggleButton`	`widgets/ToggleButton.java`	`AbstractCycleButtonWidget<ToggleButton>`	两个状态（开/关），用 `toggleButton` 主题
`ButtonWidget<W>`	`widgets/ButtonWidget.java`	`Widget<W>`	普通按钮，点击触发 `IGuiAction`
`ContextMenuButton<W>`	`widgets/menu/ContextMenuButton.java`	`AbstractMenuButton<W>`	点击弹出菜单
`PageButton`	`widgets/PageButton.java`	`Widget<PageButton>` `implements Interactable`	翻页箭头，配合 `PagedWidget`

文本族

控件	文件	继承	说明
`TextWidget<W>`	`widgets/TextWidget.java`	`Widget<W>`	单行静态文本
`ScrollingTextWidget`	`widgets/ScrollingTextWidget.java`	`TextWidget<ScrollingTextWidget>`	文本过长时横向滚动
`RichTextWidget`	`widgets/RichTextWidget.java`	`Widget<RichTextWidget>` `implements IRichTextBuilder, Interactable`	富文本，支持 `§{...}` 颜色、`§n` 下划线等
`TextFieldWidget`	`widgets/textfield/TextFieldWidget.java`	`BaseTextFieldWidget<TextFieldWidget>`	单行输入框
`TextEditorWidget`	`widgets/textfield/TextEditorWidget.java`	`BaseTextFieldWidget<TextEditorWidget>`	多行输入框

RichTextWidget 的实际渲染语法可在仓库自带示例中看到（src/main/resources/assets/modularui2/guis/test.json:18）： "text": "§{#3058B8}Blue §nUnderlined§rBlue §{#469E8F}Mint Hello"。

数值与进度

控件	文件	继承	说明
`SliderWidget`	`widgets/SliderWidget.java`	`Widget<SliderWidget>` `implements Interactable`	连续/离散滑条
`ProgressWidget`	`widgets/ProgressWidget.java`	`Widget<ProgressWidget>`	进度条
`ColorPickerDialog`	`widgets/ColorPickerDialog.java`	`Dialog<Integer>`	取色器弹窗
`TransformWidget`	`widgets/TransformWidget.java`	`DelegatingWidget`	对子控件施加坐标变换
`SchemaWidget`	`widgets/SchemaWidget.java`	`Widget<SchemaWidget>` `implements Interactable`	从 JSON 构建控件树，见下方说明

`SchemaWidget`：JSON 界面描述

SchemaWidget 允许用 JSON 描述整个界面而不写 Java。仓库自带示例 src/main/resources/assets/modularui2/guis/test.json 展示了格式：

{
  "widgets": [
    { "name": "background", "type": "image", "fillParent": true,
      "src": "modularui2:textures/gui/background/background" },
    { "name": "player_inventory", "type": "player_inventory", "pos": "7,190" },
    { "name": "test_text", "type": "text", "pos": "10,10",
      "text": "§{#3058B8}Blue §nUnderlined§rBlue §{#469E8F}Mint Hello" }
  ]
}

⚠️ 该文件还带一个 __examples: 段（test.json:21-27）存放文档用示例坐标（pos: {x: 1.5, y: 2} 与字符串写法 _pos: "1.5,2"），属于示例数据而非控件。

列表与分页

控件	文件	继承	说明
`ListWidget<I,W>`	`widgets/ListWidget.java:34`	`AbstractScrollWidget<I,W>` `implements ILayoutWidget, IParentWidget`	垂直滚动列表（同时可滚动，见「滚动控件」）
`ListValueWidget<T,I,W>`	`widgets/ListValueWidget.java:9`	`ListWidget<I,W>`	带值绑定的列表基类
`SortableListWidget<T>`	`widgets/SortableListWidget.java:23`	`ListValueWidget<T, SortableListWidget.Item<T>, …>`	可拖拽排序的列表
`CategoryList`	`widgets/CategoryList.java`	`AbstractParentWidget<IWidget, CategoryList>` `implements Interactable, ILayoutWidget`	侧边分类栏
`PagedWidget<W>`	`widgets/PagedWidget.java`	`AbstractParentWidget`	分页容器，配 `PageButton`
`Expandable`	`widgets/Expandable.java`	`Widget<Expandable>` `implements Interactable, IViewport`	可折叠/展开区块
`DropDownMenu`	`widgets/DropDownMenu.java`	`SingleChildWidget<DropDownMenu>` `implements Interactable`	下拉菜单容器
`SlotGroupWidget`	`widgets/SlotGroupWidget.java`	`ParentWidget<SlotGroupWidget>`	槽位分组容器

显示型（只画不点）

控件	文件	继承	说明
`ItemDisplayWidget`	`widgets/ItemDisplayWidget.java`	`Widget<ItemDisplayWidget>` `implements RecipeViewerIngredientProvider`	纯展示物品，并作为配方原料提供给配方查看器
`FluidDisplayWidget`	`widgets/FluidDisplayWidget.java`	`AbstractFluidDisplayWidget<FluidDisplayWidget>`	纯展示流体
`EntityDisplayWidget`	`widgets/EntityDisplayWidget.java`	`implements IDrawable`（不是 Widget）	渲染一个实体缩略图
`VoidWidget`	`widgets/VoidWidget.java`	`EmptyWidget`	什么都不画的占位控件

EntityDisplayWidget 实现的是 IDrawable 而不是 IWidget—— 它不能作为容器子控件，只能当背景/图标用。

交互

所有 implements Interactable 的控件按 Interactable 的 12 个回调响应输入（api/widget/Interactable.java:29-:111）。返回值是 Interactable.Result （定义于 api/widget/Interactable.java:172），有 4 个常量，由 accepts / stops 两个布尔量组合而成：

常量	行	`accepts`	`stops`	语义（源码注释）
`IGNORE`	`:177`	false	false	Nothing happens.
`ACCEPT`	`:181`	true	false	Interaction is accepted, but other widgets will get checked.
`STOP`	`:185`	false	true	Interaction is rejected and no other widgets will be checked.
`SUCCESS`	`:189`	true	true	Interaction is accepted and no other widgets will be checked.

因此「接受并吞掉事件」是 SUCCESS 而不是 ACCEPT——ACCEPT 仍会继续检查其他控件。