<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

浏览器兼容性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
use
Load from data: URI
Load from external URI
height
href
systemLanguage
width
x
xlink:href
Deprecated
y

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
Deprecated. Not for use in new websites.
See implementation notes.