Snap.svg 版本演进全解析:从 0.1.0 到 0.5.1 的核心 API 变迁与源码实现
Snap.svg 版本演进全解析:从 0.1.0 到 0.5.1 的核心 API 变迁与源码实现
本文以 Snap.svg 官方版本变更日志 history.md 为骨架,逐版本梳理 0.1.0 → 0.5.1 期间新增的类、方法与能力(对齐、渐变、调色板、数学函数、
<symbol>支持、viewBox动画等),并结合当前仓库src/目录下的真实源码(colors.js、align.js、paper.js、path.js、svg.js 等)与 test/ 测试用例,还原每个特性背后的实现原理与用法。读完本文,你将理解 Snap.svg 现代 SVG 编程模型如何一步步成型,并能在实际项目中直接使用这些版本化 API。
一、历史脉络与版本总览
Snap.svg 是 Adobe 出品的现代 Web SVG 绘图库,旨在取代旧版 Raphael 的 IE 兼容包袱,直接面向现代浏览器。当前仓库的 history.md 记录了从 0.1.0 初始发布到 0.5.1 的完整版本轨迹:
| 版本 | 定位 | 关键主题 |
|---|---|---|
| 0.1.0 | 初始发布 | 库的根基:Element / Paper / Set / 动画 |
| 0.2.0 | 结构完善 | 文本路径、getBBox、appendTo/prependTo、命中检测 |
| 0.3.0 | 能力扩充 | CSS 类操作、Paper.mask/ptrn/use/svg、Set.bind、属性增量语法 |
| 0.4.0 | 数学与结构 | 对齐 API、viewBox 动画、<symbol>、toDataURL、角度制三角函数、Snap.closest |
| 0.5.0 | 视觉增强 | Material / FlatUI 调色板、渐变 stop 系列方法、矩阵拆分动画优化 |
| 0.5.1 | 稳定性 | Bug fix |
从代码结构看,仓库 src/ 目录的组织方式也印证了这一演进:核心模块(element.js、paper.js、set.js、animation.js)是基础,而后期的对齐与颜色功能被拆分进独立插件文件 align.js 与 colors.js —— 这正是 0.4.0「Moved class and element related code into separate plugins」所描述的插件化架构。
二、0.1.0:初始发布的功能根基
0.1.0 是 Snap.svg 的第一个公开版本,确立了库的三大核心抽象:
Snap():入口工厂,包装 SVG 根节点并返回 Paper 对象;Paper:对应<svg>画布,提供circle()、rect()、path()、gradient()等元素创建方法;Element/Set:对应单个 SVG 元素与元素集合,提供attr()、animate()、transform()等操作。
这些基础能力至今仍是源码中的主干,例如 element.js 中的 elproto.getBBox(getBBox(isWithoutTransform))已实现基于 Snap.path.getBBox 与矩阵映射的包围盒计算,而非简单调用原生 API。测试目录 test/element.js、test/paper.js 从初始版本起就持续覆盖这些行为。
三、0.2.0:文本路径、命中检测与 DOM 语义对齐
0.2.0 是一次重要的结构完善版本,主要变化集中在:
3.1 文本路径支持
新增对 textPath 的支持,允许文字沿任意路径排布,这在 infographic 类可视化(可参考 demos/illustrated-infographic-coffee/index.html 的演示风格)中非常实用。
3.2 Paper 级 getBBox
Paper 对象(即 <svg> 根)也拥有了 getBBox() 方法,源码位于 element.js,同时服务于对齐 API 等后续特性。
3.3 Element.appendTo() / Element.prependTo()
这两个方法用于把元素挂载到另一元素下(追加 / 前置),源码在 element.js 附近实现,返回被移动的子元素,便于链式调用。
3.4 getElementByPoint()
Paper 新增命中检测能力,返回指定坐标处的元素,源码实现于 paper.js,是后续 Snap.closest() 等功能的基础。
3.5 底层架构决策:弃用内部 SVG 解析器
「Get rid of internal SVG parser in favor of the browser」 是一个关键架构转向——Snap.svg 不再自带一套 SVG 字符串解析器,而是让浏览器原生解析 SVG,Snap.svg 只负责包装 DOM 节点并增强 API。这让库更轻量、行为更贴近标准。从源码看,Snap() 对字符串的解析依赖浏览器 DOM 能力(如 new DOMParser 或 createElementNS 包装逻辑),印证了该决策。
3.6 修复项
本版本还修复了 xlink:href 设置(图片引用)、Element.animate()、动画与 stroke-dashoffset 的配合、绝对变换、SVG 变换/矩阵/多边形点坐标的动画等问题。测试 test/attrs.js 与 [test/animation.js](对应 test/ 目录)覆盖了这些回归场景。
四、0.3.0:CSS 类、Mask/Pattern 与属性增量语法
0.3.0 把「操作 SVG 元素」提升到接近 DOM 操作的体验:
4.1 CSS 类操作 API
新增 addClass()、removeClass()、toggleClass()、hasClass(),实现位于 class.js(0.4.0 之后 class 相关代码被拆分为独立插件模块),对应测试 test/class.js。
4.2 Paper 级工厂方法:mask()、ptrn()、use()、svg()
Paper.mask():创建<mask>遮罩元素;Paper.ptrn():创建<pattern>图案元素;Paper.use():创建<use>引用元素(配合后续 0.4.0 的<symbol>支持);Paper.svg():创建内嵌<svg>子画布。
关键改进:mask 与 pattern 元素像 group 一样共享 Paper 方法,即它们返回的对象同样具备创建子元素的能力,源码可在 element.js 的 elproto.mask、elproto.ptrn 及相关工厂函数中找到(pattern 工厂会写入 viewBox 与 patternUnits: "userSpaceOnUse" 等属性)。
4.3 Set.bind() 与 Set.animate() 同步
Set.bind():把一个 Set 绑定到另一对象上,使 Set 的属性变化同步作用于绑定目标;Set.animate():集合动画增加同步机制,同一 Set 内所有元素同时开始动画。
实现于 set.js,对应测试 test/set.js。
4.4 Shadow 滤镜透明度
shadow 滤镜支持 opacity,相关实现可查 filter.js。
4.5 属性增量语法:"+=10" / "-=1em" / "*=2"
这是一个非常实用的语法糖:attr() 与动画的 to 值支持相对增量写法。解析逻辑位于 attradd.js(Attribute Addition 插件),对应测试 test/attradd.js。例如:
// 让矩形宽度在当前基础上增加 10
rect.attr({ width: "+=10" });
// 动画到当前宽度 ×2
rect.animate({ width: "*=2" }, 500);
4.6 修复项
修复负 scale、path2curve 转换、共享 <defs> 导致的问题等。path2curve 相关逻辑位于 path.js,是该库路径数学的核心之一。
五、0.4.0:对齐、符号、导出与角度制数学
0.4.0 是功能密度最高的版本之一,涵盖布局、结构、导出、数学四个维度:
5.1 插件化架构调整
「Moved class and element related code into separate plugins」——class 与 element 相关代码被拆分为独立插件。当前仓库 class.js、align.js、colors.js 等文件均以 Snap.plugin(function (Snap, Element, Paper, glob) {...}) 形式注册,正是这一演进的直接结果。
5.2 Element.align() 与 Element.getAlign()(对齐 API)
这两个方法的实现位于 align.js:
Element.getAlign(el, way):返回把当前元素对齐到目标元素el所需的位移量,返回{dx, dy}对象,且该对象带toString(),可直接拼进变换字符串;Element.align(el, way):直接通过this.transform("..." + this.getAlign(el, way))完成对齐(...表示在当前变换之后叠加)。
way 支持六个值:"top"、"middle"、"bottom"、"left"、"center"、"right";若省略目标元素,则默认对齐父级 <svg> 容器。代码通过正则 firstLetter = /^[^a-z]*([tbmlrc])/i 提取首字母来匹配方向。用法:
el.align(el2, "top"); // 对齐到 el2 顶部
el.align("middle"); // 在父 svg 中水平居中(dy 对齐中线)
var dy = el.getAlign(el2, "top").dy; // 仅取位移量
5.3 viewBox 动画支持
viewBox 属性可以参与动画。attr.js 中注册了 snap.util.attr.viewBox 事件处理器,支持对象({x, y, width, height})、数组与字符串三种赋值形式,并将其拼接为 "x y width height" 字符串写入节点;equal.js 中则实现了 viewBox 的差值比较逻辑(from/to 数组逐项数值插值),使 animate({ viewBox: ... }) 可以平滑过渡。例如实现镜头缩放效果:
svg.animate({ viewBox: "0 0 400 300" }, 1000, mina.easeinout);
5.4 <symbol> 支持
配合 0.3.0 的 Paper.use(),本版本为 <symbol> 元素提供一等支持,可创建可复用的图标/图形符号,再通过 <use> 在画布中多处实例化,是图标系统的基础设施。
5.5 Paper.toDataURL()
实现于 element.js(elproto.toDataURL):通过 getBBox() 计算内容范围,用 Snap.format 拼出带 viewBox 与 width/height 的 SVG 字符串,再经 window.btoa 编码为 data URL,从而把 SVG 内容导出为可下载/可分享的图像数据:
var dataUrl = paper.toDataURL();
// 可用于 <img src="..."> 或下载
5.6 数学工具函数
新增两组数学 API,均实现在 svg.js:
角度制三角/反三角(直接对标 Math.*,但输入/输出均为角度而非弧度):
| 函数 | 语义 | 源码实现 |
|---|---|---|
Snap.sin(angle) |
角度制 sin | math.sin(Snap.rad(angle)) |
Snap.cos(angle) |
角度制 cos | math.cos(Snap.rad(angle)) |
Snap.tan(angle) |
角度制 tan | math.tan(Snap.rad(angle)) |
Snap.asin(num) |
返回角度制 asin | Snap.deg(math.asin(num)) |
Snap.acos(num) |
返回角度制 acos | Snap.deg(math.acos(num)) |
Snap.atan(num) |
返回角度制 atan | Snap.deg(math.atan(num)) |
Snap.atan2(x, y) |
返回角度制 atan2 | Snap.deg(math.atan2(x, y)) |
几何测量:
Snap.len(x1, y1, x2, y2):两点间距离;Snap.len2(x1, y1, x2, y2):两点距离的平方(避免开方,性能敏感场景用);Snap.closestPoint(path, x, y):路径上离指定点最近的点。
5.7 Snap.closest()
实现在 path.js:给定点 (x, y) 与一组候选对象,先在 100×100 的局部窗口内做粗筛(bbox 命中检测),再用 Snap.len 精确计算距离并取最近者。候选对象的坐标既可来自 .x/.y 属性,也可来自 .attr("cx"/"cy") 等 getter 函数,兼容性强。
5.8 Element.children() 与 Element.toJSON()
children():返回元素的直接子元素列表;toJSON():把元素序列化为可复用的 JSON 描述(结构、属性),为状态保存/传输提供基础。
六、0.5.0:调色板与渐变 stop 工程化
0.5.0 聚焦视觉工作流,新增两个高频使用的特性:
6.1 Material 与 FlatUI 调色板
实现于 colors.js,通过 Snap.plugin 注册:
Snap.mui:Material UI 配色,含 red/pink/purple/deeppurple/indigo/blue/lightblue/cyan/teal/green/lightgreen/lime/yellow/amber/orange/deeporange/brown/grey/bluegrey 等 19 个色系。每个色系通过saveColor()解析为带编号属性(50/100/…/900,含强调色的色系另有A100/A200/A400/A700)的颜色对象;Snap.flat:Flat UI 配色,如turquoise、carrot、wetasphalt、midnightblue等 20 个语义命名的单一色值;Snap.importMUIColors():把Snap.mui下所有色系注入全局命名空间,便于直接以amber[600]这种裸标识符书写。
官方注释给出的用法示例(见 colors.js 内 doc 注释):
// 使用 Material UI 色
Snap().rect(0, 0, 10, 10).attr({ fill: Snap.mui.deeppurple, stroke: Snap.mui.amber[600] });
// 使用 Flat UI 色
Snap().rect(0, 0, 10, 10).attr({ fill: Snap.flat.carrot, stroke: Snap.flat.wetasphalt });
// 导入全局后可直接引用
Snap.importMUIColors();
Snap().rect(0, 0, 10, 10).attr({ fill: deeppurple, stroke: amber[600] });
6.2 渐变 stop 系列方法:stops() / addStop() / setStops()
实现在 paper.js 的渐变辅助函数区(Gstops/GaddStop/GsetStops),并挂载到 linearGradient/radialGradient 元素上:
Element.stops():返回渐变内全部<stop>元素(this.selectAll("stop"));Element.addStop(color, offset):新增一个 stop,offset取值 0~100;实现会按offset数值在正确位置插入(insertBefore)而非简单追加,保证 stop 顺序合法;透明度< 1的颜色会自动写入stop-opacity;Element.setStops(str):基于渐变描述符批量更新 stops,描述符形如"#fff-#000-#f00-#fc0",可包含:25这样的自定义偏移;内部通过snap.util.grad.parse事件解析,再复用attr更新与addStop增补逻辑,实现「多退少补」的同步效果。
配合 paper.js 中 Paper.gradient() 的完整渐变描述符语法(<type>(<coords>)<colors>,大写 L/R 表示绝对坐标、小写 l/r 表示相对坐标,颜色可用 - 分隔并可带 :offset):
var g = paper.gradient("l(0, 0, 1, 1)#000-#f00-#fff"); // 相对线性渐变
var g2 = paper.gradient("L(0, 0, 100, 100)#000-#f00:25-#fff"); // 绝对线性渐变 + 25% 偏移
var g3 = paper.gradient("r(0.5, 0.5, 0.5)#000-#fff"); // 相对径向渐变
g.addStop("#00f", 75); // 追加蓝色 stop 到 75% 处
g.setStops("#fff-#000-#f00-#fc0"); // 批量重设 stops
paper.circle(50, 50, 40).attr({ fill: g });
6.3 矩阵动画优化
「Fixed matrix splitting for better animation of matrices」:矩阵动画的拆分逻辑被修复,使变换矩阵的插值更平滑。矩阵相关实现位于 matrix.js,动画插值框架在 mina.js(该库自带的缓动/补间引擎,mina.easein、mina.easeout 等缓动函数即由此提供)。
6.4 工程化:测试与 ESLint 集成
「Better integration of tests and ESlint」:测试与静态检查流程得到改进。当前仓库的 test/ 目录包含 attrs、class、colors、element、filter、gradients、matrix、mina、paper、path、primitives、set、system 等多套测试(test/snap-tests.js、test/test.html),配合根目录 Gruntfile.js 中的 lint/test 任务;package.json 亦声明了 lint 与测试脚本。
七、0.5.1 与版本使用建议
0.5.1 仅包含 Bug fix,是当前仓库所记录的最新稳定版本。结合 README.md 的安装方式,你可以这样使用:
# Bower 安装
bower install snap.svg
# npm 安装
npm install snapsvg
<!-- 直接引入(dist 目录下同时提供压缩与未压缩版本) -->
<script src="snap.svg-min.js"></script>
// webpack 2.x/3.x 下通过 imports-loader 引入(详见 README.md 的配置示例)
import Snap from 'snapsvg';
实际使用建议:
- 布局与对齐:优先使用 0.4.0 的
Element.align()/getAlign()而非手写坐标计算,可显著减少响应式布局中的样板代码; - 视觉配色:需要 Material 或 Flat 风格时直接使用
Snap.mui/Snap.flat,配合importMUIColors()可进一步简化书写; - 动态渐变:用
gradient()描述符创建、addStop()/setStops()增量维护,比手工创建<stop>节点更安全(自动保证 offset 顺序); - 导出与复用:
Paper.toDataURL()用于导出图像,<symbol>+use()用于图标复用; - 相对属性动画:
"+="/"-="/"*="语法让动画目标值不必预先计算,配合viewBox动画可实现镜头推拉效果。
八、结语:版本史即架构史
纵观 history.md 的版本轨迹,Snap.svg 的演进脉络清晰可见:
- 0.1.0 → 0.2.0:从「能画」走向「结构化」——文本路径、命中检测、DOM 语义对齐(弃用内部解析器);
- 0.2.0 → 0.3.0:从「结构化」走向「工程化」——CSS 类、Mask/Pattern 工厂、集合绑定与同步、属性增量语法;
- 0.3.0 → 0.4.0:从「工程化」走向「平台化」——插件架构拆分、布局对齐 API、
<symbol>、数据导出、角度制数学全家桶; - 0.4.0 → 0.5.x:从「平台化」走向「视觉化」——设计系统调色板、渐变 stop 工程化、矩阵动画质量提升。
每一行 changelog 背后都能在当前仓库的 src/ 与 test/ 中找到对应实现与回归用例。对于希望在项目中按能力选型或深入理解 SVG 库内部设计的开发者,这份版本史既是一张「API 能力地图」,也是一份可对照源码研读的实现索引。