yumoqing/bricks

Fork 0

yumoqing 53265bfa1d bugfix

2025-10-12 17:59:59 +08:00

7.1 KiB

Raw Blame History

`bricks.Button` 技术文档

继承自：bricks.Layout

bricks.Button 是一个可交互的按钮组件，支持图标、文本标签、自定义样式以及点击事件处理。它基于 Flexbox 布局进行内容排列，适用于水平或垂直方向的内容展示。

概述

bricks.Button 提供了一个封装良好的按钮控件，可用于触发操作或导航。该组件可以包含：

图标（通过 bricks.Icon）
文本标签（通过 bricks.Text）
自定义 CSS 样式
工具提示（tooltip）
可配置的布局方向（横向/纵向）

所有子元素使用 Flexbox 排列，并可通过 item_rate 控制尺寸比例。

配置选项（Options）

属性名	类型	描述
`orientation`	String	布局方向，可选 `'horizontal'` 或默认为垂直 `'vertical'`。影响内部图标的排列方式。
`height`	CSS value	容器高度，默认 `100%`（由父级控制）。
`width`	CSS value	容器宽度，默认 `100%`。
`item_rate`	Number	子元素（图标/文字）的缩放比率，默认为 `1`。用于调整大小。
`tooltip`	String	鼠标悬停时显示的提示文本，设置到 DOM 的 `title` 属性上。
`color`	String	文字颜色（传递给 `Text` 组件）。
`bgcolor`	String	背景颜色（传递给 `Text` 组件）。
`nonepack`	Boolean	是否移除内边距和边框；若为 `true`，则 padding 设为 `0px`，border 为 `0`。
`name`	String	组件名称，用作 DOM 元素 ID 的基础。
`icon`	String	图标资源 URL 或路径，用于创建 `bricks.Icon` 实例。
`label`	String	显示的文字标签，支持国际化（i18n）。
`css`	Object	自定义 CSS 样式对象，将被合并到 DOM 元素的 `style` 中。
`action`	Object	点击按钮后执行的动作配置，详见下表。

`action` 对象结构

子属性	类型	描述
`target`	String	目标组件或模块名称。
`datawidget`	String	数据源控件名。
`datamethod`	String	数据获取方法名。
`datascript`	String	自定义脚本逻辑（如函数体字符串）。
`dataparams`	Object	发送至数据接口的参数。
`rtdata`	Boolean	是否实时刷新数据。
`actiontype`	String	动作类型，例如 `"navigate"`、`"submit"` 等。
`...`	Any	其他扩展字段，根据业务需求定义。

结构与布局

使用 <button> 元素作为根节点。
内部采用 display: flex 进行布局：
- 水平布局：flex-direction: row
- 垂直布局：flex-direction: column
支持图标在上、文字在下的垂直排布，或并排的水平排布。
默认具有 0.5rem 的内边距，除非设置了 nonepack: true。

{
  display: flex;
  justify-content: center;
  align-items: center;
  text-align: center;
  padding: 0.5rem; /* 或 0px（当 nonepack=true） */
}

方法说明

`constructor(opts)`

初始化按钮实例，继承自 Layout 并设置基本样式和属性。

参数

opts (Object): 配置选项对象。

行为

调用父类构造函数 super(opts)。
初始化默认样式对象（Flex 布局相关）。
根据 nonepack 设置是否去除 padding 和 border。
根据 orientation 设置 flexDirection 并记录简写形式（this.orient = 'h'|'v'）。
设置组件 ID 为 opts.name。
执行 opts_setup() 创建子组件（图标/文本）。
合并默认样式与用户自定义样式到 dom_element.style。

`create()`

创建底层 DOM 元素。

this.dom_element = document.createElement('button');

此方法在组件生命周期中自动调用，无需手动执行。

`opts_setup()`

根据配置项创建子控件（图标和/或文本），并将它们添加到当前容器中。

行为

如果存在 opts.icon，创建一个 bricks.Icon 实例，并绑定点击事件。
如果存在 opts.label，创建一个 bricks.Text 实例，启用 i18n 支持，并绑定点击事件。
所有子控件均通过 add_widget() 加入布局。
文本控件引用保存在 this.text_w 上，便于后续更新。

示例代码片段

if (this.opts.icon) {
  const icon = new bricks.Icon({
    rate: this.item_rate,
    url: this.opts.icon
  });
  this.add_widget(icon);
  icon.bind('click', this.target_clicked.bind(this));
}

`target_clicked(event)`

处理按钮点击事件的核心方法。

参数

event (Event): 浏览器原生事件对象。

行为

输出调试日志：bricks.debug('target_clicked() .... called ')
阻止事件冒泡（event.stopPropagation()）
触发组件自身的 'click' 事件，并携带完整 opts 数据。
若配置了 action，且启用了 debug 模式，则输出完整的 opts 到控制台。

示例输出（debug 模式）

debug:opts= { name: "btn_save", action: { target: "form", actiontype: "submit" }, ... }

事件机制

事件名	触发时机	携带数据
`click`	用户点击按钮时	`this.opts` 对象

可通过 .bind('click', handler) 监听此事件：

button.bind('click', function(data) {
  console.log('Button clicked:', data.action);
});

注册信息

bricks.Factory.register('Button', bricks.Button);

使得可以通过工厂模式动态创建按钮：

const btn = bricks.Factory.create('Button', {
  name: 'my_button',
  label: 'Submit',
  icon: '/icons/save.svg',
  action: {
    actiontype: 'submit',
    target: 'form1'
  }
});

使用示例

const myButton = new bricks.Button({
  name: 'btn_ok',
  label: 'OK',
  icon: '/icons/check.png',
  orientation: 'horizontal',
  item_rate: 1.2,
  color: '#fff',
  bgcolor: '#007bff',
  tooltip: 'Click to confirm',
  action: {
    actiontype: 'navigate',
    target: 'page_home'
  },
  debug: true
});

document.body.appendChild(myButton.dom_element);

注意事项

推荐配合 bricks.Icon 和 bricks.Text 使用以保持 UI 一致性。
若需完全自定义外观，请使用 css 属性覆盖样式。
nonepack: true 适合嵌入紧凑型 UI 区域。
所有文本自动支持国际化（i18n），前提是 bricks.app.i18n 已正确配置。

版本信息

框架：Bricks.js
组件路径：bricks.Button
最后更新：根据代码注释推断为近期维护版本

✅ 文档完

7.1 KiB Raw Blame History Unescape Escape

bricks.Button 技术文档

目录

概述