7.9 KiB
7.9 KiB
bricks.Image 及相关图标组件技术文档
基于
bricks.js框架的图像与图标类组件实现
概述
本模块定义了基于 bricks.JsWidget 的一系列图像与图标类组件，用于在网页中动态加载、显示和管理图像资源。主要包括：
bricks.Image：基础图像组件bricks.Icon：可缩放的图标组件（继承自Image）bricks.StatedIcon：支持状态切换的图标组件（继承自Icon）bricks.BlankIcon：占位图标组件（无图像内容）
所有组件均通过 bricks.Factory 注册，可在配置系统中通过类型名实例化。
1. bricks.Image
类定义
class extends bricks.JsWidget
构造函数
constructor(opts)
参数
| 参数 | 类型 | 描述 |
|---|---|---|
opts |
Object | 配置选项对象 |
opts 属性
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
url |
String | 否 | 图像的 URL 地址 |
default_url |
String | 否 | 当主 url 加载失败时使用的备用图像地址 |
行为
- 调用父类构造函数。
- 若传入
url，则自动调用set_url()设置图像源。
方法
create()
创建一个 <img> 元素作为组件的 DOM 根节点。
create()
说明：该方法由框架调用，在初始化时创建 DOM 结构。
set_url(url)
设置图像的 src 属性，并绑定错误处理以支持默认图像。
set_url(url)
参数
| 参数 | 类型 | 描述 |
|---|---|---|
url |
String | 图像资源 URL |
行为
- 将
this.url设为传入值。 - 如果配置了
default_url，则为<img>绑定onerror事件处理器，加载失败时自动切换到默认图。 - 设置
dom_element.src = url
set_default_url()
当图像加载失败时触发，切换至默认图像。
set_default_url()
行为
- 移除
onerror监听器，防止重复触发。 - 将
src设置为this.opts.default_url - 输出日志：
console.log('default_url', this.opts.default_url)
base64()
将当前图像绘制到 Canvas 并导出为 Base64 编码的 PNG 数据 URL。
base64()
返回值
{String}- 图像的 Data URL，格式如：data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...
实现逻辑
- 创建临时
<canvas>元素。 - 获取上下文并设置画布尺寸等于图像实际宽高。
- 使用
drawImage()将图像绘制到画布。 - 调用
toDataURL('image/png')生成 Base64 字符串。 - 返回结果（未去除头部前缀）。
⚠️ 注意：此方法依赖图像已完全加载，否则可能绘制空白或异常内容。
removeBase64Header(base64String)
移除 Base64 字符串中的 MIME 头部信息（例如 data:image/png;base64,）。
removeBase64Header(base64String)
参数
| 参数 | 类型 | 描述 |
|---|---|---|
base64String |
String | 完整的 Data URL 字符串 |
返回值
{String}- 纯 Base64 编码内容
示例
const clean = removeBase64Header('data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///ywAAAAAAQABAAACAUwAOw==');
// → 'R0lGODlhAQABAIAAAAAAAP///ywAAAAAAQABAAACAUwAOw=='
2. bricks.Icon
类定义
class extends bricks.Image
扩展 Image 类，提供基于字符单位（charsize）的响应式尺寸控制。
构造函数
constructor(opts)
参数
同 bricks.Image，额外支持以下选项：
opts 扩展属性
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
rate |
Number | 1 |
缩放倍率，相对于 charsize |
cwidth |
Number | 1 |
占据的字符宽度数 |
cheight |
Number | 1 |
占据的字符高度数 |
dynsize |
Boolean | true |
是否启用动态尺寸调整 |
行为
- 调用父类构造函数。
- 自动执行
options_parse()进行配置解析与尺寸设置。
方法
options_parse()
解析配置项并设置图标尺寸及图像源。
options_parse()
动作
- 设置
rate（默认为 1）。 - 计算样式尺寸：
siz = bricks.app.charsize * rate + 'px' - 调用
set_url(this.url)重新加载图像（确保尺寸生效后加载） - 设置
cwidth,cheight,dynsize - 调用
charsize_sizing()应用尺寸策略
✅ 提示：
charsize_sizing()是JsWidget提供的方法，用于根据字符网格进行布局适配。
3. bricks.StatedIcon
类定义
class extends bricks.Icon
支持多状态切换的图标组件，常用于表示不同 UI 状态（如开/关、在线/离线等）。
构造函数
constructor(opts)
参数
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
states |
Array<{state: String, url: String}> | 是 | 状态列表，每个状态包含名称和对应图像 URL |
state |
String | 否 | 初始状态名；若未指定，则使用第一个状态 |
示例配置
{
states: [
{ state: 'online', url: '/img/online.png' },
{ state: 'offline', url: '/img/offline.png' }
],
state: 'online'
}
行为
- 调用父类构造函数。
- 自动执行
options_parse()初始化状态。
方法
options_parse()
初始化状态机逻辑。
options_parse()
行为
- 若未定义
states数组，则直接返回。 - 若未设置初始
state，则设为states[0].state - 调用
set_state(this.state)激活初始状态
set_state(state)
切换当前图标状态，并更新图像。
set_state(state)
参数
| 参数 | 类型 | 描述 |
|---|---|---|
state |
String | 要切换到的状态名称 |
行为
- 更新
this.state - 遍历
this.states查找匹配项 - 找到后设置
this.url = s.url - 调用
super.options_parse()重新应用图像和尺寸
💡 支持链式调用与运行时状态变更。
4. bricks.BlankIcon
类定义
class extends bricks.JsWidget
一个不渲染图像的“空白图标”，仅保留图标布局结构，用作占位符。
构造函数
constructor(opts)
参数
同 Icon，支持：
rate: 缩放比例cwidth,cheight: 字符单元占用dynsize: 是否动态调整大小
行为
- 不创建图像元素。
- 仅调用
charsize_sizing()实现布局占位。
工厂注册
所有组件均已注册至 bricks.Factory，可在模板或配置中通过字符串类型名实例化：
bricks.Factory.register('Image', bricks.Image);
bricks.Factory.register('StatedIcon', bricks.StatedIcon);
bricks.Factory.register('Icon', bricks.Icon);
bricks.Factory.register('BlankIcon', bricks.BlankIcon);
使用示例（假设模板语法）
{
"type": "Icon",
"url": "/icons/save.png",
"rate": 1.5,
"cwidth": 2,
"cheight": 2
}
总结
| 组件 | 用途 | 特性 |
|---|---|---|
Image |
显示普通图像 | 支持错误 fallback、Base64 导出 |
Icon |
可缩放图标 | 基于 charsize 自适应尺寸 |
StatedIcon |
多状态图标 | 支持运行时状态切换 |
BlankIcon |
布局占位符 | 无图像，仅占空间 |
注意事项
- 图像跨域问题：使用
base64()方法时，若图像来自跨域服务器且未开启 CORS，Canvas 将被污染导致无法导出数据。 - 异步加载：
base64()应在图像load事件完成后调用，否则结果不可靠。 - 内存泄漏风险：频繁调用
base64()会创建大量临时 Canvas，建议缓存或节流。 - 默认图像防循环：确保
default_url图像本身有效，避免onerror死循环。
版本信息
- 框架：
bricks.js - 模块：
image.js - 最后更新：2025年4月5日
✅ 建议使用场景：
- 图标按钮、状态指示器、用户头像、动态图像预览等需要灵活控制图像行为的 UI 元素。