2025-11-19 12:30:39 +08:00

9.0 KiB

Raw Blame History

`bricks.Toolbar` 技术文档

模块：bricks.Toolbar
继承自：bricks.Layout
用途：创建可配置的工具栏组件，支持水平/垂直布局、动态工具项生成、点击事件分发及可移除按钮功能。

概述

bricks.Toolbar 是一个基于 bricks.Layout 的类，用于构建可视化工具栏。它支持横向或纵向排列的按钮工具项，并提供灵活的配置选项，包括图标、标签、样式、事件绑定等。工具栏中的每个工具项可以触发命令事件，并可选择性地添加“删除”图标以支持动态移除。

该组件使用异步方式创建工具项，确保渲染性能，并通过 bricks.widgetBuild 工厂方法统一创建子控件。

构造函数

`constructor(options)`

初始化工具栏实例。

参数

参数名	类型	说明
`options`	Object	配置对象，继承自 `bricks.Layout` 并扩展以下属性

`options` 属性

属性	类型	默认值	说明
`orientation`	String	`'horizontal'`	布局方向：`'horizontal'` 或 `'vertical'`
`target`	Any	`undefined`	可选的目标引用，会在事件数据中传递
`interval`	String 或 Number	`'10px'`	工具项之间的间隔尺寸（CSS 单位）
`tools`	Array<Object>	`[]`	工具项描述数组，每项包含图标、名称、标签等信息
`css`	String	`'toolbar'`	自定义 CSS 前缀类名

示例

var toolbar = new bricks.Toolbar({
    orientation: 'horizontal',
    target: myComponent,
    interval: '15px',
    css: 'my-toolbar',
    tools: [
        { name: 'save', label: '保存', icon: 'save-icon.svg' },
        { name: 'delete', label: '删除', icon: 'del-icon.svg', removable: true }
    ]
});

实现细节

根据 orientation 创建 HScrollPanel（水平）或 VScrollPanel（垂直）作为内部容器。
添加对应 CSS 类：.htoolbar 或 .vtoolbar。
启用键盘选择：enable_key_select()。
使用 schedule_once 延迟调用 createTools()，避免阻塞主线程。

成员变量

变量	类型	描述
`bar`	`bricks.HScrollPanel` / `bricks.VScrollPanel`	内部滚动面板容器
`toolList`	Array<Widget>	存储所有已创建的工具按钮实例
`clicked_btn`	Widget 或 null	当前被激活（点击）的按钮
`preffix_css`	String	CSS 类前缀，用于激活状态样式

方法说明

`add_interval_box()`

在当前工具栏中插入一个间隔空白区域（JsWidget），其大小由 options.interval 控制，方向根据 orientation 决定。

行为逻辑

若为垂直布局 → 设置高度
若为水平布局 → 设置宽度

示例效果

width: 10px; /* 水平间距 */
height: 10px; /* 垂直间距 */

调用时机：在 createTools() 中，两个工具之间自动插入。

`async createTools()`

异步批量创建所有工具项。

流程

遍历 this.opts.tools
调用 createTool(desc) 逐个创建
在非最后一个工具后调用 add_interval_box()

注意事项

使用 await 确保顺序执行（可用于动画或依赖加载）
初始延迟 10ms 执行（通过 schedule_once(..., 0.01)）

`async createTool(desc)`

创建单个工具按钮。

参数

参数	类型	说明
`desc`	Object	工具描述对象，结构如下

`desc` 结构（工具项配置）

属性	类型	是否必需	说明
`name`	String	✅	工具唯一标识符（用于事件名）
`label`	String	❌	显示文本
`icon`	String	❌	图标 URL 或 class 名称
`css`	String	❌	自定义按钮 CSS 类
`removable`	Boolean	❌	是否显示删除图标，默认 `false`

返回值

{Promise<bricks.Widget>}：成功时返回按钮控件；失败返回 undefined

内部逻辑

构造 widgetBuild 所需的选项
调用 bricks.widgetBuild(options) 异步创建按钮
绑定 click 事件到 do_handle
将按钮加入 toolList 和 bar 容器
若 removable == true，调用 add_removable(w)
触发 remove 事件（当用户点击删除图标时）

`remove_item(w, event)`

从工具栏中移除指定工具项。

参数

参数	类型	说明
`w`	Widget	要移除的按钮控件
`event`	Event	DOM 事件对象

动作

从 bar 中移除控件
取消选中状态
从 toolList 数组中删除
解绑 click 事件监听器
分发 remove 事件，携带 tool_opts
阻止事件冒泡和默认行为

`do_handle(tool, event)`

处理工具按钮点击事件。

参数

参数	类型	说明
`tool`	Widget	被点击的按钮实例
`event`	Event	原始事件对象

功能

输出调试日志
构建事件数据 d，合并 tool.tool_opts 和可选 target
在 bar 上标记该按钮为选中状态
分发两个事件：
- 'command'：通用命令事件
- [tool.name]：以工具名命名的特定事件（如 'save', 'delete'）
更新激活按钮的 CSS 样式：
- 清除上一个激活按钮的样式
- 为当前按钮添加 prefix-css + '-button-active' 类
记录当前点击按钮至 this.clicked_btn

示例事件数据

{
    name: "save",
    label: "保存",
    icon: "save-icon.svg",
    target: myComponent
}

`add_removable(item)`

为指定工具项添加可删除的 SVG “×” 图标。

参数

参数	类型	说明
`item`	Widget	支持移除的工具按钮

条件判断

仅当 item.tool_opts.removable === true 时执行

实现步骤

加载 SVG 删除图标（路径来自 bricks_resource('imgs/delete.svg')）
创建 bricks.Svg 控件并插入按钮内
绑定点击事件到 remove_item
输出调试信息

错误处理

若 Svg 创建失败，输出错误日志

`click(name)`

模拟点击某个工具按钮（通过名称查找）。

参数

参数	类型	说明
`name`	String	工具项的 `name` 字段

行为

遍历 toolList，找到匹配 name 的按钮并触发其原生 DOM 的 .click() 方法，从而激活 do_handle。

应用场景

外部程序化触发某个命令
快捷键绑定

事件系统

Toolbar 支持以下事件分发：

事件名	触发条件	携带数据
`command`	任意工具被点击	合并后的工具选项 + target
`[tool.name]`	特定工具被点击	同上
`remove`	用户点击删除图标	被删除工具的原始 `tool_opts`

可通过 bind(event, handler) 监听这些事件。

示例监听

toolbar.bind('save', function(data) {
    console.log('保存操作触发:', data);
});

toolbar.bind('command', function(cmd) {
    console.log('收到命令:', cmd.name);
});

样式类说明

CSS 类	作用
`.htoolbar`	水平工具栏根元素样式
`.vtoolbar`	垂直工具栏根元素样式
`.toolbar-button-active`	激活按钮状态（默认前缀）
`[custom]-button-active`	自定义前缀激活样式（由 `css` 选项控制）

推荐在主题 CSS 中定义相关样式。

注册与工厂模式

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

允许通过字符串标识符创建实例：

bricks.create({
    widgettype: 'Toolbar',
    options: { ... }
});

使用示例

完整 HTML 示例

<div id="toolbar-container"></div>

<script>
var toolbar = new bricks.Toolbar({
    container: document.getElementById('toolbar-container'),
    orientation: 'horizontal',
    interval: '12px',
    target: app.mainView,
    css: 'app-toolbar',
    tools: [
        { name: 'new', label: '新建', icon: 'icons/new.svg' },
        { name: 'open', label: '打开', icon: 'icons/open.svg' },
        { name: 'save', label: '保存', icon: 'icons/save.svg', removable: true }
    ]
});

// 监听事件
toolbar.bind('save', function(data) {
    console.log('正在保存...', data.target);
});

// 程序触发
setTimeout(() => toolbar.click('new'), 1000);
</script>

调试信息

启用 bricks.debug 后，会输出以下信息：

工具构建失败
删除图标加载结果
点击事件详情
可移除功能启用状态

建议开发阶段开启调试模式。

总结

bricks.Toolbar 提供了一个现代化、可扩展的工具栏解决方案，具备以下特性：

✅ 支持横竖布局
✅ 动态工具生成
✅ 事件驱动架构
✅ 支持可删除项
✅ 样式可定制
✅ 兼容工厂创建模式

适合集成于富客户端应用、编辑器、IDE 工具条等场景。

9.0 KiB Raw Blame History Unescape Escape

bricks.Toolbar 技术文档

概述