444 lines
10 KiB
Markdown
444 lines
10 KiB
Markdown
# Layout
|
||
|
||
Layout 是 Bricks.js 框架中的基础容器控件，用于组织和管理子控件（subwidgets）。它是所有布局类控件的基类，支持键盘导航、动态添加/删除子控件、标题与描述渲染等功能。
|
||
**类型**：容器控件，继承自 `bricks.JsWidget`
|
||
|
||
## 主要方法
|
||
|
||
| 方法名 | 说明 |
|
||
|--------|------|
|
||
| `add_widget(w, index)` | 向容器中添加一个控件，可指定插入位置；若未指定，则追加到末尾 |
|
||
| `remove_widget(w)` | 从容器中移除指定控件 |
|
||
| `clear_widgets()` | 清空容器内所有子控件 |
|
||
| `enable_key_select()` | 启用键盘选择功能，将该容器推入全局选择栈 |
|
||
| `disable_key_select()` | 禁用键盘选择，并从选择栈中弹出 |
|
||
| `select_next_item()` | 选中下一个可选控件（支持循环） |
|
||
| `select_previous_item()` | 选中上一个可选控件（支持循环） |
|
||
| `up_level()` | 键盘“返回”操作：退出当前层级 |
|
||
| `down_level()` | 键盘“进入”操作：进入下一层级的可选控件 |
|
||
| `enter_handler()` | 回车键处理：触发当前选中控件的 `click` 事件 |
|
||
| `key_handler(event)` | 键盘事件处理器，响应方向键与回车 |
|
||
| `build_title()` | 构建并添加标题控件（Title3） |
|
||
| `build_description()` | 构建并添加描述文本控件（Text） |
|
||
| `find_first_keyselectable_child()` | 查找第一个支持键盘选择的子控件 |
|
||
|
||
## 主要事件
|
||
|
||
| 事件名 | 触发时机 | 参数 |
|
||
|-------|--------|------|
|
||
| `on_parent` | 当控件被添加或从父容器中移除时触发 | parent: 当前父容器对象 |
|
||
| `element_resize` | 元素尺寸变化时触发（由 ResponsableBox 绑定使用） | params: 包含尺寸信息的对象 |
|
||
| `click` | 被 dispatch 触发时模拟点击行为 | - |
|
||
|
||
## 源码例子
|
||
|
||
```json
|
||
{
|
||
"id": "main_layout",
|
||
"widgettype": "Layout",
|
||
"options": {
|
||
"title": "主界面布局", // 显示标题（i18n 支持）
|
||
"description": "这是一个示例布局容器", // 描述文本
|
||
"keyselectable": true // 启用键盘导航
|
||
},
|
||
"subwidgets": [
|
||
{
|
||
"id": "title_widget",
|
||
"widgettype": "Title3",
|
||
"options": {
|
||
"otext": "欢迎使用系统",
|
||
"i18n": true,
|
||
"dynsize": true
|
||
}
|
||
},
|
||
{
|
||
"id": "menu_container",
|
||
"widgettype": "VBox",
|
||
"options": {
|
||
"keyselectable": true
|
||
},
|
||
"subwidgets": [
|
||
{
|
||
"id": "btn_home",
|
||
"widgettype": "Button",
|
||
"options": {
|
||
"otext": "首页",
|
||
"i18n": true
|
||
}
|
||
},
|
||
{
|
||
"id": "btn_settings",
|
||
"widgettype": "Button",
|
||
"options": {
|
||
"otext": "设置",
|
||
"i18n": true
|
||
}
|
||
}
|
||
],
|
||
"binds": [
|
||
{
|
||
"actiontype": "method",
|
||
"wid": "btn_home",
|
||
"event": "click",
|
||
"target": "content_area",
|
||
"method": "loadPage",
|
||
"params": {
|
||
"page": "home"
|
||
},
|
||
"conform": {
|
||
"title": "确认跳转？",
|
||
"message": "是否要跳转到首页？",
|
||
"i18n": true
|
||
}
|
||
},
|
||
{
|
||
"actiontype": "method",
|
||
"wid": "btn_settings",
|
||
"event": "click",
|
||
"target": "content_area",
|
||
"method": "loadPage",
|
||
"params": {
|
||
"page": "settings"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"binds": [
|
||
{
|
||
"actiontype": "event",
|
||
"wid": "main_layout",
|
||
"event": "element_resize",
|
||
"target": "main_layout",
|
||
"dispatch_event": "reset_type"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
> **注释说明**：
|
||
> - 使用 `Layout` 作为根容器，启用键盘选择 (`keyselectable`)。
|
||
> - 内部包含标题和一个垂直菜单 VBox，菜单项为按钮。
|
||
> - 通过 `binds` 实现按钮点击后调用目标控件的方法。
|
||
> - `conform` 字段用于在执行前弹出确认对话框。
|
||
> - `element_resize` 事件可用于响应式布局调整（如在 ResponsableBox 中使用）。
|
||
|
||
---
|
||
|
||
# VBox
|
||
|
||
垂直布局容器，子控件按垂直方向排列。
|
||
**类型**：容器控件，继承自 `Layout`
|
||
|
||
## 主要方法
|
||
|
||
继承自 `Layout`，无额外独有方法。
|
||
|
||
## 主要事件
|
||
|
||
同 `Layout`
|
||
|
||
## 源码例子
|
||
|
||
```json
|
||
{
|
||
"id": "vertical_box",
|
||
"widgettype": "VBox",
|
||
"options": {
|
||
"keyselectable": true
|
||
},
|
||
"subwidgets": [
|
||
{
|
||
"id": "label_welcome",
|
||
"widgettype": "Text",
|
||
"options": {
|
||
"otext": "欢迎登录系统",
|
||
"i18n": true,
|
||
"css": "welcome-text"
|
||
}
|
||
},
|
||
{
|
||
"id": "input_username",
|
||
"widgettype": "TextInput",
|
||
"options": {
|
||
"placeholder": "请输入用户名",
|
||
"i18n": true
|
||
}
|
||
},
|
||
{
|
||
"id": "input_password",
|
||
"widgettype": "PasswordInput",
|
||
"options": {
|
||
"placeholder": "请输入密码",
|
||
"i18n": true
|
||
}
|
||
},
|
||
{
|
||
"id": "btn_login",
|
||
"widgettype": "Button",
|
||
"options": {
|
||
"otext": "登录",
|
||
"i18n": true
|
||
}
|
||
}
|
||
],
|
||
"binds": [
|
||
{
|
||
"actiontype": "method",
|
||
"wid": "btn_login",
|
||
"event": "click",
|
||
"target": "login_form_handler",
|
||
"method": "submit",
|
||
"datawidget": "input_username",
|
||
"datamethod": "getValue",
|
||
"dataparams": {},
|
||
"rtdata": {
|
||
"action": "/api/login"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
> **注释说明**：
|
||
> - `VBox` 自动应用 CSS 类 `vcontainer` 实现垂直布局。
|
||
> - 表单元素依次垂直排列。
|
||
> - 登录按钮绑定提交动作，获取输入框值并携带运行时数据发送请求。
|
||
|
||
---
|
||
|
||
# HBox
|
||
|
||
水平布局容器，子控件按水平方向排列。
|
||
**类型**：容器控件，继承自 `Layout`
|
||
|
||
## 主要方法
|
||
|
||
继承自 `Layout`
|
||
|
||
## 主要事件
|
||
|
||
同 `Layout`
|
||
|
||
## 源码例子
|
||
|
||
```json
|
||
{
|
||
"id": "toolbar",
|
||
"widgettype": "HBox",
|
||
"options": {},
|
||
"subwidgets": [
|
||
{
|
||
"id": "icon_home",
|
||
"widgettype": "Icon",
|
||
"options": {
|
||
"name": "home",
|
||
"size": "24px"
|
||
}
|
||
},
|
||
{
|
||
"id": "text_title",
|
||
"widgettype": "Text",
|
||
"options": {
|
||
"otext": "主页",
|
||
"i18n": true,
|
||
"css": "toolbar-title"
|
||
}
|
||
},
|
||
{
|
||
"id": "spacer",
|
||
"widgettype": "Filler"
|
||
},
|
||
{
|
||
"id": "btn_refresh",
|
||
"widgettype": "IconButton",
|
||
"options": {
|
||
"icon": "refresh",
|
||
"tooltip": "刷新数据",
|
||
"i18n": true
|
||
}
|
||
},
|
||
{
|
||
"id": "btn_more",
|
||
"widgettype": "MenuButton",
|
||
"options": {
|
||
"icon": "more_vert",
|
||
"menu": [
|
||
{ "text": "设置", "id": "settings", "i18n": true },
|
||
{ "text": "退出", "id": "logout", "i18n": true }
|
||
]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
> **注释说明**：
|
||
> - `HBox` 应用 `hcontainer` 样式实现水平排布。
|
||
> - 使用 `Filler` 占位实现右侧按钮靠右对齐。
|
||
> - 工具栏包含图标、文字、填充和操作按钮。
|
||
|
||
---
|
||
|
||
# Filler
|
||
|
||
弹性填充控件，用于在布局中占据剩余空间，常用于对齐目的。
|
||
**类型**：容器控件（但通常不放置子控件），继承自 `Layout`
|
||
|
||
## 主要方法
|
||
|
||
无特殊方法，主要用于样式布局
|
||
|
||
## 主要事件
|
||
|
||
无
|
||
|
||
## 源码例子
|
||
|
||
```json
|
||
{
|
||
"id": "footer_bar",
|
||
"widgettype": "HBox",
|
||
"subwidgets": [
|
||
{
|
||
"id": "status",
|
||
"widgettype": "Text",
|
||
"options": {
|
||
"otext": "就绪",
|
||
"i18n": true
|
||
}
|
||
},
|
||
{
|
||
"id": "flex_spacer",
|
||
"widgettype": "Filler"
|
||
// 占据中间空白区域
|
||
},
|
||
{
|
||
"id": "btn_close",
|
||
"widgettype": "Button",
|
||
"options": {
|
||
"otext": "关闭",
|
||
"i18n": true
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
> **注释说明**：
|
||
> - `Filler` 控件自动获得 `flex: 1` 特性（通过 CSS 类 `filler` 实现），撑开中间区域。
|
||
> - 实现左-中-右布局结构。
|
||
|
||
---
|
||
|
||
# ResponsableBox
|
||
|
||
响应式布局容器，能根据宽高比自动切换横竖排布模式。
|
||
**类型**：容器控件，继承自 `Layout`
|
||
|
||
## 主要方法
|
||
|
||
| 方法名 | 说明 |
|
||
|-------|------|
|
||
| `reset_type(event)` | 响应尺寸变化事件，根据宽高比切换 CSS 类实现布局反转 |
|
||
|
||
## 主要事件
|
||
|
||
| 事件名 | 触发时机 |
|
||
|-------|---------|
|
||
| `element_resize` | 尺寸改变时触发，由自身监听 |
|
||
|
||
## 源码例子
|
||
|
||
```json
|
||
{
|
||
"id": "responsive_panel",
|
||
"widgettype": "ResponsableBox",
|
||
"subwidgets": [
|
||
{
|
||
"id": "sidebar",
|
||
"widgettype": "VBox",
|
||
"options": {
|
||
"css": "sidebar"
|
||
},
|
||
"subwidgets": [
|
||
{
|
||
"id": "nav_item_1",
|
||
"widgettype": "Button",
|
||
"options": {
|
||
"otext": "仪表盘",
|
||
"i18n": true
|
||
}
|
||
},
|
||
{
|
||
"id": "nav_item_2",
|
||
"widgettype": "Button",
|
||
"options": {
|
||
"otext": "报表",
|
||
"i18n": true
|
||
}
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"id": "main_content",
|
||
"widgettype": "Filler",
|
||
"subwidgets": [
|
||
{
|
||
"id": "dynamic_view",
|
||
"widgettype": "urlwidget",
|
||
"options": {
|
||
"url": "/views/home.json",
|
||
"method": "GET"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
> **注释说明**：
|
||
> - 当宽度大于高度时，设为横向布局（`.hcontainer`）；
|
||
> - 否则设为纵向布局（`.vcontainer`），实现移动端友好适配。
|
||
> - 结合 `urlwidget` 实现内容区动态加载。
|
||
|
||
---
|
||
|
||
# FHBox / FVBox
|
||
|
||
带 `flexWrap: nowrap` 的固定行/列布局容器。
|
||
- **FHBox**：水平不可换行容器
|
||
- **FVBox**：垂直不可换行容器
|
||
**类型**：容器控件，分别继承自 `HBox` 和 `VBox`
|
||
|
||
## 主要方法
|
||
|
||
无独有方法
|
||
|
||
## 主要事件
|
||
|
||
同 `Layout`
|
||
|
||
## 源码例子（FHBox）
|
||
|
||
```json
|
||
{
|
||
"id": "fixed_toolbar",
|
||
"widgettype": "FHBox",
|
||
"options": {
|
||
"css": "no-wrap-toolbar"
|
||
},
|
||
"subwidgets": [
|
||
{ "id": "btn_1", "widgettype": "Button", "options": { "otext": "新建" } },
|
||
{ "id": "btn_2", "widgettype": "Button", "options": { "otext": "编辑" } },
|
||
{ "id": "btn_3", "widgettype": "Button", "options": { "otext": "删除" } },
|
||
{ "id": "btn_4", "widgettype": "Button", "options": { "otext": "导出" } },
|
||
{ "id": "btn_5", "widgettype": "Button", "options": { "otext": "打印" } }
|
||
]
|
||
}
|
||
```
|
||
|
||
> **注释说明**：
|
||
> - 使用 `FHBox` 防止工具栏按钮换行，超出部分可通过滚动查看。
|
||
> - 适用于需要保持一行显示的操作栏场景。 |