SVG

SVG 是一种基于 XML 的矢量 2D 图形格式，支持交互性和动画。Parcel 支持将 SVG 作为单独的文件、嵌入 HTML 中或在 JavaScript 文件中作为 JSX 导入。

¥SVG is a vector-based 2D graphics format based on XML, with support for interactivity and animation. Parcel includes support for SVG as a separate file, embedded in HTML, or imported as JSX in a JavaScript file.

依赖

¥Dependencies

Parcel 会检测 SVG 中对其他文件（例如 <script>、<image> 和 <use>）的大多数引用并对其进行处理。这些引用被重写，以便它们链接到正确的输出文件。

¥Parcel detects most references in SVG to other files (such as <script>, <image>, and <use>) and processes them as well. These references are rewritten so that they link to the correct output files.

文件名相对于当前 SVG 文件进行解析，但你也可以使用 absolute 和 tilde 说明符。详情请参见 依赖解析。

¥File names are resolved relative to the current SVG file, but you can also use absolute and tilde specifiers. See Dependency resolution for details.

样式表

¥Stylesheets

可以通过 SVG 文档中的 xml-stylesheet 处理指令引用外部样式表。你可以引用 CSS 文件或编译为 CSS 的任何其他文件，例如 SASS、Less 或 Stylus。

¥External stylesheets can be referenced via the xml-stylesheet processing instruction in an SVG document. You can reference a CSS file, or any other file that compiles to CSS such as SASS, Less, or Stylus.

<?xml-stylesheet href="style.css" ?>
<svg viewBox="0 0 240 20" xmlns="http://www.w3.org/2000/svg">
  <text>Red text</text>
</svg>

text {
  fill: red;
}

有关 Parcel 如何处理 CSS 的详细信息，请参阅 CSS 文档。

¥See the CSS docs for details on how CSS is processed by Parcel.

脚本

¥Scripts

<script> 元素可用于引用 SVG 中的脚本文件。你可以引用 JavaScript 文件，或编译为 JavaScript 的任何其他文件，例如 TypeScript、JSX 或 CoffeeScript。

¥The <script> element can be used to reference a script file from SVG. You can reference a JavaScript file, or any other file that compiles to JavaScript such as TypeScript, JSX, or CoffeeScript.

type="module" 属性应用于指示文件是 ES 模块 或 CommonJS 文件。如果省略，则引用的文件将被视为经典脚本。有关此内容的更多信息，请参阅 经典脚本。SVG 中尚不支持 ES 模块，因此即使作为模块编写，Parcel 也会将所有 JavaScript 编译为经典脚本。

¥The type="module" attribute should be used to indicate that a file is an ES module or CommonJS file. If it is omitted, then the referenced file is treated as a classic script. See Classic scripts for more information about this. ES modules are not yet supported natively in SVG, so Parcel compiles all JavaScript to classic scripts even if authored as a module.

<svg viewBox="0 0 240 80" xmlns="http://www.w3.org/2000/svg">
  <circle cx="50" cy="50" r="50" fill="red" />
  <script type="module" href="interactions.js" />
</svg>

let circle = document.querySelector('circle');
circle.addEventListener('click', () => {
  circle.setAttribute('fill', 'blue');
});

有关详细信息，请参阅 MDN 文档 中的 <script> 元素；有关 Parcel 如何处理 JavaScript 的详细信息，请参阅 JavaScript 文档。

¥See the MDN docs for the <script> element for more info, and the JavaScript docs for details on how Parcel processes JavaScript.

图片

¥Images

可以使用 <image> 元素将光栅图片或其他 SVG 嵌入到 SVG 文件中。Parcel 可识别 href 和 xlink:href 属性。

¥Raster images or other SVGs can be embedded in an SVG file using the <image> element. Parcel recognizes the href and xlink:href attributes.

<image href="image.jpg" width="100" height="50" />

Parcel 的图片转换器还可用于通过使用 查询参数 来调整图片大小和转换图片。

¥Parcel’s image transformer can also be used to resize and convert images by using Query parameters.

<image href="image.jpg?as=webp" width="100" height="50" />

有关 Parcel 如何处理图片的详细信息，请参阅 图片 文档。

¥See the Image docs for details on how Parcel processes images.

链接

¥Links

SVG 文件可以使用 <a> 元素链接到其他网页或文件。Parcel 支持 href 和 xlink:href 属性。

¥SVG files can link to other web pages or files using the <a> element. Parcel supports the href and xlink:href attributes.

<a href="circle.html">
  <circle cx="50" cy="40" r="35" />
</a>

默认情况下，从 SVG 文件引用的其他资源将在其编译文件名中包含 内容哈希，但 <a> 元素引用的文件则不会。这是因为这些 URL 通常是人类可读的，并且随着时间的推移需要有一个稳定的名称。打包包命名可以被 命名插件 覆盖。

¥While other assets referenced from an SVG file will include a content hash in their compiled filename by default, files referenced by an <a> element will not. That's because these URLs are typically human readable, and need to have a stable name over time. Bundle naming can be overridden by Namer plugins.

外部参考

¥External references

Parcel 通过许多其他元素上的 href 和 xlink:href 属性支持外部引用。有关详细信息，请参阅 MDN 文档。

¥Parcel supports external references via the href and xlink:href attributes on many other elements. See the MDN docs for more details.

<use href="fox.svg#path" stroke="red" />
<text>
  <textPath href="fox.svg#path">
    Quick brown fox jumps over the lazy dog.
  </textPath>
</text>

还支持通过表示属性中的 url() 函数引用的外部资源，例如 fill、stroke、clip-path 等。

¥External resources referenced via the url() function in presentation attributes such as fill, stroke, clip-path, and many others are also supported.

<circle
  cx="50" cy="40" r="35"
  fill="url(external.svg#gradient)" />

内联脚本和样式

¥Inline scripts and styles

带有文本内容的 <script> 和 <style> 标签也像独立文件一样进行处理，并将生成的包插入回 SVG 文件中。如上所述使用 type="module" 属性可以从内联脚本导入其他模块。

¥<script> and <style> tags with text content are also processed just like standalone files, and the generated bundles are inserted back into the SVG file. Use the type="module" attribute as described above to enable importing other modules from an inline script.

<svg viewBox="0 0 240 80" xmlns="http://www.w3.org/2000/svg">
  <circle cx="50" cy="50" r="50" />
  <style>
    @import './style.scss';
  </style>
  <script type="module">
    import {setup} from './interactions.ts';
    let circle = document.querySelector('circle');
    setup(circle);
  </script>
</svg>

$fill: blue;

circle {
  fill: $fill;
}

export function setup(element: SVGElement) {
  element.addEventListener('click', () => {
    element.setAttribute('fill', 'red');
  });
}

通过 @import 引用的 CSS 文件和通过 import 引用的 JavaScript 文件将打包到编译后的 SVG 文件中。有关如何引用外部文件的信息，请参阅 样式表 和 脚本。

¥CSS files referenced via @import, and JavaScript referenced via import will be bundled into the compiled SVG file. See Stylesheets and Scripts for how to reference an external file.

内联 style 属性

¥Inline style attribute

style 属性可用于任何 SVG 元素来定义 CSS 样式。Parcel 将处理内联 CSS，并将结果插入回 style 属性中。这包括以下引用的 URL，以及为你的目标浏览器转换现代 CSS。

¥The style attribute can be used on any SVG element to define CSS styles. Parcel will process the inline CSS, and insert the result back into the style attribute. This includes following referenced URLs, as well as transforming modern CSS for your target browsers.

<circle
  cx="50" cy="40" r="35"
  style="fill: url(external.svg#gradient)" />

HTML 中的 SVG

¥SVG in HTML

HTML 中的 SVG 可以作为外部文件引用，也可以直接嵌入到 HTML 文档中。

¥SVG in HTML can either be referenced as an external file, or embedded directly into an HTML document.

外部 SVG

¥External SVG

可以通过多种方式从 HTML 引用 SVG 文件。最简单的是使用 <img> 元素，并使用 src 属性引用 SVG 文件。Parcel 将遵循参考并处理 SVG 及其所有依赖。

¥SVG files can be referenced from HTML in several ways. The simplest is to use the <img> element, and reference the SVG file using the src attribute. Parcel will follow the reference and process the SVG and all of its dependencies as well.

<img src="logo.svg" alt="logo" />

如果你的 SVG 是静态的，则此方法非常有效。如果 SVG 引用外部资源（例如其他 SVG、图片、字体、样式表或脚本）或包含任何交互性，则它将无法工作。你也无法通过 HTML 页面中的 CSS 更改 SVG 的样式，也无法使用 JavaScript 操作 SVG 的 DOM，并且用户无法选择 SVG 中的任何文本。

¥This approach works great if your SVG is static. If the SVG references external resources such as other SVGs, images, fonts, stylesheets, or scripts, or contains any interactivity, it won’t work. You also cannot alter the styling of the SVG via CSS in the HTML page or manipulate the DOM of the SVG with JavaScript, and any text in the SVG cannot be selected by the user.

<object> 元素可用于在 HTML 中嵌入外部 SVG，并启用外部引用、脚本编写、交互性和文本选择。使用 data 属性引用 SVG 文件。

¥The <object> element can be used to embed an external SVG in HTML and enable external references, scripting, interactivity, and text selection. Use the data attribute to reference the SVG file.

<object data="interactive.svg" title="Interactive SVG"></object>

这还允许你通过 <object> 元素上的 getSVGDocument() 方法访问 SVG DOM。

¥This also allows you to get access to the SVG DOM via the getSVGDocument() method on the <object> element.

let object = document.querySelector('object');
let svg = object.getSVGDocument();
let circle = svg.querySelector('circle');
circle.setAttribute('fill', 'red');

但是，使用 <object> 元素嵌入的 SVG 无法在 HTML 页面上通过 CSS 设置样式。

¥However, SVGs embedded using the <object> element cannot be styled by CSS on the HTML page.

内联 SVG

¥Inline SVG

SVG 可以直接内联到 HTML 中，而不是作为单独的文件引用。这允许 HTML 页面上的 CSS 设置 SVG 元素的样式。Parcel 支持嵌入 SVG 中的外部引用，就像 SVG 位于单独文件中时一样。

¥SVG can be inlined into HTML directly rather than referenced as a separate file. This allows CSS on the HTML page to style the SVG elements. Parcel supports external references within embedded SVG the same way it does when the SVG is in a separate file.

<!DOCTYPE html>
<html>
  <body>
    <svg width="100" height="100">
      <circle cx="50" cy="50" r="50" />
    </svg>
    <style>
      circle {
        fill: blue;
      }

      circle:hover {
        fill: green;
      }
    </style>
  </body>
</html>

CSS 中的 SVG

¥SVG in CSS

可以使用 url() 函数从 CSS 文件引用 SVG。与 <img> 元素一样，背景图片中的 SVG 不支持样式表等外部资源，并且禁用脚本和交互性。

¥SVG can be referenced from CSS files using the url() function. As with the <img> element, SVGs in background images do not support external resources such as stylesheets, and scripting and interactivity is disabled.

.logo {
  background: url('logo.svg');
}

你还可以使用数据 URL 将小型 SVG 嵌入 CSS 文件中。使用 data-url: 方案来执行此操作，Parcel 将构建 SVG 并将结果内联到编译后的 CSS 中。详细信息请参见 打包内联。

¥You can also embed small SVGs in a CSS file using data URLs. Use the data-url: scheme to do this, and Parcel will build the SVG and inline the result into the compiled CSS. See Bundle inlining for more details.

.logo {
  background: url('data-url:logo.svg');
}

JavaScript 中的 SVG

¥SVG in JavaScript

SVG 文件可以作为 JavaScript 的外部 URL 引用、作为字符串内联，也可以转换为 JSX 以在 React 等框架中渲染。

¥SVG files can either be referenced as an external URL from JavaScript, inlined as a string, or converted to JSX for rendering in a framework like React.

URL 参考

¥URL references

Parcel 支持使用 URL 构造函数引用 SVG 文件。此示例使用结果通过 JSX 渲染 <img> 元素。其工作方式与上面 外部 SVG 中描述的相同。如果 SVG 是交互式的或具有外部资源，则可以使用 <object> 元素。

¥Parcel supports referencing SVG files using the URL constructor. This example uses the result to render an <img> element using JSX. This works the same way as described in External SVG above. You can use an <object> element instead if the SVG is interactive or has external resources.

const logo = new URL('logo.svg', import.meta.url);

export function Logo() {
  return <img src={logo} alt="logo" />;
}

有关更多详细信息，请参阅 JavaScript 文档中的 URL 依赖。

¥See URL dependencies in the JavaScript docs for more details.

作为字符串内联

¥Inlining as a string

通过使用 bundle-text: 方案导入，SVG 可以作为 JavaScript 中的字符串内联。

¥SVG can be inlined as a string in JavaScript by importing it using the bundle-text: scheme.

import svg from 'bundle-text:./logo.svg';

let logo = document.createElement('div');
logo.innerHTML = svg;
document.body.appendChild(logo);

详细信息请参见 打包内联。

¥See Bundle inlining for more details.

作为 React 组件导入

¥Importing as a React component

@parcel/transformer-svg-react 插件可用于将 SVG 文件导入为 React 组件。这使用 SVGR 将 SVG 文件转换为 JSX。它还使用 SVGO 来优化 SVG 以减小文件大小。

¥The @parcel/transformer-svg-react plugin can be used to import an SVG file as a React component. This uses SVGR to transform the SVG file into JSX. It also uses SVGO to optimize the SVG to reduce file size.

该插件不包含在默认的 Parcel 配置中，因此你需要安装它并将其添加到你的 .parcelrc.conf 文件中。

¥This plugin is not included in the default Parcel config, so you'll need to install it and add it to your .parcelrc.

yarn add @parcel/transformer-svg-react --dev

你可以配置 .parcelrc 将所有 SVG 转换为 JSX，或者使用命名管道创建可从 JavaScript 导入语句引用的 URL 方案。这种方法允许从 JavaScript 引用的 SVG 文件转换为 JSX，但在其他地方引用的 SVG 保留为 SVG 文件。在将 SVG 转换为 JSX 之前，首先使用 "..." 语法运行默认的 SVG 转换器。

¥You can either configure your .parcelrc to convert all SVGs to JSX, or use a named pipeline to create a URL scheme that you can reference from a JavaScript import statement. This approach allows SVG files referenced from JavaScript to be converted to JSX, but SVGs referenced elsewhere to be kept as SVG files. Use the "..." syntax to run the default SVG transformer first before converting the SVG to JSX.

{
  "extends": "@parcel/config-default",
  "transformers": {
    "jsx:*.svg": ["...", "@parcel/transformer-svg-react"]
  }
}

import Icon from "jsx:./icon.svg";

export const App = () => <Icon />;

生产

¥Production

在生产模式下，Parcel 包括优化以减少代码的文件大小。有关其工作原理的更多详细信息，请参阅 生产。

¥In production mode, Parcel includes optimizations to reduce the file size of your code. See Production for more details about how this works.

缩小化

¥Minification

在生产模式下，Parcel 会自动缩小代码以减小打包包的文件大小。默认情况下，Parcel 使用 SVGO 执行 SVG 缩小。

¥In production mode, Parcel automatically minifies your code to reduce the file sizes of your bundles. By default, Parcel uses SVGO to perform SVG minification.

要配置 SVGO，你可以在项目根目录中创建 svgo.config.json 文件。要查看 SVGO 的所有可用配置选项，请参阅 官方文档。

¥To configure SVGO, you can create a svgo.config.json file in your project root directory. To see all the available configuration options for SVGO, see the official documentation.

{
  "plugins": [
    {
      "name": "preset-default",
      "params": {
        "overrides": {
          "inlineStyles": false
        }
      }
    }
  ]
}