大网数据广告活动
Web 标准与前端开发

<use>

· 52CE 我爱测

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

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

示例

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

html,
body,
svg {
  height: 100%;
}
<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。有关常见陷阱的详细信息,请参阅使用说明。<br/> 值类型:<URL>;默认值:无;动画性:是
  • xlink:href
    • : 需要被复制的元素或片段的 <IRI> 引用。如果同时存在 href 和 xlink:href ,则使用 href 所给的值。<br/> 值类型:<IRI>;默认值:无;动画性:是
  • x
    • : 应用于 <use> 元素的额外最终偏移变换的 x 坐标。<br/> 值类型:<coordinate>;默认值:0;动画性:是
  • y
    • : 应用于 <use> 元素的额外最终偏移变换的 y 坐标。<br/> 值类型:<coordinate>;默认值:0;动画性:是
  • width
    • : use 元素的宽度。<br/> 值类型:<length>;默认值:0;动画性:是
  • height
    • : use 元素的高度。<br/> 值类型:<length>;默认值:0;动画性:是

[!NOTE] 除非引用的元素具有 viewBox,否则 width 和 height 对 use 元素没有任何影响。仅在 use 指向 svg 或 symbol 元素时才有效。

[!NOTE] 从 SVG2 开始,x、y、width 和 height 是几何属性,这意味着这些属性也可以作为该元素的 CSS 属性使用。

使用说明

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

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

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

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

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

使用上下文

规范

浏览器兼容性

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。