<use>

使用コンテキスト

属性

href

複製する必要がある要素やフラグメントへの URL です。よくある落とし穴の詳細については、使用上のメモを参照してください。
値の型: <URL>; デフォルト値: none; アニメーション: 可

xlink:href

複製する必要がある要素やフラグメントの <IRI> 参照です。 href と xlink:href の両方が存在する場合、 href で指定された値が使用されます。
値の型: <IRI>; デフォルト値: none; アニメーション: 可

警告: SVG 2 以降、xlink:href 属性は href に取って代わられ非推奨となりました。詳細は xlink:href ページを参照してください。

x

この <use> 要素に適用される追加の最終オフセット変換の X 座標。
値の型: <coordinate>; デフォルト値: 0; アニメーション: 可

y

この <use> 要素に適用される追加の最終オフセット変換の Y 座標。
値の型: <coordinate>; デフォルト値: 0; アニメーション: 可

width

この <use> 要素の幅です。
値の型: <length>; デフォルト値: 0; アニメーション: 可

height

この <use> 要素の高さです。
値の型: <length>; デフォルト値: 0; アニメーション: 可

DOM インターフェイス

この要素は SVGUseElement インターフェイスを実装しています。

例

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

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>

使用上のメモ

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

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

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

外部リソースから <use> によりリソースを読み込み

外部 SVG ファイルから <use> 要素を使用して、ノードを読み込むことができます。ファイルのパスを指定した後、読み込むノードの id を指す URL フラグメントを続けて指定します。

<svg>
  <use href="../assets/my-svg.svg#my-fragment"></use>
</svg>

過去には、URL フラグメントは、SVG 文書全体を読み込むだけの場合でも、常に必要とされてきました。そのような場合、id は SVG のルート要素に含められていました。

<svg xmlns="http://www.w3.org/2000/svg" id="my-fragment">
  <circle cx="150" cy="100" r="80" fill="green" />
</svg>

しかし、現代の実装では更新が加えられており、外部文書全体を読み込みたい場合、URL フラグメントなしで参照できるようになりました（また、SVG 文書のルート要素に id を指定する必要もなくなりました）。

<svg>
  <use href="../assets/my-svg.svg"></use>
</svg>

ブラウザーの対応については、ブラウザーの互換性一覧表を確認してください。

データ URI から <use> でリソースを読み込み

セキュリティ上の理由から、href 属性にデータ URI でリソースを読み込むことは非推奨です。これは <use href="data:..." の場合だけでなく、set または setAttribute メソッドを使用して href を設定する場合にも適用されます。

こちらも、ブラウザーの対応については、ブラウザーの互換性一覧表を確認してください。

仕様書

ブラウザーの互換性