bricks/aidocs/svg.md

bricks.Svg 与相关组件技术文档

本文件为 bricks.Svg 及其派生类（StatedSvg 和 MultipleStateIcon）的详细技术说明文档。这些类用于在网页中动态加载、渲染和控制 SVG 图标的行为，支持颜色设置、闪烁动画、URL 动态更新以及状态切换功能。

---

模块结构

var bricks = window.bricks || {};

所有组件均挂载于全局命名空间 bricks 下，并通过 bricks.Factory.register() 注册为可实例化的 UI 组件。

---

1. bricks.Svg 类

简介

bricks.Svg 是一个继承自 bricks.VBox 的类，用于显示并控制单个 SVG 图标的可视化行为。它支持从远程 URL 加载 SVG 内容，动态着色、闪烁动画等特性。

继承关系

class Svg extends bricks.VBox

---

构造函数：constructor(opts)

参数

参数	类型	必需	默认值	描述
opts.rate	Number	否	1	缩放比例，影响宽度和高度
opts.url	String	否	-	SVG 文件的 URL 地址
opts.blink	Boolean	否	false	是否启用闪烁效果
opts.color	String (CSS Color)	否	由 bricks.app.get_color() 获取	SVG 填充颜色
opts.blinkcolor	String (CSS Color)	否	由 bricks.app.get_bgcolor() 获取	闪烁时的颜色
opts.blinktime	Number	否	0.5	闪烁间隔时间（秒）

⚠️ 注意：opts.cwidth 和 opts.cheight 将被自动设为 opts.rate，实现等比缩放。

行为说明

• 调用父类 super(opts) 初始化容器。
• 若未指定 color 或 blinkcolor，则使用应用级默认前景/背景色。
• 若提供了 url，调用 set_url(url) 加载 SVG 内容。
• 支持动态尺寸（dynsize: true）。

---

方法列表

set_url(url)

从指定 URL 加载 SVG 内容并插入到 DOM。

参数

• url (String | null)：SVG 文件路径或网址；若为 null 或空，则清空内容。

流程

1. 清除当前内容（若无 url）。
2. 使用 fetch() 请求 SVG 文本。
3. 验证响应是否以 <svg 开头（防止 XSS）。
4. 存储原始 SVG 文本至 this.svgText。
5. 调用 set_colored_svg(color) 渲染带颜色的 SVG。
6. 如果启用了 blink，启动闪烁动画。

✅ 安全提示：仅允许标准 <svg ...> 标签开头的内容，避免注入风险。

---

set_color(color)

设置 SVG 的填充颜色，并立即重新渲染。

参数

• color (String)：合法 CSS 颜色值（如 "red", "#00ff00", "rgb(255,0,0)"）

行为

• 更新 this.color
• 调用 set_colored_svg(color)

---

set_blinkcolor(color)

设置闪烁状态下的颜色。

参数

• color (String)：目标闪烁颜色

行为

• 更新 this.blinkcolor
• 自动补全 blinktime 为 0.5（如果尚未设置）

---

set_colored_svg(color)

将模板中的 {color} 占位符替换为实际颜色值，并更新 DOM。

参数

• color (String)：要应用的颜色

实现

var svgText = bricks.obj_fmtstr({color: color}, this.svgText);
this.dom_element.innerHTML = svgText;

📌 依赖 bricks.obj_fmtstr 实现字符串模板替换（类似 {color} → "#ff0000"）

---

start_blink()

启动周期性颜色闪烁动画。

条件

• 必须设置了 blinktime > 0
• 必须定义了 blinkcolor

行为

• 若当前没有运行任务（!this.blink_task），调用 _blink() 启动首次切换。

---

_blink()

私有方法：执行一次颜色切换，并安排下一次调用。

逻辑

• 当前颜色是正常色 → 切换为 blinkcolor
• 当前颜色是 blinkcolor → 切换回正常 color
• 使用 schedule_once(fn, delayInSeconds) 安排下次执行（避免阻塞主线程）

🔁 此方法形成递归循环，直到 end_blink() 被调用。

---

end_blink()

停止闪烁动画。

行为

• 设置 this.blink_task = null，中断 _blink() 的递归调度链。

---

set_ancent_color(e)

从父元素的计算样式中获取文本颜色，并设置为 SVG 颜色。

应用场景

适用于希望图标跟随上下文主题色的情况。

实现

var pstyle = getComputedStyle(this.parent);
this.set_color(pstyle.color);

---

2. bricks.StatedSvg 类

简介

继承自 bricks.Svg，支持多个状态（state），每个状态对应不同的 SVG 资源。点击可按顺序切换状态。

构造函数：constructor(opts)

扩展参数

参数	类型	必需	描述
opts.states	Array<{state: String, url: String}>	是	状态数组，每项包含状态名与对应的 SVG URL
opts.state	String	否	初始状态；若不提供，默认取第一个状态

初始化行为

• 设置初始状态 this.curstate
• 调用 set_state(state) 加载对应 SVG
• 绑定 click 事件处理器 trigger

---

方法列表

trigger(event)

处理点击事件，顺序切换到下一个状态（循环）。

事件处理

• stopPropagation() 和 preventDefault() 阻止冒泡与默认行为

切换逻辑

• 查找当前状态索引 i
• 下一状态索引：k = i + 1，若已达末尾则回到 0
• 调用 set_state(states[k].state)
• 触发 state_changed 事件

---

set_state(state)

切换到指定状态。

参数

• state (String)：目标状态名称

行为

• 若已处于该状态，直接返回
• 遍历 this.states 查找匹配项
• 找到后调用 set_url(s.url)
• 广播 state_changed 事件
• 若未找到匹配项，清除 SVG 内容（set_url(null)）

---

3. bricks.MultipleStateIcon 类

简介

另一种多状态图标实现方式，使用对象字典管理 URL 映射，适合命名清晰的状态切换（如开关、模式选择等）。

构造函数：constructor(opts)

参数

参数	类型	必需	描述
opts.urls	Object<String, String>	是	状态名到 SVG URL 的映射表，例如 {on: 'on.svg', off: 'off.svg'}
opts.state	String	是	初始状态键名

初始化流程

• 从 urls[state] 提取初始 URL
• 调用 super(opts) 创建基础 SVG
• 记录 this.urls 和当前 this.state
• 绑定 click 事件到 change_state

---

方法列表

change_state(event)

点击时切换到下一个状态（按 Object.keys(urls) 顺序循环）。

流程

• 获取所有状态键名数组
• 查找当前 state 的索引
• 计算下一索引（越界则归零）
• 调用 set_state(newState)
• 触发 state_changed 事件

---

set_state(state)

设置当前状态并加载对应 SVG。

参数

• state (String)：目标状态键名

行为

• 更新 this.state
• 调用 set_url(this.urls[state])

---

工厂注册

以下三类组件均已向 bricks.Factory 注册，可在声明式模板中使用：

bricks.Factory.register('Svg', bricks.Svg);
bricks.Factory.register('StatedSvg', bricks.StatedSvg);
bricks.Factory.register('MultipleStateIcon', bricks.MultipleStateIcon);

这意味着可以通过如下方式创建实例（假设框架支持）：

<div data-widget="Svg" data-options='{"url": "icon.svg", "color": "blue"}'></div>

---

使用示例

示例 1：基础彩色 SVG

const icon = new bricks.Svg({
  url: '/icons/home.svg',
  color: 'green',
  blink: true,
  blinkcolor: 'yellow',
  blinktime: 0.8
});
document.body.appendChild(icon.dom_element);

示例 2：三态切换图标（StatedSvg）

const light = new bricks.StatedSvg({
  states: [
    { state: 'red',   url: '/svg/red.svg' },
    { state: 'yellow', url: '/svg/yellow.svg' },
    { state: 'green', url: '/svg/green.svg' }
  ],
  state: 'red'
});

light.on('state_changed', (state) => {
  console.log('Current state:', state);
});

示例 3：双态图标（MultipleStateIcon）

const toggle = new bricks.MultipleStateIcon({
  urls: {
    on: '/icons/power-on.svg',
    off: '/icons/power-off.svg'
  },
  state: 'off'
});

toggle.on('state_changed', s => console.log('Power is now:', s));

---

注意事项与最佳实践

项目	建议
安全性	不要加载不可信来源的 SVG，尤其是含 <script> 或内联事件的文件
性能	多次调用 set_color 会触发重绘，建议批量操作
闪烁控制	使用 start_blink() / end_blink() 显式控制动画生命周期
异步加载	set_url() 是异步操作，后续逻辑应放在监听器或 Promise 中处理
颜色同步	推荐使用 set_ancent_color() 实现主题适配

---

依赖说明

依赖项	来源	用途
bricks.VBox	基础布局容器	提供 DOM 容器能力
bricks.app.get_color()	应用配置模块	获取默认前景色
bricks.app.get_bgcolor()	应用配置模块	获取默认背景色
bricks.obj_fmtstr()	字符串工具	替换 {color} 模板
schedule_once(fn, sec)	异步调度工具	实现非阻塞定时任务

---

版本信息

• 编写日期：2025年4月5日
• 框架版本兼容性：BricksJS v1.x+
• 维护者：前端组件团队

---

✅ 文档完成
如有扩展需求，请参考现有接口进行子类化开发。