第5章：文档结构

5.5. ‘symbol’ 元素

‘symbol’ 元素用于定义图形模板， 可以通过 ‘use’ 元素实例化， 但不会直接渲染。

‘symbol’ 为其包含的图形建立嵌套坐标系统。 当 symbol 作为 ‘use’ 元素的 引用元素实例化时，其渲染效果与嵌套的 ‘svg’ 元素非常相似。

x、y、宽度 和 高度 几何属性 在 ‘svg’ 元素上具有相同的效果， 当‘symbol’ 被 ‘use’ 元素实例化时。 特别是，如果宽度和高度 计算为 auto （并且未被实例化的‘use’元素上的值覆盖）， 那么它们将被视为100%的值。

在 SVG 2 中新增。 允许在符号上指定几何属性 提供了更一致的渲染模型， 并允许作者为每个符号设置默认大小 （仍然可以通过‘use’元素上的属性进行覆盖）。

5.5.1. 属性

名称	值	初始值	可动画
refX	<length> | left | center | right	(无)	是
refY	<length> | top | center | bottom	(无)	是

在 SVG 2 中新增。添加此属性使对齐符号到特定点更加容易，正如在地图中常做的那样。与‘marker’上的匹配属性类似。

将 refX/refY 添加到符号元素。已在莱比锡面对面会议中解决。 状态：完成。

我们将为标记/符号上的 refX/refY 添加 top/center/bottom 和 left/center/right 关键字。已在伦敦面对面会议中解决。值的灵感来自'background-position'。 状态：完成。

‘refX’ 和 ‘refY’ 属性定义了 符号的参考点，该点应精确放置在符号的 x,y 定位坐标上， 由x和y 属性及其变换定义的累积效应。

关键字值与‘refX’ 和 ‘refY’ 属性在 ‘marker’ 元素上的含义相同， 在适用方向上解析为 0%、50% 或 100%。

与其他定位属性不同， ‘refX’ 和 ‘refY’ 被解释为在符号内容的坐标系统中，应用了‘viewBox’ 和‘preserveAspectRatio’ 属性后。 如果未指定其中一个或两个属性， 则在相应维度上不进行调整， 符号的矩形视口区域的顶部或左侧 （无论‘viewBox’坐标如何） 将位于x,y 点。

为了向后兼容， 当‘refX’ 和 ‘refY’ 在‘symbol’上未指定时的行为， 与指定为0时的行为不同， 因此与在‘marker’上未指定的等效属性的行为不同。

5.5.2. 关于符号的说明

使用‘symbol’ 元素来表示在同一文档中多次使用的图形，增加了结构和语义。 与‘symbol’元素密切相关的是 ‘marker’和‘pattern’元素； 这三者都定义了一个图形内容的容器，可以在SVG中以不同位置和比例重复渲染。 然而，虽然模式和标记中的重用图形 为另一个元素提供了图形效果， ‘symbol’中的内容将被嵌入 作为完全交互的内容，放在使用元素阴影树 中。

用户代理样式表将 ‘symbol’元素的 overflow属性设置为 hidden，这导致在符号的SVG视口边界处创建一个矩形裁剪路径。 除非覆盖overflow属性， 否则任何位于符号内的图形如果超出符号的SVG视口将会被裁剪。

‘symbol’元素 绝不能直接渲染； 它们的唯一用法是作为可以通过‘use’元素引用的内容。 用户代理必须将‘symbol’元素的 display属性设置为none， 作为用户代理样式表的一部分， 并且此声明必须高于任何其他CSS规则或呈现属性。

生成的实例的‘symbol’ 作为‘use’元素的直接引用元素 必须始终具有inline的计算值 对于display属性。 换句话说，每当宿主‘use’元素被渲染时，必须进行渲染。 用户代理样式表再次定义此声明 必须高于任何其他CSS规则或呈现属性。 任何其他‘symbol’ 被克隆以在使用元素阴影树中创建元素实例 的行为类似于符号定义，且不得被渲染。

5.6. ‘use’ 元素

‘use’ 元素引用了另一个元素，其副本将替换文档中的 ‘use’ 元素进行渲染。引用的元素可以是 容器元素，在这种情况下，将使用以该元素为根的完整 SVG 文档子树的副本。

克隆的内容继承了 ‘use’ 元素的样式，并且可以成为用户事件的目标。但是，这些克隆的元素实例仍然链接到引用的源，并反映原始 DOM 的变更。此外，引用元素作用域中的所有样式规则也适用于克隆的 shadow tree。

x、y、宽度和 高度几何属性指定了引用元素的位置。如果 引用元素定义了视口（例如，它是 ‘svg’ 或 ‘symbol’），那么除了 auto 之外的值会覆盖该元素上相应的几何属性值。

负值的 宽度或高度将被视为非法值。如果 宽度或 高度 为零，且这些属性对 引用元素 有影响，则该元素的渲染将被禁用。

x 和 y 属性会影响该元素的用户坐标系。有关实现详细信息，请参见 布局部分。

名称	值	初始值	是否可动画
href	URL [URL]	(无)	是

URL 引用指向要克隆以供渲染的 SVG 文档中的元素/片段。

‘use’ 元素可以通过指定没有片段的 ‘href’ 值来引用整个 SVG 文档。这种引用被认为是指向引用文档的根元素。

请参考URL 引用属性和 已弃用的 XLink 属性的常见处理方式。

SVG 2 中的新特性：一个没有片段的 ‘href’ 允许引用整个 SVG 文档，而不必确保其根元素上有一个 ID。

用户代理可以出于安全原因限制外部资源文档的使用。特别是，本规范不允许 ‘use’ 中的跨域资源请求。未来的版本或其他规范可能会提供一种安全地启用跨域资源重用的方法。

当设置了 ‘href’ 属性（或在没有 ‘href’ 属性的情况下，设置了 ‘xlink:href’ 属性）时，用户代理必须 处理 URL。通过 URL 处理得到的目标元素就是 ‘use’ 元素的 引用元素。

如果通过解析 URL 得到的 引用元素 既不是 SVG 元素，也不是可以包含在 SVG 容器元素中的 HTML 命名空间中的元素，那么该引用是 无效的，‘use’ 元素有误。

如果引用元素是 ‘use’ 元素的（包含影子树的）祖先，则这是一个 无效的循环引用，‘use’ 元素有误。

否则，用户代理必须生成 影子树 的 重用图形 作为 ‘use’ 元素的内容，正如下一节中描述的那样，use 元素的影子树。

一个拥有未解析或无效 URL 引用的 ‘use’ 不会被渲染。对于边界框计算，它等同于一个空的容器元素。

5.6.1. use 元素的影子树

‘use’ 元素生成的 重用图形 是通过 影子树定义的。从交互性和样式继承的角度来看，它们与 SVG 中其他类型的 重用图形（例如 ‘pattern’ 和 ‘marker’ 的内容）有很大不同。

影子树中的元素会像 ‘use’ 元素是一个容器并且它们是其子元素一样进行渲染。然而，SVG 文档对象模型（DOM）只包含 ‘use’ 元素及其属性。SVG DOM 并不包括作为 ‘use’ 元素子元素的元素实例。

支持脚本和文档对象模型的用户代理必须按照本节所述并符合 DOM 规范或其未来替代方案，来实现 use 元素的影子树。相比之下，不支持动态交互处理模式的用户代理可能不需要实现影子 DOM 的所有细节。然而，所有用户代理必须确保重用图形的布局、样式继承、多媒体和声明动画（如果适用）像实现了影子 DOM 一样进行渲染。

在讨论 ‘use’ 元素及其影子树时，适用以下定义：

引用元素

由 ‘href’（或 ‘xlink:href’）属性在 ‘use’ 元素上指定的元素，或者如果提供的 URL 没有包含链接到特定元素 ‘id’ 的目标片段，则为该属性引用的文档的根元素。

引用的文档子树

引用图形

引用的元素及其所有子节点。

影子根节点

ShadowRoot 对象，一种 DocumentFragment 节点，与宿主 Element 关联，包含用于渲染宿主的内容。影子根节点应符合 DOM 规范或其未来替代方案。

影子宿主

宿主

具有关联影子根节点的元素；使用与 DOM 标准中的宿主定义一致。

影子树

根节点为影子根节点的节点树；使用与 DOM 标准中的影子树定义一致。

use 元素影子树

宿主为 ‘use’ 元素的影子树，包含通过克隆引用图形生成的元素实例。

元素实例

实例

在 use 元素的影子树中生成的元素，源自引用文档子树中的对应元素。

实例根节点

引用元素的元素实例；它始终是 ‘use’ 元素影子根节点的直接子元素。

对应元素

对于每个元素实例，引用文档子树中与其克隆对应的元素。

对应 use 元素

对于每个元素实例，导致它在文档中渲染的 ‘use’ 元素。如果该元素本身不是 ‘use’ 元素影子树中的元素实例，则为该元素的影子根宿主 ‘use’ 元素；否则，递归地退出影子树，直到找到未在另一个 ‘use’ 元素影子树中生成的 ‘use’ 元素。

当用户代理成功解析一个 ‘use’ 元素以识别 引用元素 时，必须创建一个宿主为该 ‘use’ 元素本身的 use 元素影子树。即使该 ‘use’ 元素因是 永不渲染的元素的后代、条件处理或其祖先元素上的 display 属性被设置为 none 而未被渲染，也必须创建该影子树。

影子树中的每个节点都是从 引用文档子树中的对应节点克隆生成的 实例。影子节点都从 实例根节点开始，实例根节点是 引用元素的实例，并且它本身是影子根节点的直接子元素。

影子树是开放的（可通过脚本检查），但只读。任何直接修改影子树中元素、属性和其他节点的尝试都会抛出 NoModificationAllowedError。

在 use 元素影子树 中，‘script’ 元素是无效的（不会执行）；‘audio’ 和 ‘video’ 元素受 多媒体部分的限制。

以前的 SVG 版本将影子树的内容限制为 SVG 图形元素。本规范允许克隆任何有效的 SVG 文档子树。然而，克隆非图形内容通常不会有任何可见的效果。

如果引用的元素位于外部文件中，那么属性和样式属性中的所有 URL 引用必须如 生成绝对 URL 中所述那样变为绝对路径，然后将值复制到 元素实例。影子树本身使用包含它的文档相同的文档基本 URL。

用户代理必须确保对 引用文档子树的所有更改都反映在影子树中，包括对元素、属性、文本和其他节点的更改。此外，对引用图形生效的样式表的更改必须反映在影子树范围内的样式表更改中，如 样式继承 部分中进一步描述的那样。

如果 ‘use’ 元素或 引用元素 以某种方式被修改，导致 ‘use’ 元素的 URL 引用再次变为 未解析状态，那么该 use 元素的整个影子树将被丢弃。

当 ‘use’ 引用的另一个元素也是 ‘use’ 元素，或者其内容包含 ‘use’ 元素时，上述影子 DOM 克隆方法是递归的。然而，一组直接或间接引用一个元素以创建循环依赖的引用是一个无效的循环引用。用户代理不得渲染该 ‘use’ 元素或其影子树。

5.6.2. 重用图形的布局

x、y、宽度 和 高度 属性的值 在 ‘use’ 元素 上用于定位重用的图形 并设置视口大小， 如果 引用元素 定义了嵌套视口。 这些属性在 ‘use’ 元素上的效果 与其在 图形元素 上的效果显著不同， 或与其在 CSS 框模型中的效果不同。

x 和 y 属性定义了 一个附加变换 (translate(x,y)， 其中 x 和 y 表示对应属性的计算值) 应用于 ‘use’ 元素， 在任何由其他属性指定的变换之后 （即附加到变换列表的右侧）。

宽度 和 高度 属性 在 ‘use’ 元素 上覆盖引用的 ‘svg’ 或 ‘symbol’ 元素 上的对应属性值 在确定该属性在 实例根 元素上的使用值时。 然而，如果 ‘use’ 元素上的属性计算值为 auto， 则该属性将按照元素实例的正常计算方式计算。

因此，这些属性可以用于缩放定义其自身坐标系统的图形， 每次重用时。 因为 auto 是初始值， 如果在 ‘use’ 元素上未显式设置尺寸， 则将使用在 ‘svg’ 或 ‘symbol’ 上设置的值作为默认值。

宽度 和 高度 属性 在 ‘use’ 元素 上没有效果 如果 引用元素 不 建立新的视口。 特别是，‘use’ 元素本身并不建立新的视口， 因此不影响重用图形中百分比的解释。

在所有其他方面， 使用元素影子树 中的元素的渲染和布局 的发生方式就像 ‘use’ 元素是其影子内容的容器。 特别是，除非影子树中的元素建立新的视口， 否则它们必须在 ‘use’ 元素定义的坐标系统中绘制 （包括任何累积的变换）。 这影响了百分比长度的解释， 以及具有 userSpaceOnUse 单位的图形效果。

5.6.3. 样式作用域和继承

使用元素阴影树，像其他阴影树一样，表现出样式封装，正如在CSS 作用域模块[css-scoping-1]中定义的那样。这意味着阴影树中的元素从其宿主 ‘use’元素继承样式，但外部文档中定义的样式规则不会匹配阴影树中的元素。相反，阴影树维护自己的一组样式表，其CSS规则与阴影树中的元素匹配。

呈现属性和‘style’属性从引用的图形中克隆到元素实例中，方式与其他属性相同。

当引用元素来自与‘use’元素相同的文档时，来自同一文档的样式表将在原始文档和阴影树文档片段中同时应用。主文档中的样式表的任何更改也会影响阴影树；通过文档和阴影根文档片段的styleSheets属性访问的StyleSheetList对象必须是相同的。如果‘style’元素在引用文档子树中重复，则元素实例上的styleSheet属性指向与对应元素相同的对象。

当引用元素来自外部文档时，处理该文档时生成的样式表对象适用于阴影树，并且是只读的。样式表中的所有URL引用，包括仅片段引用，必须相对于包含引用元素的文档的URL进行绝对引用。用户代理可以重用同一样式表对象用于任何引用该外部文档的阴影树。

作用于阴影树的样式规则通常不能影响主文档中的任何元素。同样，主文档中的样式规则只能通过更改继承值来影响阴影树元素。然而，CSS 作用域定义了从阴影树内部样式化宿主元素的特殊选择器，或者根据宿主上下文的变化调整阴影树内的样式[css-scoping-1]。

阴影树作用域内的CSS媒体查询使用与对应的“光”文档相同的设备特征和尺寸进行评估（即，包含阴影树的对应使用元素的文档，在递归退出所有嵌套阴影树后）。

在大多数情况下，阴影树中的元素实例将与原始文档中的对应元素匹配相同的样式规则。然而，如果CSS规则使用复杂选择器根据其祖先或兄弟匹配元素，并且那些祖先或兄弟没有被克隆作为阴影树的一部分，则该规则将不再匹配元素实例。同样，像nth-of-type和nth-child这样的子索引伪类可能适用于一个元素但不适用于另一个元素。这代表了与SVG早期版本中定义的样式克隆有所变化。

以下示例演示了样式匹配规则的一致性和变化。左侧的圆形被重用来绘制右侧的圆形。原始圆形以各种方式设置样式：

• 描边宽度（20）通过圆形本身的呈现属性设置。
• 描边不透明度（0.7）通过匹配圆形标签名称的简单选择器的CSS规则设置。
• 描边颜色（绿色）使用复杂CSS选择器设置，匹配作为带有类special的元素的后代的圆形。
• 填充颜色未直接在圆形上设置，因此从包含的‘g’元素设置的样式继承（蓝色）。

在SVG 1.1样式克隆模型中，指定样式值将从原始元素克隆到元素实例。重用的圆形将具有与原始圆形相同的样式，除了填充值将从‘use’（橙色）而不是从‘g’（蓝色）继承。

在SVG 2要求的阴影DOM模型中，重用圆形的样式计算如下：

• 描边宽度（20）呈现属性被克隆到元素实例。
• 设置描边不透明度（0.7）的CSS规则是克隆到阴影树中的CSS样式表的一部分；它与元素实例的圆形标签名称匹配，因此应用。
• 具有复杂选择器的CSS规则也是克隆样式表的一部分，但它不匹配圆形的元素实例，因为它不是带有类special的元素的后代；相反，圆形上的描边颜色从宿主‘use’元素继承（紫色）。
• 填充颜色仍未直接设置，因此再次从宿主‘use’元素继承。

因此，重用的圆形在填充颜色（因为它从不同元素继承）和描边颜色（因为复杂选择器不再匹配）上与原始圆形不同。

<svg xmlns="http://www.w3.org/2000/svg"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     width="200" height="100" viewBox="0 0 200 100">
  <title>样式继承和使用元素</title>
  <desc>
    两个圆形，其中一个是另一个的重新样式克隆。
    此文件演示了在SVG 2中，
    阴影DOM样式匹配规则与SVG 1.1样式克隆规则不同的一个情况。
    左侧的原始圆形
    应该有蓝色填充
    和绿色描边。
    在符合SVG 1.1的用户代理中，
    右侧的重用圆形
    应该有橙色填充和绿色描边。
    在符合SVG 2的用户代理中，
    重用圆形应具有橙色填充和紫色描边。
    在所有情况下，
    描边应部分透明
    并宽20个单位，
    相对于总直径为100个单位的圆形。
  </desc>
  <style type="text/css">
    circle          { stroke-opacity: 0.7; }
    .special circle { stroke: green; }
    use             { stroke: purple;
                      fill: orange; }
  </style>
  <g class="special" style="fill: blue">
     <circle id="c" cy="50" cx="50" r="40"
             stroke-width="20">
  </g>
  <use xlink:href="#c" x="100">
</svg>

示例 使用改变样式

以SVG格式查看此示例 （仅限支持SVG的浏览器）

之前的SVG版本 对于动态伪类 （如:hover） 应如何应用于元素实例并不明确。 阴影树模型要求所有此类伪类 独立于 元素实例或其 对应元素进行匹配， 具体取决于用户与哪个元素交互。

在‘use’元素上指定'visibility:hidden'并不能保证 被引用的内容不会被渲染。 与display或opacity属性不同， visibility属性并不直接应用于容器元素， 因此也不直接应用于‘use’元素。 由于visibility通常是继承的， 隐藏使用元素通常会隐藏子内容， 但不一定。 如果阴影树中的任何图形元素指定了 'visibility:visible'，那么该 元素即使‘use’元素指定了'visibility:hidden'，也会可见。

在以下示例中，关键样式规则如下：

.dark {
  visibility: hidden;
}
.eyes {
  visibility: visible;
}
svg:hover .dark, svg:focus .dark {
  visibility: visible;
}

"dark"类被设置在包含‘use’元素的组上， 因此重用图形的所有部分都继承了隐藏的可见性设置， 除了具有类"eyes"的子树，其中可见性被重置为可见。 在悬停或聚焦图形时，隐藏效果被移除。

示例 使用可见性隐藏，默认样式

示例 使用可见性隐藏，互动样式

以SVG格式查看此示例

该示例还演示了其他样式属性的继承 （填充和描边） 指定在‘use’元素上， 以及如何在符号内的任何元素指定显式值时（例如，粉色的鼻子和耳朵以及白色的尾巴）这些也不被使用。

5.6.4. 使用元素阴影树中的多媒体

当使用元素阴影树包含 ‘audio’或‘video’元素时， 必须执行以下行为：

• 用户代理必须将媒体播放与对应元素 （如果它作为同一文档的一部分被渲染）和文档中同一对应元素的任何其他实例同步。
• 如果‘use’元素 未被渲染，则该实例不得播放任何音频。
• 如果为对应元素提供了用户代理的播放控件 （或如果该元素被渲染将包括这些控件）， 则它们必须包含在文档中的所有实例中， 并且对任何实例的用户操作必须控制它们的所有播放。

5.6.5. 使用元素阴影树中的动画

Web 动画 API [web-animations-1] 和SVG 动画规范 [svg-animation] 定义了非 CSS 方法来动画化 目标元素的属性和样式，而不直接操作 DOM 属性 （详见动画附录）。 实现这些功能的用户代理 必须确保所有适用于引用文档子树中元素的动画 也适用于使用元素阴影树中的该元素实例， 如本节所述。

在使用元素阴影树中的所有动画 与对应使用元素的文档时间线相同， 无论引用元素 是来自同一文档还是外部文档。

对于使用Web 动画 API方法 [web-animations-1]应用的动画效果， 如果动画的目标是阴影树中元素实例的对应元素， 用户代理必须构建一个ShadowAnimation ，其源为该Animation对象 ，其目标为元素实例。 如果该元素在不同树中有多个实例， 则会有多个阴影动画，每个实例一个。

用户代理必须为所有在阴影树生成时生效的Web 动画 API 动画 （包括待处理和冻结动画） 创建这样的ShadowAnimation， 并为阴影树存在时应用的任何新动画创建。 用户代理不得为 CSS 动画或动画元素创建 ShadowAnimation对象 （因为这些是单独复制的）。

作为接口定义的一部分， ShadowAnimation是只读的， 必须反映对其sourceAnimation的任何更改。

任何尝试直接将新动画应用于 元素实例（或 伪元素） 在使用元素阴影树中的目标 必须抛出NoModificationAllowedError。

对于每个动画元素 [svg-animation] 其目标是引用文档子树中的元素， 用户代理必须确保在使用元素阴影树中 有一个等效的动画元素。 如果动画元素本身是引用文档子树的一部分， 则通过为动画元素创建 元素实例，这将自然而然地发生。 否则，用户代理必须为动画元素生成一个元素实例 ，其效果就像它是阴影树中的一个节点一样。 这些生成的动画元素的有效文档顺序 必须与其对应元素的文档顺序相同。

每个动画元素或实例只能影响 同一节点树（阴影或光）， 无论目标是隐式（父元素） 还是显式（对元素的 URL 交叉引用‘id’）。 通过这种方式，动画元素和目标元素之间的一对一关系得以保留。

‘id’属性 像其他任何属性一样被克隆， 从对应元素到元素实例； 这不与‘id’的唯一性要求冲突， 因为克隆和原始在不同的节点树中。

所有在文档或阴影树中， 定时开始或结束以响应 另一个元素的事件 由其‘id’属性识别的动画元素， 也必须在任何带有该‘id’的元素的实例 接收到相同事件时开始或结束。 这与如何在引用元素上设置事件监听器也一致 监听该元素实例上的事件， 如使用元素阴影树中的事件处理部分所述。 此行为不适用于仅由事件定义的动画开始或结束时间， 而不是通过‘id’ （因此隐式地监听目标元素上的事件）； 在这种情况下，每个动画元素仅由其自身目标触发。

在阴影树中生成动画元素实例时， 如果与对应元素相关联的活动动画 （包括冻结动画）存在， 并且触发该动画的计时事件也会触发该实例， 则该元素实例的动画必须启动， 其开始时间 在文档时间线上向后调整 以匹配对应元素的时机。

<set href="#target" begin="mouseover" ...>
  <!-- 仅影响鼠标悬停的元素 -->

<set href="#target" begin="target.mouseover" ...>
  <!-- 当任何实例的鼠标悬停时，
          影响具有 id 'target' 的所有元素实例，
          在所有光节点和阴影节点树中 -->
  

5.6.6. 使用元素阴影树中的事件处理

在使用元素阴影树中的元素 可以同时监听和成为 DOM 事件的目标。 事件重新目标提供了封装， 使得当事件从阴影树冒泡到光节点时，阴影 DOM 结构的细节被隐藏。

事件重新目标是 SVG 2 中的新特性。 它与 Shadow DOM 规范、 现有实现一致， 并符合仅关心主 DOM 中元素的作者的期望。

在引用图形中的元素上定义的任何事件监听器 也必须在每个元素实例中监听相同事件，并且在相同的捕获阶段 在使用元素阴影树中。 这包括使用事件属性（这将像其他任何 DOM 属性一样被重复分配）的事件监听器 以及使用addEventListener方法分配的事件监听器。 用户代理必须确保每个元素实例的事件监听器列表 与其对应元素保持同步。 事件监听器不能直接分配给使用元素阴影树中的只读元素实例。 对此类元素添加事件监听器的任何尝试 必须抛出NoModificationAllowedError。

在使用元素阴影树中的事件 根据阴影树的事件路径和事件重新目标算法进行调度和冒泡 [DOM]。

任何容器元素或图形元素在SVG文档中可以拥有零个或多个‘desc’和/或‘title’元素作为子元素，其内容为文本。‘desc’和‘title’元素不会作为图形的一部分进行视觉呈现。display值必须始终设置为none，由用户代理样式表控制，并且此声明必须优先于任何其他CSS规则或呈现属性。

多个兄弟‘desc’或‘title’元素必须具有不同的语言，通过在描述性元素或其祖先上定义的‘lang’属性（或xml:lang属性）来确定。用户代理必须选择与用户设置的语言偏好最佳匹配的每种类型的元素。如果有多个同样有效的匹配，应该使用第一个匹配。如果'title'或'desc'没有匹配，则必须选择该类型的第一个元素。

<svg>
  <use href="#star">
    <title>Favourite</title>
    <title lang="en-us">Favorite</title>
    <title lang="nl">Favoriet</title>
    <title lang="">★</title>
  </use>
</svg>
  

使用多个‘title’或‘desc’元素提供本地化信息存在风险，目前没有已知的实现。

用户代理必须将所选'title'和'desc'元素的文本内容作为父元素名称和描述计算的一部分，提供给平台无障碍API，如SVG无障碍API映射[SVG-AAM]规范中所定义。

任何'title'或'desc'元素作为渲染元素的直接子元素的包含表示该渲染元素在图形中具有语义重要性。作者不应，也SVG生成器必须不，包含没有文本内容或仅包含空白文本内容的空'title'或'desc'元素，因为这将导致无名称对象呈现给辅助技术用户。

如果单个图形元素本身没有意义，则应为描述有意义对象的最近容器元素提供替代文本。作者应使用分组（‘g’）元素将其绘图元素结构化为有意义的对象，并使用‘title’命名这些组。相反，如果容器对象仅用于应用样式或布局，并且既不定义对象也不提供有意义的分组结构，则不需要替代文本。

父元素为未渲染的描述性文本元素可供作者或创作工具作为参考信息；作者被警告，此数据通常对通过辅助技术查看图形的最终用户不可用。尽管如此，未渲染元素可以作为渲染元素的可访问名称或描述的一部分被引用（如SVG-AAM中定义），递归计算将使用引用元素的描述性子元素。

描述和标题元素可以包含来自其他命名空间的标记文本，使用标准XML机制指示命名空间。然而，作者不应依赖此类标记为替代文本提供意义；目前，仅需要将纯文本内容暴露给辅助技术。

HTML解析器以与处理HTML片段中的标记相同的方式处理‘title’和‘desc’元素。通过在SVG文档中嵌套HTML元素，可以创建未定义元素的层次结构；这仅在内容合法时实现。作者不得混合使用HTML和SVG元素以避免意外的影响；具体来说，不得在描述元素中使用“<”或“>”作为文本的一部分。

用户代理可以在‘title’中使用标记来影响标题的视觉呈现（如工具提示），但不是必须这样做。

‘title’ 子元素表示元素的简短文本替代。

在链接上，这可以是目标资源的标题或描述；在图像或图形对象上，它可以是图形的简短描述；在交互内容上，它可以是元素的标签或使用说明，等等。

如果绘图元素有可见标签（例如，使用‘text’元素），作者不应在‘title’元素中提供冗余信息。相反，视觉标签应通过‘aria-labelledby’属性与绘图元素相关联。

交互用户代理应在用户交互时以与平台惯例一致的方式提供‘title’元素的纯文本内容；现有的用户代理通常在悬停父元素时将‘title’元素呈现为工具提示。

作者应在独立 SVG 文档的根 SVG 元素中提供‘title’子元素。由于用户经常在上下文之外查看文档，作者应提供丰富上下文的标题。因此，作者应提供诸如“中世纪养蜂导论”的标题，而不是“导论”，因为后者并没有提供太多上下文信息。出于可访问性的原因，用户代理应始终向用户提供根 SVG 元素的‘title’子元素的内容。然而，这通常是通过其他方式完成的，而不是用于嵌套 SVG 和图形元素的工具提示，例如，通过在浏览器标签中显示。

‘desc’元素 表示元素的更详细文本信息，例如描述。这通常对辅助技术可用，以提供更详细的信息，例如图形的视觉外观描述或帮助解释复杂小部件的功能。它通常对其他用户不可用，因此不应用于重要说明。

作者可以使用‘aria-describedby’ 属性（在描述的元素或父容器上）将详细信息（包括可见文本）与图形的部分关联， 其值为一个或多个包含描述的 SVG 或 HTML 元素的 ID 引用。‘aria-describedby’ 属性在提供描述时优先于子‘desc’ 元素。如果元素同时具有可见描述和提供补充信息的子‘desc’元素，作者应在其自己的‘aria-describedby’ 列表中明确包括该元素自身的‘id’，以便将两个描述连接在一起。

5.12.6. ‘data-*’ 属性

所有 SVG 元素支持 自定义数据 属性， 这些属性是在无命名空间中，其名称以字符串 “data-” 开头。 请参阅 HTML 规范中的自定义数据属性要求。

5.14.1. Document 接口的扩展

DOM Core 规范定义了一个 Document 接口，该接口由本规范扩展。

如果 SVG 文档通过引用嵌入，例如当一个 HTML 文档有一个 ‘object’ 元素，其 ‘data’ 属性引用了一个 SVG 文档（即，MIME 类型为 "image/svg+xml" 且其根元素是一个 ‘svg’ 元素），将会存在两个不同的 DOM 层次结构。 第一个 DOM 层次结构是用于引用文档（例如，XHTML 文档）。第二个 DOM 层次结构是用于被引用的 SVG 文档。

partial interface Document {
  readonly attribute SVGSVGElement? rootElement;
};

rootElement IDL 属性 表示根 ‘svg’ 元素。获取时 rootElement 返回文档的根元素， 如果它是一个 ‘svg’ 元素，则返回该元素，否则返回 null。

该属性已被弃用，并可能在未来的 SVG 规范中被移除。 建议作者使用 documentElement 属性 替代 Document。

实现 HTML 的 SVG 实现必须支持 document 接口的 HTML 扩展。 其他 SVG 实现必须支持以下 IDL 片段。

// 仅在某些实现中实现
partial interface Document {
  readonly attribute DOMString title;
  readonly attribute DOMString referrer;
  readonly attribute DOMString domain;
  readonly attribute Element? activeElement;
};

title、referrer、domain 和 activeElement IDL 属性必须表现得与 HTML 中定义的对应 IDL 属性相同。

5.14.2. 接口 SVGSVGElement

一个 SVGSVGElement 对象表示一个 ‘svg’ 元素 在 DOM 中。SVGSVGElement 接口还包含一些杂项工具方法，例如数据类型对象工厂方法。

一个 SVGSVGElement 对象维护一个内部 DOMPoint 对象，称为 其 当前平移点对象， 该对象是从 currentTranslate IDL 属性返回的对象。

[Exposed=Window]
interface SVGSVGElement : SVGGraphicsElement {

  [SameObject] readonly attribute SVGAnimatedLength x;
  [SameObject] readonly attribute SVGAnimatedLength y;
  [SameObject] readonly attribute SVGAnimatedLength width;
  [SameObject] readonly attribute SVGAnimatedLength height;

  attribute float currentScale;
  [SameObject] readonly attribute DOMPointReadOnly currentTranslate;

  NodeList getIntersectionList(DOMRectReadOnly rect, SVGElement? referenceElement);
  NodeList getEnclosureList(DOMRectReadOnly rect, SVGElement? referenceElement);
  boolean checkIntersection(SVGElement element, DOMRectReadOnly rect);
  boolean checkEnclosure(SVGElement element, DOMRectReadOnly rect);

  void deselectAll();

  SVGNumber createSVGNumber();
  SVGLength createSVGLength();
  SVGAngle createSVGAngle();
  DOMPoint createSVGPoint();
  DOMMatrix createSVGMatrix();
  DOMRect createSVGRect();
  SVGTransform createSVGTransform();
  SVGTransform createSVGTransformFromMatrix(DOMMatrixReadOnly matrix);

  Element getElementById(DOMString elementId);

  // Deprecated methods that have no effect when called,
  // but which are kept for compatibility reasons.
  unsigned long suspendRedraw(unsigned long maxWaitMilliseconds);
  void unsuspendRedraw(unsigned long suspendHandleID);
  void unsuspendRedrawAll();
  void forceRedraw();
};

SVGSVGElement includes SVGFitToViewBox;
SVGSVGElement includes SVGZoomAndPan;
SVGSVGElement includes WindowEventHandlers;

这些 x、 y、 width 和 height IDL 属性 反映 x、y、width 和 height 属性的计算值及其对应的 表现属性。

currentScale 和 currentTranslate IDL 属性表示响应用户放大和平移操作而应用于文档的变换，如 放大和平移中所描述的。

文档的放大和平移 变换是一个形式为 [currentScale 0 0 currentScale currentTranslate.x currentTranslate.y] 的 2x3 矩阵。 ‘transform’ 属性的值不会影响 currentScale 或 currentTranslate。

获取 currentScale 时， 执行以下步骤：

1. 如果当前的 ‘svg’ 元素不是 最外层 svg 元素， 则返回 1。
2. 让 [a b c d e f] 成为表示文档的放大和平移 变换的 2x3 矩阵。
3. 返回 a。

设置 currentScale 时， 执行以下步骤：

1. 如果当前的 ‘svg’ 元素不是 最外层 svg 元素， 则返回。
2. 让 scale 为赋值给 currentScale 的值。
3. 让 [a b c d e f] 成为表示文档的放大和平移 变换的 2x3 矩阵。
4. 将文档的放大和平移变换设置为 [scale 0 0 scale e f]。

获取 currentTranslate 时， SVGSVGElement 对象的 当前平移点对象 被返回。此对象 表示当前平移 对于 ‘svg’ 元素。当前平移点对象 必须在其 ‘svg’ 元素不是 最外层 svg 元素 时为 只读，否则为可写。

请参见 分配给 DOMPoint 的规则， 以了解修改 当前平移点对象 如何影响文档的放大和平移变换。

每当文档的放大和平移变换因用户交互而变化，或者每当 最外层 svg 元素 发生变化时，执行以下步骤：

1. 让 [a b c d e f] 成为表示文档的放大和平移 变换的 2x3 矩阵。
2. 让 element 为 最外层 svg 元素。
3. 更新 element 的 当前平移点对象 的 x 和 y 分量 为 e 和 f，分别。

在 最外层 svg 元素 变化时运行这些步骤将确保，如果文档元素被替换为不同的 ‘svg’ 元素， 其 currentTranslate 将立即更新以反映文档的放大和平移变换的平移分量。

每当 ‘svg’ 元素 不再是 最外层 svg 元素 时， 其 当前平移点对象 的 x 和 y 分量必须设置为 0。

请注意，‘zoomAndPan’ 属性的值 在 最外层 svg 元素 仅控制文档的 放大和平移变换是否可以通过用户交互更新。 无论该属性的值如何，当前比例和平移 都可以通过修改 currentScale 和 currentTranslate 来更改。

suspendRedraw、 unsuspendRedraw、 unsuspendRedrawAll 和 forceRedraw 方法均已弃用，定义为没有效果。当调用 suspendRedraw 方法时，必须返回 1。

getIntersectionList 和 getEnclosureList 方法的定义如同在 交集与包围中所述。

要查找给定元素element的交集或包含后代，使用给定的矩形rectangle，并将ancestor视为解释rectangle坐标空间的元素，执行以下步骤：

1. 让result成为一个最初为空的列表。
2. 如果element由于具有display值为none，或者在具有失败的条件处理属性或失败的分支的子树中，返回result。
3. 对于element的每个子元素child，按文档顺序：
   1. 如果child是‘svg’或‘g’元素，则：
      1. 让descendants成为在ancestor的坐标空间中找到child与rectangle的交集（或包含）后代的结果。
      2. 将descendants的所有元素附加到result。
   2. 否则，如果child是‘use’元素，则：
      1. 让root成为child的影子树的根。
      2. 让descendants成为在ancestor的坐标空间中找到root与rectangle的交集（或包含）后代的结果。
      3. 如果descendants不为空，则将child附加到result。

         这意味着，尽管我们查看child的use-element影子树中的元素，但我们不将元素实例或它们的对应元素放入result列表中；只有‘use’元素本身被返回。

   3. 否则，如果child是图形元素，则：
      1. 让region成为child坐标系统中对命中检测敏感的形状，考虑child的pointer-events值的解释规则。
      2. 将region转换为ancestor的坐标系统。
      3. 如果我们正在查找交集后代，并且region部分或完全位于rectangle内，则将child附加到result。
      4. 否则，我们正在查找包含后代。如果region完全位于rectangle内，则将child附加到result。
4. 返回result。

要查找给定元素element中的非容器图形元素，执行以下步骤：

1. 让result成为一个最初为空的列表。
2. 如果element是‘svg’或‘g’元素，则对于element的每个子元素child，按文档顺序：
   1. 让descendants成为在child中找到非容器图形元素的结果。
   2. 将descendants的所有元素附加到result。
3. 否则，如果element是图形元素，则将element附加到result。
4. 返回result。

当调用getIntersectionList(rect, referenceElement)或getEnclosureList(rect, referenceElement)时，执行以下步骤：

1. 让descendants成为一个列表，具体取决于我们在哪个方法中：

   getIntersectionList

   descendants是当前‘svg’元素与矩形rect在当前‘svg’元素的坐标系统中的交集后代的结果。

   getEnclosureList

   descendants是当前‘svg’元素与矩形rect在当前‘svg’元素的坐标系统中的包含后代的结果。

2. 如果referenceElement不为null，则从descendants中删除任何没有referenceElement作为祖先的元素。
3. 返回一个静态 NodeList，其中包含descendants中的所有元素。 （[DOM], 第5.2.7节）

当调用checkIntersection(element, rect)或 checkEnclosure(element, rect)时，将执行以下步骤：

1. 让descendants成为一个列表，取决于我们所处的方法：

   getIntersectionList

   descendants是当前‘svg’元素与矩形 rect在当前‘svg’元素的坐标系统中的交集后代的结果。

   getEnclosureList

   descendants是当前‘svg’元素与矩形 rect在当前‘svg’元素的坐标系统中的包含后代的结果。

2. 让elements成为 查找非容器图形元素的结果，位于element中。
3. 如果elements为空，则返回false。
4. 如果elements中的任何元素不在descendants中，则返回false。
5. 返回true。

createSVGNumber、 createSVGLength、 createSVGAngle、 createSVGPoint、 createSVGMatrix、 createSVGRect和 createSVGTransform方法都是工厂函数，用于创建特定类型的新数据类型对象。当调用这些方法之一时，将根据下表返回一个新对象：

createSVGPoint、 createSVGMatrix和 createSVGRect方法 都已被弃用，仅保留用于与遗留内容的兼容性。 建议作者使用DOMPoint、DOMMatrix和 DOMRect 构造函数。

createSVGTransformFromMatrix 方法用于根据矩阵对象创建新的SVGTransform对象。 其行为与createSVGTransformFromMatrix 方法在SVGTransformList上的行为相同。

5.14.3. 接口 SVGGElement

SVGGElement对象表示一个‘g’元素在DOM中。

[Exposed=Window]
interface SVGGElement : SVGGraphicsElement {
};

5.14.4. 接口 SVGUnknownElement

SVGUnknownElement对象 表示SVG命名空间中的未知元素。

[Exposed=Window]
interface SVGUnknownElement : SVGGraphicsElement {
};

5.14.5. 接口 SVGDefsElement

SVGDefsElement对象表示一个 ‘defs’元素在 DOM中。

[Exposed=Window]
interface SVGDefsElement : SVGGraphicsElement {
};

5.14.6. 接口 SVGDescElement

SVGDescElement对象表示一个 ‘desc’元素在 DOM中。

[Exposed=Window]
interface SVGDescElement : SVGElement {
};

5.14.7. 接口 SVGMetadataElement

SVGMetadataElement对象 表示一个 ‘metadata’元素在DOM中。

[Exposed=Window]
interface SVGMetadataElement : SVGElement {
};

5.14.8. 接口 SVGTitleElement

SVGTitleElement对象表示 一个‘title’元素在 DOM中。

[Exposed=Window]
interface SVGTitleElement : SVGElement {
};

5.14.9. 接口 SVGSymbolElement

SVGSymbolElement对象 表示一个 ‘symbol’ 元素在DOM中。

[Exposed=Window]
interface SVGSymbolElement : SVGGraphicsElement {
};

SVGSymbolElement包括 SVGFitToViewBox;

在SVG 2中新增。 SVGSymbolElement接口现在 继承自 SVGGraphicsElement， 使得在阴影DOM中实例化的符号可以作为图形元素被查询。

5.14.10. 接口 SVGUseElement

一个 SVGUseElement 对象表示 DOM 中的 ‘use’ 元素。

[Exposed=Window]
interface SVGUseElement : SVGGraphicsElement {
  [SameObject] readonly attribute SVGAnimatedLength x;
  [SameObject] readonly attribute SVGAnimatedLength y;
  [SameObject] readonly attribute SVGAnimatedLength width;
  [SameObject] readonly attribute SVGAnimatedLength height;
  [SameObject] readonly attribute SVGElement? instanceRoot;
  [SameObject] readonly attribute SVGElement? animatedInstanceRoot;
};

SVGUseElement 包含 SVGURIReference;

x, y, width 和 height IDL 属性 反映 了 x、 y、 width 和 height 属性及其对应的呈现属性。

instanceRoot 和 animatedInstanceRoot IDL 属性均指向 实例根， 即是此元素的影子根节点的直接子元素的 SVGElementInstance （u.instanceRoot 等同于获取 u.shadowRoot.firstChild）。 如果此元素没有影子树 （例如，因其 URI 无效 或因被 条件处理 禁用）， 则获取这些属性返回 null。

5.14.11. 接口 SVGUseElementShadowRoot

每个 use-element shadow tree 的根对象 实现 SVGUseElementShadowRoot 接口。 此接口目前未定义对 ShadowRoot 接口 和 DocumentOrShadowRoot 混合体定义的属性和方法的任何扩展。 但是，从作者脚本的角度来看，根植于此节点的树完全是只读的。

[Exposed=Window]
interface SVGUseElementShadowRoot : ShadowRoot {
};

5.14.12. 混合 SVGElementInstance

SVGElementInstance 接口 定义对 SVGElement 接口的扩展， 这些扩展仅用于 use-element shadow tree 中的元素。

在早期版本的 SVG 中， SVG 元素实例被定义为有效的事件目标但不是完整的 DOM 节点的非元素对象。 本规范重新定义了 use-element shadow tree 以使其与影子 DOM 规范一致，这意味着实例实际上是 SVGElement 对象。 此接口为向后兼容添加了缺失的功能。 但是，作者应意识到兼容性并不完美， 并据此设计他们的脚本。 还要注意，这些属性在影子树中的 HTML 命名空间元素对象上不可用。

interface mixin SVGElementInstance {
  [SameObject] readonly attribute SVGElement? correspondingElement;
  [SameObject] readonly attribute SVGUseElement? correspondingUseElement;
};

correspondingElement IDL 属性 如果此元素是 元素实例 在 use-element shadow tree 中，则指向 对应元素， 否则为 null。

当 引用的元素 在外部文件中时， 此指针的存在意味着必须在内存中维护外部文件的整个 DOM。 但是，按照目前的规范，外部 DOM 是只读的。 因此，它提供的功能有限，并可能对性能产生较大影响。 在等待实现者的反馈时， 作者应考虑将对外部文件引用的 correspondingElement 的使用视为风险。

correspondingUseElement IDL 属性 如果此元素是 元素实例 在 use-element shadow tree 中，则指向 对应的使用元素， 否则为 null。

5.14.13. 接口 ShadowAnimation

ShadowAnimation 接口定义了 一个只读的 Animation 对象， 它镜像了从中构造的 sourceAnimation 对象的所有变化。 它们用于镜像在 use-element shadow tree 中 作者发起的动画对象。

[Constructor(Animation source, Animatable newTarget), Exposed=Window]
interface ShadowAnimation : Animation {
  [SameObject] readonly attribute Animation sourceAnimation;
};

sourceAnimation IDL 属性 指向构造函数中传入的 Animation 对象。

构造函数生成一个新的 ShadowAnimation 对象， 它反映了 sourceAnimation 上的所有属性， 但其 effect 是通过构造一个新的 KeyframeEffectReadOnly 来创建的，使用 sourceAnimation 的关键帧效果作为其源， 然后将其 target 修改为匹配 newTarget 参数。

ShadowAnimation 是只读的。 任何尝试设置任何继承的 IDL 属性或调用任何 Animation 方法以改变 其状态的操作， 必须抛出 NoModificationAllowedError。 但是，用户代理必须确保对 sourceAnimation 的任何属性或状态的变化 都会反映在 ShadowAnimation 的变化中。

5.14.14. 接口 SVGSwitchElement

一个 SVGSwitchElement 对象 表示 DOM 中的 ‘switch’ 元素。

[Exposed=Window]
interface SVGSwitchElement : SVGGraphicsElement {
};

5.14.15. 混合 GetSVGDocument

此接口提供对嵌入的 SVG 文档的访问，该文档通过引用嵌入在另一个基于 DOM 的语言中。 期望此接口在允许此类 SVG 文档引用的 DOM 对象上实现。

此接口已被弃用，可能会在未来的 SVG 规范版本中删除。要访问 嵌入在 ‘iframe’ 或 ‘object’ 元素中的 SVG 文档， 建议作者分别使用 contentDocument 属性在 HTMLIFrameElement 或 HTMLObjectElement 接口。

HTMLIFrameElement、 HTMLEmbedElement 和 HTMLObjectElement 接口都定义了自己的 getSVGDocument 方法， 提供以与 GetSVGDocument 相同的方式访问 SVG 文档。因此，这三个 接口无需实现 GetSVGDocument。 仍然，强烈建议作者使用 contentDocument。

interface mixin GetSVGDocument {
  Document getSVGDocument();
};

getSVGDocument 方法 用于返回引用的 SVG 文档。当调用 getSVGDocument() 时， 必须返回嵌入元素引用的 Document 对象 实现 GetSVGDocument 接口；如果没有文档，则返回 null。

请注意，这不会检查引用的文档是否确实是 SVG 文档。 相反，返回任何文档。