2025-11-18 14:59:26 +08:00

10 KiB

Raw Blame History

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 触发时模拟点击行为	-

源码例子

{
  "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

源码例子

{
  "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

源码例子

{
  "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

主要方法

无特殊方法，主要用于样式布局

主要事件

无

源码例子

{
  "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`	尺寸改变时触发，由自身监听

源码例子

{
  "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）

{
  "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 防止工具栏按钮换行，超出部分可通过滚动查看。

适用于需要保持一行显示的操作栏场景。

10 KiB Raw Blame History Unescape Escape

Layout

主要方法

主要事件

源码例子

VBox

主要方法

主要事件

源码例子

HBox

主要方法

主要事件

源码例子

Filler

主要方法

主要事件

源码例子

ResponsableBox

主要方法

主要事件

源码例子

FHBox / FVBox

主要方法

主要事件

源码例子（FHBox）

10 KiB

Raw Blame History