<template>要素

Technical Summary

Definition / Categories

項目	定義
意味	scriptでcloneしてDocumentへ挿入するHTML fragmentの宣言
Categories	Metadata content、Flow content、Phrasing content、Script-supporting element
Context	Metadata、Phrasing、Script-supporting contentが期待される場所。span属性のないcolgroupの子という特殊なcontextもある
Content model	Nothing。markupとして書かれた内容はTemplate Contentsに入る
Tag omission	開始タグ・終了タグとも省略不可
Content attributes	グローバル属性、for、shadowrootmode、shadowrootdelegatesfocus、shadowrootserializable、shadowrootslotassignment、shadowrootclonable、shadowrootcustomelementregistry
DOM interface	HTMLTemplateElement。contentはreadonlyのDocumentFragment

Template ContentsとDOM tree

HTML parserでtemplateの内容を読んだ場合、その内容はtemplate要素の通常のchildとしては扱われません。template.contentが返すTemplate Contentsへ入ります。

<template id="card-template">
  <article>
    <h2>Card</h2>
  </article>
</template>

const template = document.querySelector('#card-template');
template.childNodes.length;         // 0
template.content.childNodes.length; // 1
template.content.firstElementChild.nodeName; // "ARTICLE"

これは単なるCSSの非表示とは異なります。template contentsには、template要素の通常のdescendantとは異なるowner documentとinsertionの処理が関係します。parser、DOM manipulation、adopting、custom elementsを一緒に確認する必要があります。

Clone・Insert・IDの境界

contentはDocumentFragmentです。cloneNode(true)で複製し、複製側の参照を更新してからDocumentへ挿入します。fragmentを複数回使うときは、固定IDの重複、label・for、ARIA参照、form controlのnameと値を個別に設計します。

const template = document.querySelector('#card-template');
const fragment = template.content.cloneNode(true);
const heading = fragment.querySelector('h2');
heading.textContent = 'A cloned card';
document.querySelector('#cards').append(fragment);

同じnodeをそのまま別の場所へ何度も追加するのではなく、必要な回数だけcloneします。外部データをHTMLとして解釈する必要がない場合は、textContentなどで値を設定し、template自身をsanitizerとは扱いません。

表示・実体化・Accessibility

template要素はrendering上何も表現しません。template contentsも、通常のDocument treeへ挿入されるまでは、ページの利用者が操作するライブな内容として扱いません。実体化後は、挿入された見出し、label、button、form control、ARIA関係が通常のsemanticsとAccessibility mappingの評価対象になります。

そのため、templateの中に意味のある内容を書くだけでは、利用者へ届くことを保証できません。JavaScriptが失敗したときのfallback、動的挿入後のfocus、name・role・accessible name、status通知を別に確認します。

Declarative Shadow DOM

shadowrootmodeは、templateをDeclarative Shadow Rootとして扱うための属性です。openとclosedでshadow rootの公開状態が変わり、shadowrootdelegatesfocus、slot assignment、serializable、clonableなどの追加条件が関係します。

<my-card>
  <template shadowrootmode="open">
    <style>:host { display: block; }</style>
    <slot></slot>
  </template>
  <span>Light DOM content</span>
</my-card>

Declarative Shadow DOMでは、parserがshadow treeを作る条件、template contents、slotのassigned nodes、hostとshadow treeのAccessibility境界を分けて扱います。通常のclone用途の結果を、Declarative Shadow DOMの実装結果へそのまま一般化しません。

forとstreaming用途

HTML Standardはtemplateのfor属性を、processing instructionで示した既存の位置へ内容を挿入・置換する仕組みとして定義しています。通常のクライアント側template利用とは別のprocessing modelであり、実装時期と対応範囲を確認してから扱います。

Accessibility

template自身がrendering上何も表現しないことと、template contentsが実体化後にどのようにAccessibility treeへ入るかを分けます。templateは、実体化された見出しやcontrolのaccessible nameを自動的に作る要素ではありません。

段階	確認する対象	注意点
実体化前	template要素とtemplate contents	表示されるライブコンテンツや操作対象として扱わない
通常の挿入後	見出し、label、button、form control、live region	挿入されたDOMのsemanticsとfocusを観測する
Shadow DOM	host、shadow tree、slot、delegates focus	browser・platform・支援技術ごとのmappingを分ける

Fact / Evidence（主張 / 根拠）

template elementの定義、Template Contents、DOM interface、Declarative Shadow DOMを、仕様上の主張と実装観測に分離して記録します。

Evidence

1. HTML Standard: the template element — definition、categories、content attributes、HTMLTemplateElement、rendering
2. DOM Standard: DocumentFragment — template contentsを受け取るfragment interface
3. HTML Accessibility API Mappings — template自身と実体化後の要素をmapping上分けて確認する入口
4. Web Platform Tests: the-template-element — template parsing、content、DOM APIに関係するテスト群の入口
5. Web Platform Tests: declarative Shadow DOM — shadowrootmodeとshadow treeのテスト群の入口

Implementation Evidence

仕様上のprocessing modelと、ブラウザーで観測するTemplate Contents、clone、parser、Declarative Shadow DOM、Accessibility Treeを分けて登録します。専用fixtureをまだ実行していないため、未実施の項目を確認済みとは扱いません。

専用fixture候補: template-v1で、childNodesとcontentの差、deep clone、fragment insertion、重複ID、shadowrootmode、実体化前後のAccessibility Treeを再現する。

Coverage / Open Issues

• 確認済み意味、categories、context、content model、tag omission、content attributes
• 確認済みTemplate Contents、DocumentFragment、content、clone・insertの仕様上の入口
• 確認済みshadowrootmode、slot assignment、focus delegation、serializationに関する仕様上の入口
• 未完了Chrome・Firefox・Safariのparser、custom elements、adopting、動的変更、重複IDとform・ARIA参照の比較
• 未完了Declarative Shadow DOM、slot、closed root、focus、serialization、custom element registryの実装差
• 未完了WPTの個別実行結果、HTML-AAMのplatform mapping、支援技術、互換性、Expert-gap Review

このページは初期Coverageです。仕様上の入口を整理したものであり、すべてのブラウザー、DOM操作、custom element、Shadow DOM構成、支援技術で同じ結果になることを主張しません。

Related surface

初心者向けのひな形、content、cloneの使い方はYugienのtemplate要素ページを参照してください。scriptによるDOM操作はscript要素、slotとshadow treeはDeclarative Shadow DOMの実装確認で併せて扱います。