bricks/aidocs/floaticonbar.md

bricks.IconBar 及相关组件技术文档

---

概述

bricks.IconBar 是一个基于 bricks.HBox 的 UI 组件类，用于创建水平排列的图标工具栏。它支持动态图标、点击事件分发、响应式尺寸调整等功能。该模块还包含多个扩展类：

• bricks.IconTextBar：带文本标签的图标栏。
• bricks.FloatIconBar：浮动式图标栏，鼠标悬停时显示完整图标组。
• bricks.FloatIconTextBar：结合浮动与图文混合的增强型工具栏。

这些组件常用于构建轻量级、可定制的工具栏或操作面板。

---

基础结构

var bricks = window.bricks || {};

确保 bricks 全局命名空间存在，避免覆盖已有内容。

---

1. bricks.IconBar

类继承关系

class extends bricks.HBox

继承自 HBox（水平布局容器），实现横向排列子控件。

配置参数 (opts)

参数名	类型	默认值	说明
cheight	Number	2	子项高度倍率（相对于字符单位）
rate	Number	1	缩放比例因子
margin	String	'10px'	图标之间的左右边距
tools	Array	[]	工具定义数组，每个元素为一个工具描述对象

tools 数组项结构

属性	类型	是否必需	说明
name	String	否	图标的唯一标识名称（用于事件分发和 DOM ID）
icon	String	是（非 blankicon）	SVG 图标 URL 或资源路径
rate	Number	否	单独设置该图标的缩放比例（优先于全局 rate）
dynsize	Boolean	否	是否启用动态尺寸调整
tip	String	否	提示文本（暂未在 IconBar 中直接使用）

特殊情况：若 name === 'blankicon'，则生成空白占位符图标。

构造函数行为

constructor(opts)

1. 默认值填充：

   • 若未指定 cheight，默认设为 2
   • 若未指定 rate，默认设为 1

2. 调用父类构造器：

   super(opts);
   

3. 样式设置：

   • 添加 CSS 类名 'childrensize'
   • 设置主轴对齐方式为居中（alignItems: center）

4. 遍历 tools 创建子控件：

   • 复制每个工具配置并补充通用属性（如 cheight, cwidth, dynsize）
   • 调用 build_item(opts) 创建具体控件
   • 设置左右 margin 和 cursor 样式为 pointer
   • 若有 name，设置对应 widget 的 ID
   • 绑定点击事件并通过 regen_event 分发事件
   • 将控件加入容器

5. 内部高度记录：

   • 使用 this.height_int 记录所有子控件中的最大高度（像素值），便于外部布局参考。

---

方法详解

build_item(opts) → Widget

根据配置创建单个图标控件。

行为逻辑：

• 计算实际高度：h = bricks.app.charsize * rate * opts.cheight
• 更新 this.height_int 以保持最大高度
• 判断是否为 blankicon：
  • 是 → 返回 new bricks.BlankIcon({...})
  • 否 → 使用 opts.icon 作为 url 创建 bricks.Svg 实例
• 绑定点击事件到 regen_event(desc, event)
• 返回创建的控件

regen_event(desc, event)

处理图标点击事件，并触发两个事件：

this.dispatch(desc.name, desc);        // 以 name 为事件类型分发
this.dispatch('command', desc);        // 统一命令事件

同时阻止事件冒泡和默认行为：

event.preventDefault();
event.stopPropagation();

此设计适用于菜单/按钮点击后不希望影响页面其他部分的操作场景。

---

2. bricks.IconTextBar（图文混合图标栏）

类继承关系

class extends bricks.IconBar

重写了 build_item 方法以支持图标+文字组合。

build_item(opts) 实现细节

返回一个 HBox 容器，内含：

1. SVG 图标（可选）

   • 来源：opts.icon
   • 属性包括 rate, dynsize

2. 文本标签（可选）

   • 使用 bricks.Text 显示 opts.label
   • 支持国际化（i18n: true）、自动换行（wrap: true）、左对齐（haligh: 'left'）

3. 整体包装

   • 包裹在一个 HBox 中，宽度自适应，高度自动计算
   • 绑定点击事件至 regen_event(opts)
   • 更新 height_int（基于 charsize * rate）

⚠️ 注意：图标与文本共存时垂直居中对齐由外层 HBox 控制。

---

3. bricks.FloatIconBar（浮动图标栏）

类继承关系

class extends bricks.HBox

实现“仅显示浮出按钮，悬停时展开全部图标”的交互模式。

配置参数 (opts)

同 IconBar，但只显示一个小浮点按钮，其余图标隐藏。

构造函数逻辑

1. 创建浮出按钮：

   this.float_w = new bricks.Svg({ url: bricks_resource('imgs/float-out.png') });
   

   • 绑定 mousemove 事件显示图标栏
   • 添加到容器

2. 创建图标主体：

   this.icons_box = this.build_bar(opts);
   

   • 默认调用 new bricks.IconBar(opts)
   • 初始隐藏（display: none）

3. 设置容器高度等于 icons_box.height_int

4. 绑定全局点击事件隐藏图标栏（通过 Body.click）

方法说明

方法	功能
build_bar(opts)	工厂方法，创建内部图标栏实例（可被子类重写）
show_icons()	显示图标栏（display: flex）
hide_icons()	隐藏图标栏（display: none）

📌 交互逻辑：鼠标移上浮点按钮 → 显示图标；点击任意空白区域 → 隐藏图标。

---

4. bricks.FloatIconTextBar（浮动图文栏）

类继承关系

class extends bricks.FloatIconBar

扩展 FloatIconBar，使其内部使用 IconTextBar 替代 IconBar。

核心重写方法

build_bar(opts) {
    return new bricks.IconTextBar(opts);
}

✅ 效果：浮出后显示带文字说明的图标按钮组，适合需要语义化提示的场景。

---

工厂注册

以下语句将各组件注册到 bricks.Factory，支持通过字符串名称动态创建实例：

bricks.Factory.register('IconBar', bricks.IconBar);
bricks.Factory.register('IconTextBar', bricks.IconTextBar);
bricks.Factory.register('FloatIconBar', bricks.FloatIconBar);
bricks.Factory.register('FloatIconTextBar', bricks.FloatIconTextBar);

使用示例（工厂方式）

var bar = bricks.Factory.create('IconTextBar', {
    tools: [
        { name: 'save', icon: '/icons/save.svg', label: 'Save File' },
        { name: 'print', icon: '/icons/print.svg', label: 'Print' }
    ],
    margin: '8px',
    rate: 1.2
});

---

示例配置

简单图标栏

new bricks.IconBar({
    cheight: 2,
    rate: 1,
    margin: '12px',
    tools: [
        { name: 'home', icon: '/icons/home.svg', tip: 'Go Home' },
        { name: 'settings', icon: '/icons/settings.svg' },
        { name: 'blankicon' }, // 占位符
        { name: 'logout', icon: '/icons/logout.svg' }
    ]
});

图文混合栏

new bricks.IconTextBar({
    rate: 1.1,
    tools: [
        { name: 'new', icon: '/icons/new.svg', label: 'New', tip: 'Create new file' },
        { name: 'open', icon: '/icons/open.svg', label: 'Open' },
        { name: 'help', label: 'Help', icon: '/icons/help.svg' }
    ]
});

浮动图文工具栏

new bricks.FloatIconTextBar({
    tools: [
        { name: 'cut', icon: '/icons/cut.svg', label: 'Cut' },
        { name: 'copy', icon: '/icons/copy.svg', label: 'Copy' },
        { name: 'paste', icon: '/icons/paste.svg', label: 'Paste' }
    ],
    rate: 1
});

---

设计特点总结

特性	描述
🔧 模块化设计	所有功能拆分为可复用类，便于扩展
🖱️ 交互友好	支持点击、悬停展开、事件拦截
📏 响应式尺寸	基于 charsize 和 rate 实现相对缩放
🔔 事件驱动	通过 dispatch 发送命名事件，解耦 UI 与业务逻辑
🧩 工厂模式支持	可通过字符串动态创建组件

---

注意事项

1. 依赖前提：

   • 必须已加载 bricks.HBox, bricks.Svg, bricks.Text, bricks.BlankIcon, bricks.Body
   • bricks.app.charsize 需已初始化
   • bricks_resource() 函数需可用（用于资源路径解析）

2. 性能建议：

   • 工具数量较多时建议使用 FloatIconBar 减少视觉干扰
   • 避免频繁重建整个 IconBar，应缓存实例

3. 样式定制：

   • 推荐通过 set_style() 或外部 CSS 修改外观
   • 不推荐直接修改内部 DOM 结构

---

版本信息

• 作者：Bricks Framework Team
• 版本：1.0
• 最后更新：2025年4月5日

---

📌 文档结束