FlowingDev

在 React 中使用 SVG：从静态图片到动态组件

学习如何将静态 SVG 图片转换为动态、可复用的 React 组件（JSX/TSX），使其能够接受 props、改变颜色等等。

试用工具: SVG 转 JSX

一言以蔽之

SVG 转 JSX 能把你的矢量图代码变成一个可复用的 React 组件，让它变得动态、能用 props 控制，而不再只是个静态文件。

它解决了什么问题

在遥远的 Web 洪荒时代（也就五年前吧），如果你想显示一个 SVG 图标，你八成会直接把它扔进一个 <img> 标签里：<img src="/icons/user.svg" alt="User profile" />。搞定。上线。

但这种简单粗暴的方法其实是个坑。你的 SVG 现在成了一个黑盒。想在用户鼠标悬停在按钮上时改变图标颜色？门儿都没有。浏览器把它当成普通图片文件（比如 JPG、PNG），你没法用 CSS 轻松地修改它的内部样式。想给图标里的某条路径加个动画？别想了。想给暗黑模式换个颜色？那你得新建一个文件（user-white.svg），然后写逻辑去切换 src 属性。这事儿很快就会变得一团糟。

“啊哈！”聪明的开发者会说，“SVG 不就是 XML 标记嘛！我直接把 .svg 文件里的代码复制粘贴到我组件的 return 语句里不就行了！”

// MyComponent.js
const MyComponent = () => (
  <div>
    <p>My Profile</p>
    {/* 我刚从一个 .svg 文件里粘贴过来的！ */}
    <svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
      <path d="M12 12C14.21 12 16 10.21 16 8C16 5.79 14.21 4 12 4C9.79 4 8 5.79 8 8C8 10.21 9.79 12 12 12ZM12 14C9.33 14 4 15.34 4 18V20H20V18C20 15.34 14.67 14 12 14Z" fill="black"/>
    </svg>
  </div>
);

这招叫“内联（inlining）”，确实是前进了一大步。现在 SVG 成了 DOM 的一部分，你可以用 CSS 来给它上样式了。但你这是拆了东墙补西墙。

  1. 代码臃肿： 那一大坨 SVG 代码让你组件的可读性直线下降。想象一下，要是在一个组件里放五个这样的图标。
  2. 无法复用： 其他地方也需要这个用户图标？准备好再把那一大坨代码原封不动地复制粘贴一遍吧。
  3. 不是 JSX： React 有自己的一套 HTML “方言”。像 stroke-width 这样的属性需要转成驼峰命名（camelCase）的 strokeWidth，class 要变成 className。忘了转换这些，要么就静默失败，要么就在控制台给你报一堆警告。

真正的解决方案，是把图标当成组件生态系统里的一等公民，而不是静态资源。你想要的是 <UserIcon color="blue" size={24} /> 这样的组件。这正是 SVG 转 JSX 要解决的问题：它把“将原始 SVG 标记转换成一个整洁、可复用、由 prop 驱动的 React 组件”这个过程中的所有模板代码都自动化了。

底层原理揭秘

把一坨文本变成一个漂亮的 React 组件可能看起来像变魔术，但其实这是一个有迹可循、按部就班的过程。咱们来揭开这层幕布看看。

第一步：解析 SVG 标记

首先，工具必须能“看懂”SVG。因为 SVG 是 XML 的一种方言，所以它可以像 HTML 文档一样，被解析成一个节点树状结构。每个元素（<svg>、<path>、<g> 等）都成为一个节点，而它的属性（width、fill、d 等）则成为该节点的属性。

所以，这段代码：

<svg width="24" height="24">
  <path fill-rule="evenodd" d="..." />
</svg>

在解析器眼里是这样一棵树：

  • svg 节点，拥有 width="24" 和 height="24" 属性
    • path 节点，拥有 fill-rule="evenodd" 和 d="..." 属性

第二步：属性 JSX 化

这一步就是特定于 React 的转换了。解析器会遍历节点树，把属性转换成 JSX 兼容的格式。

  • 驼峰命名（Camel-casing）： 任何带连字符（kebab-case）的属性都会被转换为驼峰命名（camelCase）。fill-rule 变成 fillRule，stroke-width 变成 strokeWidth。
  • 关键字映射： JavaScript 的保留关键字会被替换掉。最常见的就是 class，它会变成 className。
  • Style 属性： 像 style="fill:red; stroke:blue" 这样的属性会被转换成一个 JavaScript 对象：style={{ fill: 'red', stroke: 'blue' }}。

所以，<path fill-rule="evenodd" class="icon-path"> 就会转成等价的 JSX：<path fillRule="evenodd" className="icon-path">。

第三步：用组件包装

现在 SVG 树已经能说一口流利的 JSX 了，下一步就是把它包装进一个标准的 React 函数式组件结构里。最简单的版本长这样：

import React from 'react';

const MyIcon = () => {
  return (
    <svg width="24" height="24" viewBox="0 0 24 24">
      {/* ... 所有 JSX 化之后的 path 和其他元素 ... */}
    </svg>
  );
};

export default MyIcon;

这已经给了你一个可复用的 <MyIcon /> 组件，算是一大进步了。但真正的威力在于让它动起来。

第四步：添加 Props 和 currentColor

这才是精髓所在。一个好的转换器不会只硬编码 SVG 的原始属性，而是让它们变得可配置。

  • 展开 Props： 组件会被修改，使其能够接受 props 并将它们展开到根 <svg> 元素上。这通常用 ...rest 语法实现。现在你可以把任何标准的 SVG 属性（比如 width、height、className 或 aria-label）直接传给你的组件了。

  • currentColor 的妙用： 这绝对是改变游戏规则的神器。转换器会找到那些定义了图标颜色的硬编码 fill 和 stroke 属性（例如 fill="#000000"），然后用 currentColor 这个特殊的 CSS 关键字取而代之。

currentColor 会告诉浏览器：“这个元素的 CSS color 属性是啥颜色，这里的 fill/stroke 就用啥颜色。”这意味着你的图标现在和文本的表现一样了。如果你把图标包在一个 div 里，然后设置 color: blue，图标就会变成蓝色。

// 升级版组件
const MyIcon = ({ color = 'currentColor', size = 24, ...rest }) => {
  return (
    <svg 
      width={size} 
      height={size} 
      fill={color} // 或者直接应用在 path 上
      {...rest}
    >
      <path d="..." fill="currentColor" />
    </svg>
  );
};

第五步：转发 Ref

有时候，你需要从父组件直接获取到真实的 <svg> DOM 元素的句柄（handle），可能要测量它的位置，或者配合第三方库使用。普通的函数式组件会隐藏其内部的 DOM 结构。解决方案就是 React.forwardRef。

一个成熟的转换器会用 React.forwardRef 把组件包起来，它能建立一个通道，把父组件传来的 ref 直接透传给底层的 <svg> 标签。

最终，一个生产级别的组件通常长这样（以 TypeScript 为例）：

import * as React from 'react';

type Props = React.SVGProps<SVGSVGElement>;

const MyIcon = React.forwardRef<SVGSVGElement, Props>((props, ref) => (
  <svg ref={ref} xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" {...props}>
    <path d="..." fill="currentColor" />
  </svg>
));

MyIcon.displayName = 'MyIcon'; // 方便调试
export default MyIcon;

真实世界里的故事

主题噩梦

一个前端团队正在开发一个漂亮的 Web 应用，同时支持亮色和暗色两种模式。他们用了大概 50 个图标，全都是用 <img src="/icons/whatever.svg"> 实现的。这些图标都是黑色的。当他们上线暗色模式时，团队瞬间慌了：所有 50 个黑色图标都在新的深色背景下“消失”了。他们手忙脚乱的第一个“修复”方案是导出了第二套白色图标（whatever-dark.svg），然后在所有地方都写了一堆恶心的条件逻辑（isDarkMode ? 'whatever-dark.svg' : 'whatever.svg'）。这简直是一场维护灾难。

后来，一位开发者引入了 SVG-to-JSX 的工作流。他们跑了一个脚本，把所有 50 个 SVG 都转成了 React 组件，关键一步是把所有的 fill="black" 属性都换成了 fill="currentColor"。他们把所有的 <img> 标签都换成了新的图标组件，比如 <WhateverIcon />。瞬间，这些图标就继承了父元素的文本颜色，而文本颜色已经由主题的 CSS 处理好了。亮色模式：黑色文本，黑色图标。暗色模式：白色文本，白色图标。一切就这么自然地解决了。

**经验：**将 SVG 内联为组件，可以让它们无缝地融入应用现有的设计系统和样式，把你从资源管理的地域里拯救出来。

会动的对号

一位产品经理想要一个“令人愉悦”的动画：当用户完成表单时，一个对号应该在屏幕上动态地画出来。用 GIF 动图不行——看起来有锯齿，而且文件还死大。开发人员试着找了个库，但没有一个能完全适配他们定制的对号设计。

于是她决定自己动手，从设计师那里拿来静态的对号 SVG，然后把它转成了一个 JSX 组件。这样一来，她就可以在 React 代码里直接访问到对号的 <path> 元素了。通过给那个 path 的 stroke-dasharray 和 stroke-dashoffset 属性加上简单的 CSS transition，她就实现了想要的“描边”效果。动画丝般顺滑，可以无限缩放，而且只占用了不到 1KB 的代码。

**经验：**把 SVG 转换成组件，能解锁对其内部各个部分的精细控制，从而让复杂的 CSS 或 JavaScript 驱动的动画成为可能。

常见错误和陷阱

  • 忘记无障碍（Accessibility）。 一个传达了意义的图标（比如一个表示“关闭”的 X）不仅仅是装饰。如果在转换时把 <title> 标签去掉了，屏幕阅读器可能会把它读成“组”，或者直接忽略它。务必确保你最终的组件有一个合适的 aria-label prop，或者在 SVG 内部通过 <title> 元素提供一个无障碍名称。一个好的组件会渲染成 <svg role="img" ...>。
  • 搞大打包体积（Bundle Size）。 内联 SVG 意味着它们的代码现在是你 JavaScript 包的一部分。对于几十个小的 UI 图标来说，这是利大于弊的（减少了 HTTP 请求）。但如果你想内联一个包含成千上万条路径的巨型复杂插图，你可能会严重撑大你的包体积，拖慢初始页面加载速度。对于大型、静态的插图，<img> 仍然是一个完全合理的选择。
  • 忽略了先优化这一步。 从 Figma 或 Adobe Illustrator 这类设计工具导出的 SVG 是出了名的乱。它们包含编辑器元数据、注释、隐藏图层，以及精度过高的十进制数值。直接把这些塞进 JSX 组件，会导致代码臃肿、难以阅读。在转换之前，一定要先用 SVGO 这样的优化器处理一下你的 SVG。这通常能减少 50% 甚至更多的代码量。
  • 手动编辑导致同步问题。 你把 icon.svg 转成了 Icon.jsx。然后你手动修改了 Icon.jsx 来加个功能。一周后，设计师给了你一个更新版的 icon.svg。现在你面临一个选择：重新运行转换，丢失你的手动修改；或者尝试手动把你编辑过的 JSX 和新设计合并。唯一的“信源”应该是 .svg 文件；转换到 JSX 的过程应该是一个可重复的、自动化的脚本。

为什么你应该关注它

只要你在构建一个基于组件的 Web 应用（比如 React、Preact 等），并且你的图标不只是想当个静态图片，你就应该考虑把 SVG 转换成 JSX。

在以下情况中，它就是正确的工具：

  • 你需要图标根据 state 或 props 改变颜色、大小或描边宽度。
  • 你正在构建一个设计系统或组件库，需要一个可扩展、一致的方式来管理图标。
  • 你想给图标的某个部分加上动画。
  • 你正在优化性能，希望通过内联关键图标来减少网络请求的数量。

在现代前端开发中，把图标当作组件来用不是什么黑科技——而是构建动态、可维护、高性能用户界面的标准做法。

深入了解

理论搞定，动手试试吧——100% 在你的浏览器中运行。

试用工具: SVG 转 JSX