跳过主要内容

DrawSVG

快速入门

CDN 链接

gsap.registerPlugin(DrawSVGPlugin) 

最简用法

//draws all elements with the "draw-me" class applied 
gsap.from(".draw-me", {duration:1,drawSVG: 0});

描述

DrawSVGPlugin 允许你逐步显示(或隐藏) SVG 的描边。<path>, <line>, <polyline>, <polygon>, <rect>,或者<ellipse>你甚至可以从描边的中心(或任何位置/段)向外进行动画。它通过控制stroke-dashoffsetstroke-dasharrayCSS 属性影响描边。

可以将 drawSVG 值理解为描述整个 SVG 元素中被描边的部分(不一定要从起点开始)。例如,drawSVG:"20% 80%"表示仅在路径 20% 到 80% 的位置之间渲染描边,意味着两端各有一个 20% 的间隙。如果你从"50% 50%"开始并动画过渡到"0% 100%",则会从中间向外绘制描边,直到填满整个路径。

加载中...

记住,drawSVG值并不是描述你想在其中进行动画的范围——它描述的是你要动画到的最终状态(或者如果你使用的是from()补间动画,则是起始状态)。所以gsap.to("#path", {duration: 1, drawSVG: "20% 80%"})是将描边从当前状态动画过渡到沿路径描边存在于 20% 到 80% 之间的状态。它不会在补间过程中从 20% 动画过渡到 80%。

这是一个好处是因为它给你更大的灵活性。你并不局限于从路径上的一个单一的点开始并在一个方向上做动画。你可以控制整个线段(起始和结束位置)。所以你甚至可以沿着路径从一端到另一端做一个虚线动画,大小不变,就像gsap.fromTo("#path", {drawSVG: "0 5%"}, {duration: 1, drawSVG: "95% 100%"});

你可以使用百分比或绝对长度。如果你只使用一个值,0将默认作为起始值,所以"100%"等同于"0 100%""true".

重要提示:要想对描边进行动画处理,你首先必须使用 CSS 或 SVG 属性实际应用一个描边:

/* Define a stroke and stroke-width in CSS: */
.yourPath {
stroke-width: 10px;
stroke: red;
}

/* or as SVG attributes: */
<path ... stroke-width="10px" stroke="red" />
详细讲解

如何对多个描边进行动画并交错播放?

将 DrawSVGPlugin 集成到 GSAP 中的一大好处是,你可以利用丰富的 API 快速创建复杂的效果并完全控制(比如pause, resume, reverse, seek嵌套等)。假设你有 20 个带有类名draw-me的 SVG 元素,并希望以交错的方式绘制它们。你可以这样写:

//draws all elements with the "draw-me" class applied with staggered start times 0.1 seconds apart
gsap.from(".draw-me", {duration:1,stagger: 0.1, drawSVG: 0});

或者你可以创建一个时间轴并将这些补间动画放入其中,以便整体控制整个动画序列:

var tl = gsap.timeline();
tl.from(".draw-me", { duration: 2, drawSVG: 0 }, 0.1);

//now we can control it:
tl.pause();
tl.play();
tl.reverse();
tl.seek(0.5);...

添加"live"以在动画过程中重新计算长度

在极少数情况下,SVG 元素本身的长度可能在 drawSVG 动画过程中发生改变(比如窗口调整大小导致响应式变化)。在这种情况下,你只需简单地在值后面追加"live",这会让 DrawSVGPlugin 在每次动画 tick 时更新长度。例如,drawSVG: "20% 70% live".

拆分多段路径<path>

通常最好在<path>只包含单一段落(不包含多个 "M" 命令)的元素上使用 DrawSVGPlugin,因为浏览器很难正确地在一个多段路径上绘制连续的描边。但我们已经编写了一个辅助函数,它可以自动将一个多段路径<path>拆分为每个段落一个<path>,如这个演示所示:

加载中...

注意事项 / 说明

  • DrawSVGPlugin 完全不会对 SVG 的填充进行动画处理——它仅通过stroke-dashoffsetstroke-dasharrayCSS 属性影响描边。

  • 在某些罕见的情况下,Firefox 无法正确计算<path>元素的总长度,因此即使你动画到 100%,你可能会发现路径会提前结束一点。在这种(少见的)情况下,有两种解决方案:要么向你的路径添加更多锚点,使控制点更靠近路径;要么略微超过百分比,比如使用102%而不是100%。需要明确指出的是,这是 Firefox 的 bug,而非 DrawSVGPlugin 的问题。

  • 自 2014 年 12 月起,iOS Safari 存在一个 bug,会在某些情况下导致<rect>描边渲染错误(过粗、边缘轻微伪影,以及原点位置错误)。最佳解决方法是将你的<rect>转换为<path>或者<polyline>.

  • 你不能影响<use>元素的内容,因为浏览器根本不允许这样做。嗯,你可以对其进行补间动画,但你在屏幕上看不到任何变化。

方法

DrawSVGPlugin.getLength(element:[Element | Selector text]): Number

提供一种简便的方法获取 SVG 元素描边的长度,包括:<path>, <rect>, <circle>, <ellipse>, <line>, <polyline>,以及<polygon>

DrawSVGPlugin.getPosition(element:[Element | Selector text]): Number

提供一种简便的方法获取当前 DrawSVG 的位置。

示例演示

查看完整系列的使用演示和我们最喜欢的社区灵感演示在 CodePen 上。

无噪 Logo
无噪文档
中文文档 · 复刻官网
查看所有 ↗