敖烈的存档点

Back

SVG.js 中文文档

用于操作和动画 SVG 的轻量级库。

介绍#

网上暂时没有3.2版本的文档，所以自己翻译了一份。水平有限，欢迎大家指正。

更新于 2024-12-20

前言

用于操作和动画 SVG 的轻量级库。

官网：SVG.js ↗

为什么选择 SVG.js？

SVG.js 没有任何依赖，旨在保持尽可能小的体积，同时尽可能全面地覆盖 SVG 规范。如果你还不确定，这里有一些亮点：

速度很快

SVG.js 很快。虽然不如 vanilla.js 快，但比竞争对手快很多倍：

条件:

  • rects: 创建 10000 个矩形
  • fill: 创建 10000 个矩形，并填充颜色
  • gradient: 创建 10000 并填充渐变色

相交其他产品用时快很多。测试环境： Intel Core i7-4702MQ @ 2.2GHz.

易于阅读，语法简洁。

仅使用 JavaScript 创建和操作 SVG 非常繁琐。例如，仅创建一个简单的粉色方块就需要相当多的代码：

SVG.js 提供了简洁易读的语法。操作与上面的 vanilla.js 示例相同：

// SVG.js
var draw = SVG().addTo('#drawing'),
    rect = draw.rect(100, 100).fill('#f06')
javascript

只需两行代码，而不是十行！而且不需要编写重复代码。

编写复杂的动画。

更多功能。

  • 尺寸、位置、变换、颜色等动画效果
  • 得益于模块化结构，轻松扩展
  • 提供各种实用的插件
  • 统一的 API，适用于不同形状类型（如移动、调整大小、居中等）
  • 元素绑定事件
  • 完整支持透明度蒙版和裁剪路径
  • 支持文本路径，甚至可以实现动画效果
  • 元素分组功能
  • 动态渐变和图案
  • 完整文档支持（你正在阅读的就是 :)）

License

SVG.js MIT许可条款授权：MIT License ↗

更新日志

获取最新版本中有哪些变化，请查看官方更新日志：change log ↗.

安装#

Npm

npm install svg.js
bash

Yarn

yarn add svg.js
bash

CDN.js / jsDelivr

从 cdnjs.com ↗ 或直接从 jsdelivr ↗ 获取最新版本。

下载

您可以在GitHub release Page ↗ 上找到所有版本。

最新版本可以在这里找到: svg.min.js ↗。

为了获得最佳的开发体验，请确保源映射文件与库文件位于同一文件夹中。

入门#

准备工作

创建一个基本的 HTML 标记并引入 svg.js 脚本

<!DOCTYPE html>
<html>
    <head>
      <title>SVG.js</title>
      <script src="https://cdn.jsdelivr.net/npm/@svgdotjs/svg.js@3.0/dist/svg.min.js"></script>
    </head>
    <body>

    </body>
</html>
html

或者直接在你的 JavaScript 应用中导入 svg.js

import { SVG } from '@svgdotjs/svg.js'
javascript
注意：以前在全局 SVG 对象上可用的所有属性现在都需要通过导入来使用。

创建一个 SVG 画布

接下来，使用 SVG() 函数创建一个 SVG画布 并将其添加到 HTML 页面中：

var draw = SVG().addTo('body').size(300, 300)
var rect = draw.rect(100, 100).attr({ fill: '#f06' })
javascript

你可以传递任意 CSS 选择器给 addTo，或者直接传递一个节点。

<body>
  <svg xmlns="http://www.w3.org/2000/svg" version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" width="300" height="300">
    <rect width="100" height="100" fill="#f06"></rect>
  </svg>
</body>
javascript

SVG.js 不会自动设置画布的大小。因此请确保使用适当的值调用 size()。

例如，要将大小设置为其父级的尺寸，请使用以下命令：

var draw = SVG().addTo('#someId').size('100%', '100%')
javascript

等待DOM加载

这对许多人来说可能显而易见，但仍值得一提。如果你在页面的 <head> 中引入了 JavaScript 文件，请确保等待 DOM 加载完成后再执行代码：

SVG.on(document, 'DOMContentLoaded', function() {
  var draw = SVG().addTo('body')
})
javascript

如果你将 JavaScript 文件引入在页面底部，这就不需要使用。

SVG文件中使用

SVG.js 也可以在 HTML DOM 之外运行，例如在一个独立的 SVG 文件中：

<?xml version="1.0" encoding="utf-8" ?>
<svg id="drawing" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" >
  <script type="text/javascript" xlink:href="svg.min.js"></script>
  <script type="text/javascript">
    <![CDATA[
      var draw = SVG('#drawing')
      draw.rect(100,100).animate().fill('#f03').move(100,100)
    ]]>
  </script>
</svg>
plaintext

SVG() 函数

SVG() 函数不仅可以创建新的SVG画布，还可以从 DOM 中获取 svg.js 对象，或者通过 SVG 片段创建新的对象：

// new document
var draw = SVG()

// get rect from dom
var rect = SVG('#myRectId')
// or
var rect = SVG('rect')
// any css selector will do
var path = SVG('#group1 path.myClass')

// create new object from fragment
var circle = SVG('<circle>')

// convert node to svg.js object
var obj = SVG(node)
javascript

练习

为了帮助你快速入门，这里提供了一个基础设置。所有内容都已准备好，供你开始尝试。

容器元素#

SVG.Container

SVG.Container 类是所有可以包含其他元素的容器元素的基础包装类。

继承结构为：SVG.Base > SVG.EventTarget > SVG.Dom > SVG.Element > SVG.Container。

SVG.Svg#

SVG.Svg 是 SVG.js 的主要初始化函数，它会在指定的元素中创建一个根 SVG 节点，并返回一个 SVG.Svg 的实例。

SVG()

返回的 SVG.Svg 继承自 SVG.Container。

var draw = SVG().addTo('#drawing')
javascript

注意： 第一次调用 SVG() 时，会创建一个第二个不可见的 <svg> 元素。这是我们的解析器，具体说明请参阅 常见问题解答 ↗

一个SVG画布也可以在另一个SVG画布内部创建。这种情况下，它被称为嵌套SVG：

nested()

SVG.Container上的构造函数 返回一个继承自SVG.Container的SVG.Svg对象

var nested = draw.nested()

var rect = nested.rect(200, 200)
javascript

svg.isRoot()

检测这个 <svg> 元素是否是根SVG元素。注意，如果该元素是文档片段（document-fragment）的直接子元素，这将返回 false。然而，如果该元素完全从DOM中分离出来，它将返回 true。

svg.namespace()

为SVG元素添加所需的SVG命名空间。在创建时会自动完成。如果你不需要这些命名空间，你可以使用 removeNamespaces() 方法来移除它们。

svg.removeNamespaces()

从 svg 元素中删除 svg 命名空间。

SVG.G#

当你想要将一组元素当作一个整体变换时，你可以使用分组来完成。组内的所以元素，都会保持相对于它们所属组的位置不变。

注意： 组本身是没有形状的，它的形状都是继承自组内的元素的形状。因此，SVG.G不会相应x、y、width 和 height属性。 如果你需要操作这些属性，请使用 嵌套nested() 方法代替。

group()

SVG.Container上的构造函数 返回一个继承自SVG.Container的SVG.G对象

组具有与根 SVG 画布相同的所有元素方法：

var group = draw.group()
group.path('M10,20L30,40')
javascript

画布上的现有元素也可以添加到组中：

var rect = draw.rect(100, 100)
group.add(rect)
javascript

SVG.Symbol#

SVG.Container上的构造函数 返回一个继承自SVG.Container的SVG.Symbol对象

和组group类似，符号symbol也是一个容器元素。符号和组的唯一区别在于符号本身不会被渲染显示。因此，符号元素非常适合与使用use元素一起使用：

var symbol = draw.symbol()
symbol.rect(100, 100).fill('#f09')

var use = draw.use(symbol).move(200, 200)
javascript

SVG.Defs#

<defs>是用来存放被引用元素的容器。<defs>的后代元素不会被直接渲染。<defs>存在于主<svg>画布中，可以通过defs()方法访问。

defs()

SVG.Container上的构造函数 返回一个继承自SVG.Container的SVG.Defs对象

var defs = draw.defs()
javascript

通过root()方法，<defs>也可以在任何其他元素上访问得到。

var defs = rect.root().defs()
javascript

defs的工作方式与组group完全相同。

SVG.A#

创建一个可以在所有子元素上激活的超链接。

link()

SVG.Container上的构造函数 返回一个继承自SVG.Container的SVG.A对象

超链接或<a>标签会创建一个容器，使所有子元素都可以进行链接跳转：

var link = draw.link('https://svgdotjs.github.io/')
var rect = link.rect(100, 100)
javascript

link.to()

可以使用to()方法更新链接 url：

link.to('https://svgdotjs.github.io/')
javascript

link.target()

link()可以通过target()方法来创建target属性：

link.target('_blank')
javascript

element.linkTo()

元素可以用linkTo()方法以相反的方式链接：

rect.linkTo('https://svgdotjs.github.io/')
javascript

或者可以传递一个function而不是URL，以在链接元素上获得更多的选项。

rect.linkTo(function(link) {
  link.to('https://svgdotjs.github.io/').target('_blank')
})
javascript

element.unlink()

移除元素的链接：

rect.unlink()
javascript

element.linker()

判断元素是否有链接元素。如果没有，则返回null。

rect.linker() // returns the link
javascript

SVG.Fragment#

svg片段Fragment是一个SVG内容片段document-fragment的包装器。虽然它不是容器Container类的一部分，但它仍然拥有所有构建元素的方法。 你可以轻松的将你需要的SVG元素编辑到一个片段内，并且一次性将它们全部添加到DOM中。

const frag = new Fragment()
frag.rect(100, 100)
frag.circle(100, 100)

draw.add(frag) // will add rect and circle
javascript

SVG.Fragment直接扩展了SVG.Dom，所以它支持dom的所有基本操作以及svg元素的导入和导出：

const frag = new Fragment()
frag.rect(100, 100)
frag.circle(100, 100)
frag.first() // rect
frag.last() // rect

frag.svg() // <rect ... /><circle ... />
javascript

其他元素#

SVG.js 元素的常规处理#