SVG 基础语法与文档结构

5 minBeginner2026/7/18

svg 根元素、命名空间、defs/metadata/title、嵌套与分组。

1. svg 根元素

<svg> 是 SVG 文档的根元素，承载坐标系、视口与全局属性。

<svg
  width="400"
  height="300"
  viewBox="0 0 400 300"
  xmlns="http://www.w3.org/2000/svg"
  xmlns:xlink="http://www.w3.org/1999/xlink"
>
  <!-- 内容 -->
</svg>

1.1 关键属性

属性	作用	说明
`width` / `height`	视口尺寸	可用像素或百分比；内联 SVG 省略时默认 100% × 100%
`viewBox`	内部坐标系	`min-x min-y width height`，决定图形映射到视口的方式
`xmlns`	命名空间	独立 .svg 文件必需；内联在 HTML 中可省略
`preserveAspectRatio`	宽高比策略	控制 viewBox 如何适配视口
`role` / `aria-label`	可访问性	为屏幕阅读器提供语义

1.2 内联 vs 独立文件

<!-- 内联：HTML 解析器宽容，可省略 xmlns -->
<svg viewBox="0 0 100 100">
  <circle cx="50" cy="50" r="40" />
</svg>

<!-- 独立 .svg 文件：必须有 xmlns 与 XML 声明 -->
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
  <circle cx="50" cy="50" r="40" />
</svg>

2. 文档结构元素

2.1 `<g>` 分组

<g>（group）将多个元素逻辑分组，可统一应用样式与变换。

<svg viewBox="0 0 200 100">
  <g fill="#4f5bd5" stroke="#fff" stroke-width="2">
    <circle cx="50" cy="50" r="30" />
    <rect x="90" y="20" width="60" height="60" rx="8" />
  </g>
</svg>

子元素继承 <g> 上的 fill、stroke、transform 等可继承属性。

2.2 `<defs>` 定义

<defs> 存放可复用资源（渐变、滤镜、符号、路径），不直接渲染，通过 url(#id) 引用。

<svg viewBox="0 0 200 100">
  <defs>
    <linearGradient id="brand" x1="0%" x2="100%">
      <stop offset="0%" stop-color="#4f5bd5" />
      <stop offset="100%" stop-color="#00b894" />
    </linearGradient>
  </defs>
  <rect width="200" height="100" fill="url(#brand)" />
</svg>

2.3 `<symbol>` 符号

<symbol> 类似 <g>，但自带 viewBox，适合定义可复用图标，配合 <use> 实例化。

<svg>
  <symbol id="icon-close" viewBox="0 0 24 24">
    <path d="M6 6 L18 18 M18 6 L6 18" stroke="currentColor" stroke-width="2" />
  </symbol>
  <use href="#icon-close" x="0" y="0" width="24" height="24" />
</svg>

2.4 `<use>` 引用

<use> 复制并实例化 <g>、<symbol> 或其他元素。

<use href="#icon-close" x="100" y="50" width="32" height="32" fill="#d63031" />

href 替代了旧版的 xlink:href（SVG 2 推荐）。跨文件引用：

<use href="icons.svg#icon-close" width="24" height="24" />

2.5 `<title>` 与 `<desc>`

为可访问性提供标题与描述，类似 <img alt>。

<svg viewBox="0 0 200 100" role="img" aria-labelledby="t d">
  <title id="t">2024 年度销售额</title>
  <desc id="d">柱状图展示四个季度的销售额对比</desc>
  <!-- 图形 -->
</svg>

2.6 `<metadata>` 元数据

存放 RDF / DC 等元信息，不参与渲染。

<metadata>
  <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description rdf:about="" xmlns:dc="http://purl.org/dc/elements/1.1/">
      <dc:creator>fanquanpp</dc:creator>
      <dc:date>2026-07-18</dc:date>
    </rdf:Description>
  </rdf:RDF>
</metadata>

3. 元素嵌套规则

SVG 元素存在严格的嵌套约束，违反会导致渲染异常。

3.1 容器元素

可包含其他图形元素的容器：<svg>、<g>、<defs>、<symbol>、<a>、<mask>、<pattern>、<marker>。

3.2 图形元素

只能作为叶子节点或包含动画元素：<rect>、<circle>、<ellipse>、<line>、<polyline>、<polygon>、<path>、<text>、<image>、<use>。

3.3 嵌套 `<svg>`

<svg> 可嵌套，建立独立坐标系，常用于组件化场景。

<svg viewBox="0 0 400 200">
  <svg x="0" y="0" width="200" height="200" viewBox="0 0 100 100">
    <circle cx="50" cy="50" r="40" fill="#4f5bd5" />
  </svg>
  <svg x="200" y="0" width="200" height="200" viewBox="0 0 100 100">
    <rect x="10" y="10" width="80" height="80" fill="#00b894" />
  </svg>
</svg>

3.4 `<switch>` 与特性检测

<switch> 按顺序渲染第一个 requiredFeatures 匹配的子元素，用于兼容降级。

<switch>
  <text requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> 高级特性可用 </text>
  <text>降级文本</text>
</switch>

4. 属性继承规则

SVG 属性分为可继承与不可继承两类，理解继承可减少重复声明。

4.1 可继承属性

类别	属性
颜色	`color`、`fill`、`stroke`、`stop-color`
描边	`stroke-width`、`stroke-linecap`、`stroke-linejoin`、`stroke-dasharray`
文本	`font-family`、`font-size`、`font-weight`、`text-anchor`、`direction`
其他	`opacity`、`visibility`、`cursor`、`letter-spacing`

4.2 不可继承属性

x、y、cx、cy、r、width、height、transform、filter、clip-path、mask 等几何与变换属性不可继承。

4.3 `currentColor` 关键字

currentColor 引用当前元素的 color 属性，实现与 CSS 联动的主题色。

<g color="#d63031">
  <rect width="100" height="100" fill="currentColor" />
  <circle cx="150" cy="50" r="40" stroke="currentColor" fill="none" />
</g>

修改 color 即可统一调整 fill 与 stroke 颜色，是图标系统主题化的核心技巧。

5. 完整文档示例

<?xml version="1.0" encoding="UTF-8"?>
<svg
  xmlns="http://www.w3.org/2000/svg"
  viewBox="0 0 300 150"
  role="img"
  aria-labelledby="title desc"
>
  <title id="title">品牌 Logo</title>
  <desc id="desc">由矩形与圆形组合而成的简化 Logo</desc>

  <defs>
    <linearGradient id="brand-grad" x1="0%" x2="100%">
      <stop offset="0%" stop-color="#4f5bd5" />
      <stop offset="100%" stop-color="#00b894" />
    </linearGradient>
    <symbol id="dot" viewBox="0 0 20 20">
      <circle cx="10" cy="10" r="8" fill="#fff" />
    </symbol>
  </defs>

  <g fill="url(#brand-grad)">
    <rect x="10" y="30" width="200" height="90" rx="12" />
  </g>

  <use href="#dot" x="180" y="55" width="30" height="30" />
  <text x="110" y="80" text-anchor="middle" fill="#fff" font-size="28" font-family="sans-serif">
    FANDEX
  </text>
</svg>

下一篇将深入 viewBox 与坐标系，这是 SVG 缩放适配的核心机制。