<use>

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

* Some parts of this feature may have varying levels of support.

<use> 元素从 SVG 文档中获取节点,并将它们复制到其他地方。其效果与将这些节点深度克隆到一个不可导出的 DOM 中,然后粘贴到 use 元素所在的位置相同,这与克隆的模版元素类似。

示例

下面的示例展示了如何使用 use 元素绘制一个具有不同填充色和描边色的圆形。在最后一个圆形中,stroke="red" 将被忽略,因为描边已在 myCircle 上设置。

html
<svg viewBox="0 0 30 10" xmlns="http://www.w3.org/2000/svg">
  <circle id="myCircle" cx="5" cy="5" r="4" stroke="blue" />
  <use href="#myCircle" x="10" fill="blue" />
  <use href="#myCircle" x="20" fill="white" stroke="red" />
</svg>

属性

href

需要被复制的元素或片段的 URL。有关常见陷阱的详细信息,请参阅使用说明
值类型<URL>默认值:无;动画性

xlink:href 已弃用

需要被复制的元素或片段的 <IRI> 引用。如果同时存在 hrefxlink:href ,则使用 href 所给的值。
值类型<IRI>默认值:无;动画性

x

应用于 <use> 元素的额外最终偏移变换的 x 坐标。
值类型<coordinate>默认值0动画性

y

应用于 <use> 元素的额外最终偏移变换的 y 坐标。
值类型<coordinate>默认值0动画性

width

use 元素的宽度。
值类型<length>默认值0动画性

height

use 元素的高度。
值类型<length>默认值0动画性

备注: 除非引用的元素具有 viewBox,否则 widthheightuse 元素没有任何影响。仅在 use 指向 svgsymbol 元素时才有效。

备注: 从 SVG2 开始,xywidthheight几何属性,这意味着这些属性也可以作为该元素的 CSS 属性使用。

使用说明

如果 use 引用的元素上已经定义了相应的属性,则大多数 use 元素上的属性将被忽略。(这与 CSS 样式属性在层叠中如何覆盖“先前”设置的属性有所不同)。只有use 元素上的 xywidthheighthref 属性,若引用的元素已经定义了相应的属性,才会或可能产生一些效果,稍后会进行描述。然而,任何其他属性如果没有在引用的元素上设置,应用于 use 元素。

由于克隆的节点不可导出,因此在使用 CSSuse 元素及其克隆的后代添加样式时必须小心。除非通过 CSS 继承显式请求,否则无法保证克隆的 DOM 会继承 CSS 属性。

出于安全原因,浏览器可能会对 use 元素应用同源策略,并可能拒绝加载 href 属性中的跨源 URL。目前没有定义的方式为 use 元素设置跨源策略。

警告: 出于安全原因,在 href 属性中使用数据 URI 加载资源已被弃用。这适用于 <use href="data:...,以及使用 setsetAttribute 方法设置 href 的情况。请参阅浏览器兼容性表中的“Load from data: URI”部分,以检查不同浏览器版本的支持情况。

警告: 从 SVG 2 开始,xlink:href 属性已被弃用,建议改用 href。有关更多信息,请参阅 xlink:href 页面。

使用上下文

类别图形元素、图形引用元素、结构元素
允许的内容任意数量、任意顺序的下列元素:
动画元素
描述性元素

规范

Specification
Scalable Vector Graphics (SVG) 2
# UseElement

浏览器兼容性

BCD tables only load in the browser