養子化 (DOM)

[12] DOM において養子化 (adopt) とは、ある節点の節点文書 (ownerDocument) をある文書に書き換える操作です。この時節点の親がいればその親子関係は解消され、節点の子節点その他付随する節点があればそれらの節点文書も新しい節点文書に書き換わります。

[13] Document オブジェクトの adoptNode メソッドは、指定された節点を当該 Document に adopt します。

[14] adopt 操作は adoptNode メソッド以外でも用いられます。例えば adoptChild は新しい子節点を親節点と同じ文書に移し、既に親がいればその親子関係を解消するために adopt します。

仕様書

養子化操作

[46] 養子化では、次のような操作が行われます。

[47] 親の消去 ★
[48] 節点文書の書き換え
[49] img 要素の読み込み
[51] カスタム要素コールバック反応 adoptedCallback の実行

[50] 「★」のあるものは、当該節点のみに適用されます。それ以外は、子孫、雛形内容および影木にも適用されます。

[15] ある節点節点のある文書新文書への養子化 (adopt) 操作は、次の処理で構成されます >>10。

[38] 旧文書を、節点の節点文書に設定します。
[41] 節点の親が null 以外なら、
1. [16] 節点の親から節点を削除します。
[43] 旧文書と新文書が異なるなら、
1. [40] 節点の影を含む包括的子孫の各節点文書を、新文書に設定します。
2. [54] 節点の影を含む包括的子孫の各要素の属性リストの各属性の節点文書を、新文書に設定します。
3. [36] 節点の影を含む包括的子孫の各要素要素について、
  1. [44] 要素がカスタムなら、
    1. [45] 要素をカスタム要素コールバック反応をキューに追加します。 コールバック名は adoptedCallback, 引数リストは旧文書と新文書のリストとします。
4. [17] 節点の影を含む包括的子孫の各節点について、影を含む木順に、
  1. [18] 節点と旧文書に関する養子化手順群を実行します。

[19] 養子化手順群 (adoption steps) >>10 には、次のものがあります。

[25] img 要素では、 update the image data やそれに相当する処理 >>24
[9] template 要素では、雛形内容の adopt >>26

[27] >>9 は adopting steps が導入される以前に規定されたため、>>33 まで「ownerDocumentが変化した時」という表現になっていました。 adopt はそれ以外でも発生しますが、実質的には同じでした。

[28] >>32 以前の DOM Standard は adopt された節点 (根) に対して adopting steps を呼ぶと言っていますが、 HTML Standard は変更が発生した節点すべてに対して adopting steps が呼ばれることを期待していて、齟齬がありました。

[3] >>16 の削除操作内で removing steps も実行されます。

[78] 養子化は、その節点だけでなく子孫にまで影響が及びます。影木があれば、そちらにも影響が及びます。

[79] 養子化の時点で親があれば、削除 (親子関係が解消) されます。従って養子化の影響は (子の削除を除き) 祖先には及びません。

[76] DocumentFragment はホストを持つ場合には、同時にのみ養子化されることになっています。

[55] 影根を adoptNode (>>72) や importNode に引き渡すと、例外を投げることになっています。その他養子化が呼び出される場面では、影根が(単独で)養子化されることはありません。

[77] よって影根は常に影ホストと同じ文書に属します。

[80] 養子化は、

から呼び出されます。

`Document` インターフェイス `adoptNode` メソッド (DOM)

[20] Document オブジェクトの adoptNode メソッドは、指定した節点をその文書へと養子化します。 >>11

[21] 具体的には、次のようにしなければなりません >>11。

[63] 文書を、文脈オブジェクトに設定します。
[64] 節点を、第1引数を Node として解釈した結果に設定します。
[22] CEReactions:
1. [62] 節点の節点型が文書の場合、
  1. [65] NotSupportedError DOMException を投げ、ここで停止します。
2. [66] 節点が影根の場合、
  1. [67] HierarchyRequestError DOMException を投げ、ここで停止します。
3. [68] 節点が DocumentFragment で、 節点のホストが null でない場合、
  1. [69] 節点を返し仕様書になし、ここで停止します。
4. [70] 節点を文書に養子化します。
5. [71] 節点を返します。

[72] つまり引数の節点を養子化するのですが、 DocumentFragment のとき特殊な挙動になります。 DocumentFragment は3種類ありますが、そのうち2種類はホストがあります。ホストがある DocumentFragment は、ホストと同時にのみ養子化できます >>58 (>>76)。例外を返したり何もしなかったりするのは、後方互換性のためとされます >>58。この処理は令和元(2019)年の改正で明文化されました >>56 が、それ以前の Webブラウザーの処理は曖昧でした。

[73] そのときの修正ミスで何も返さないケースが生じていますが (>>69)、 Chrome では常に節点が返されるようです。

[74] このメソッドは常に引数をそのまま返します。つまりあまり意味はありません。 chaining の便宜とも思われますが、 DOM にはそういうのはあまりないので、どうなのでしょう。 (appendChild に近いパターンなので、やはりそうなのかもしれませんが。)

[75] DOM3 は文書が異なるDOM実装に属することも想定しているので、もしかすると引数と返値が違うケースがあったのかもしれません。しかし DOM3 はそのへんのアーキテクチャーをあまりはっきり語っていなかったので、その場合に引数の節点オブジェクトはその後どうなってしまうのかなど、謎が多いです。

[23] adoptNode メソッドは、 DOM3 で追加されたものでした。 DOM3 仕様上は明示的に adoptNode を呼ばなければ adoptChild などで違う文書に挿入することができませんでした。

[61] しかし現実の Webブラウザーは当時から自動的に adopt する実装にほぼなっていました。現在の DOM Standard はそちらの動作を採用しているため、このメソッドが必要になる場面はほとんどありません。