yumoqing/bricks
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
bricks/aidocs/svg.md
yumoqing 55908f7b8f bugfix
2025-10-05 06:39:58 +08:00

9.3 KiB
Raw Blame History

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+
  • 维护者：前端组件团队

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