bricks/docs/zh/layout.md

HBox

控件功能：水平布局容器，用于将子控件沿水平方向排列。
类型：容器控件
父类控件：bricks.Layout

初始化参数

• options (Object, 可选)：配置选项对象，继承自 Layout 的通用选项。
  • 无特有参数，构造函数中仅调用父类并设置 CSS 类 'hcontainer'。

主要事件

• 无特有事件。
• 继承自 Layout 的键盘导航事件支持（当启用 keyselectable 时）：
  • keydown：处理方向键（左/右切换层级，上/下切换选中项，Enter 触发点击）。

---

FHBox

控件功能：固定水平布局容器，防止子元素换行，适用于不可折行的水平排列场景。
类型：容器控件
父类控件：bricks.HBox → bricks.Layout

初始化参数

• options (Object, 可选)：配置选项对象。
  • 无额外参数，构造函数中调用父类后设置样式 flexWrap: 'nowrap'。

主要事件

• 与 HBox 相同，依赖 Layout 提供的键盘导航逻辑。
• 支持通过方向键进行焦点控制和 Enter 键触发点击。

---

VBox

控件功能：垂直布局容器，用于将子控件沿垂直方向排列。
类型：容器控件
父类控件：bricks.Layout

初始化参数

• options (Object, 可选)：配置选项对象。
  • 无特有参数，构造函数中仅设置 CSS 类 'vcontainer'。

主要事件

• 无特有事件。
• 同样支持 Layout 定义的键盘导航机制（上下选择、左右进入/退出层级等）。

---

FVBox

控件功能：固定垂直布局容器，防止子元素换行，适用于不可折行的垂直排列。
类型：容器控件
父类控件：bricks.VBox → bricks.Layout

初始化参数

• options (Object, 可选)：配置选项对象。
  • 无额外参数，构造函数中设置 flexWrap: 'nowrap'。

主要事件

• 与 VBox 相同，支持完整的键盘导航行为。

---

Filler

控件功能：弹性填充控件，用于在 Flex 布局中占据剩余空间，实现动态布局平衡。通常用于撑开其他组件间距。
类型：容器控件（但一般不添加子控件）
父类控件：bricks.Layout

初始化参数

• options (Object, 可选)：配置选项对象。
  • 无特有参数，构造函数中设置 CSS 类 'filler'。
  • 注释代码中曾计划设置 flexGrow: 1 和 overflow: auto，当前未启用。

主要事件

• 无特有事件。
• 支持被纳入键盘导航栈（若显式启用 keyselectable），但实际用途较少。

---

ResponsableBox

（注：类名可能应为 "ResponsiveBox"，拼写疑似笔误）

控件功能：响应式布局容器，能根据自身宽高比自动切换为横向或纵向布局模式。宽度大于高度时为横向（hcontainer），否则为纵向（vcontainer）。
类型：容器控件
父类控件：bricks.Layout

初始化参数

• opts (Object, 可选)：配置选项对象，传递给父类 Layout。
  • 构造函数中绑定 'element_resize' 事件以监听尺寸变化。

主要事件

• element_resize：当容器尺寸发生变化时触发，驱动 reset_type() 方法重新判断布局方向。
• 自动调整 CSS 类和宽高样式：
  • 宽 > 高：应用 'hcontainer'，高度 100%，宽度自适应。
  • 高 ≥ 宽：应用 'vcontainer'，宽度 100%，高度自适应。
• 支持嵌套键盘导航，行为由 Layout 统一管理。

---

Layout

虽未直接注册工厂名（但其子类已注册），Layout 是所有上述容器的基类，核心功能集中在此。

控件功能：基础布局容器类，提供通用的子控件管理、键盘可选支持、标题/描述构建、工具栏集成等功能。是所有布局控件的共同父类。
类型：容器控件
父类控件：bricks.JsWidget

初始化参数

• options (Object, 可选)
  • keyselectable (Boolean)：是否启用键盘选择功能，默认 false。
  • title (String)：可选标题文本，会生成 Title3 控件。
  • description (String)：可选描述文本，会生成 Text 控件。
  • toolbar (Object)：工具栏配置，用于创建 FloatTextIconBar。
  • 其他继承自 JsWidget 的通用参数。

主要事件

• keydown：全局绑定，由 enable_key_select() 激活，处理以下按键：
  • ArrowUp / ArrowDown：上下切换选中子控件。
  • ArrowLeft：调用 up_level()，返回上一层级。
  • ArrowRight：调用 down_level()，进入下一层级。
  • Enter：触发当前选中控件的 click 事件。
• on_parent：当控件被添加或移除出父容器时分发，通知子控件其父级变更。
• element_resize：仅 ResponsableBox 使用，但 Layout 提供 DOM 元素操作能力。
• click：可通过 enter_handler() 手动派发给选中子控件。

此外还提供以下关键方法（虽非事件，但影响事件流）：

• enable_key_select() / disable_key_select()：启用/禁用键盘导航，并维护全局栈 key_selectable_stack。
• add_widget(w, index)：添加子控件，自动插入 DOM 并建立父子关系。
• remove_widget(w) / clear_widgets()：移除控件，清理 DOM 与事件关联。
• select_item(w)：高亮指定子控件（需支持 .selected(bool) 方法）。