<use>

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨2015年7月⁩.

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

<use> 要素は SVG 文書の中からノード取り出して、別の場所に複製します。効果は、あたかもそのノードが非公開の DOM に配下を含めて複製され、 use 要素がある場所に貼り付けられたかのようになり、 template 要素ととても似ています。

例

次の例は、use 要素を使用して、塗りつぶし色と線の色が異なる円を描画する方法を示しています。最後の円では、線は myCircle で既に設定されているため、stroke="red" は無視されます。

html,
body,
svg {
  height: 100%;
}

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>; 既定値: none; アニメーション: 可
xlink:href 非推奨;: 複製する必要がある要素やフラグメントの <IRI> 参照です。 href と xlink:href の両方が存在する場合、 href で指定された値が使用されます。
値の型: <IRI>; 既定値: none; アニメーション: 可
x: この use 要素の X 座標です。
値の型: <coordinate>; 既定値: 0; アニメーション: 可
y: この use 要素の Y 座標です。
値の型: <coordinate>; 既定値: 0; アニメーション: 可
width: この use 要素の幅です。
値の型: <length>; 既定値: 0; アニメーション: 可
height: この use 要素の高さです。
値の型: <length>; 既定値: 0; アニメーション: 可

メモ: width および height は use 要素では効果がありません。ただし、参照される要素に viewBox がある場合を除きます。すなわち、 use が svg または symbol 要素を参照していた時だけ効果があります。

メモ: SVG2 から、 x, y, width, height は位置プロパティとなり、すなわちこれらの属性がその要素への CSS プロパティとしても使用することができるようになりました。

use のほとんどの属性は、 use から参照される要素に既にある属性を上書きしません。 (これは CSS のスタイル属性がカスケードで「以前」に設定されたものを上書きする方法とは異なります)。参照された要素が対応する属性をすでに定義している場合、 use 要素の x, y, width, height, href の各属性のみ、後述するする効果を持つ、あるいは持つ可能性があります。ただし、参照された要素に設定されていないその他の属性は、 use 要素に適用される可能性があります。

クローンされたノードは公開されないので、 CSS を使って use 要素とその隠れた子孫要素にスタイル付けをする場合は注意が必要です。CSS の継承を使用して明示的に要求しない限り、CSS 属性は隠された複製の DOM によって継承されることが保証されません。

セキュリティ上の理由で、ブラウザーは同一オリジンポリシーを use 要素に適用して、 href 属性にあるオリジンをまたがる URL を読み込むことを拒否することがあります。現在のところ、 use 要素の同一オリジンポリシーを設定する方法は定義されていません。

警告: セキュリティ上の理由から、 href 属性にデータ URI を使用してリソースを読み込むことは非推奨となっています。これは、<use href="data:...、および set または setAttribute メソッドを使用して href を設定する場合にも適用されます。さまざまなブラウザーのバージョンでの対応状況については、ブラウザーの互換性表の "Load from data: URI" を参照してください。

警告: SVG 2 で xlink:href 属性が非推奨になり、 href に置き換えられました。詳しくは xlink:href のページを参照してください。

使用コンテキスト

カテゴリー	グラフィック要素、グラフィック参照要素、構造的要素
許可されている内容	任意の数、任意の順序の以下の要素。アニメーション要素説明的要素