[12] [[DOM]] において[DFN[[RUBYB[[[養子化]]]@en[adopt]]]]とは、ある[[節点]]の[[節点文書]] ([CODE(DOMa)@en[[[ownerDocument]]]]) をある[[文書]]に書き換える操作です。 この時[[節点]]の[[親]]がいればその[[親子]]関係は解消され、 [[節点]]の[[子節点]]その他付随する[[節点]]があればそれらの[[節点文書]]も新しい[[節点文書]]に書き換わります。 [13] [CODE(DOMi)@en[[[Document]]]] [[オブジェクト]]の [DFN[[CODE(DOMm)@en[[[adoptNode]]]]]] [[メソッド]]は、指定された[[節点]]を当該 [CODE(DOMi)@en[[[Document]]]] に [[adopt]] します。 ;; [14] [[adopt]] 操作は [CODE(DOMm)@en[[[adoptNode]]]] [[メソッド]]以外でも用いられます。 例えば [CODE(DOMm)@en[[[adoptChild]]]] は新しい[[子節点]]を[[親節点]]と同じ[[文書]]に移し、 既に[[親]]がいればその[[親子]]関係を解消するために [[adopt]] します。 * 仕様書 [REFS[ - '''[10] [CITE@en-US[DOM Standard]] ([TIME[2014-03-20 17:08:41 +09:00]] 版) ''' - [11] [CITE@en-US[DOM Standard]] ([TIME[2014-03-20 17:08:41 +09:00]] 版) - [24] [CITE@en-US-x-hixie[HTML Standard]] ([TIME[2014-04-03 03:44:44 +09:00]] 版) - [26] [CITE@en-US-x-hixie[HTML Standard]] ([TIME[2014-04-03 03:44:44 +09:00]] 版) ]REFS] * 養子化操作 [46] [[養子化]]では、次のような操作が行われます。 [FIG(list)[ - [47] [F[親][parentNode]]の消去 ★ - [48] [F[節点文書]]の書き換え - [49] [CODE(HTMLe)@en[img]] [[要素]]の読み込み - [51] [[カスタム要素コールバック反応]] [DFN[[CODE[adoptedCallback]]]] の実行 ]FIG] [50] 「★」のあるものは、当該[[節点]]のみに適用されます。 それ以外は、[[子孫]]、[[雛形内容]]および[[影木]]にも適用されます。 [15] ある[[節点]][VAR[節点]]のある[[文書]][VAR[新文書]]への[RUBYB[養子化]@en[adopt]]操作は、 次の処理で構成されます [SRC[>>10]]。 [FIG(steps)[ = [38] [VAR[旧文書]]を、[VAR[節点]]の[F[節点文書]]に設定します。 = [41] [VAR[節点]]の[F[親][parentNode]]が [[null]] 以外なら、 == [16] [VAR[節点]]の[F[親][parentNode]]から[VAR[節点]]を[[削除][removeChild]]します。 = [43] [VAR[旧文書]]と[VAR[新文書]]が異なるなら、 == [40] [VAR[節点]]の[[影を含む包括的子孫]]の各[F[節点文書]]を、[VAR[新文書]]に設定します。 == [54] [VAR[節点]]の[[影を含む包括的子孫]]の各[[要素]]の[F[属性リスト]]の各[[属性]]の[F[節点文書]]を、[VAR[新文書]]に設定します。 == [36] [VAR[節点]]の[[影を含む包括的子孫]]の各[[要素]][VAR[要素]]について、 === [44] [VAR[要素]]が[F[カスタム]]なら、 ==== [45] [VAR[要素]]を[[カスタム要素コールバック反応をキューに追加]]します。 [VAR[コールバック名]]は [CODE[adoptedCallback]], [VAR[引数リスト]]は[VAR[旧文書]]と[VAR[新文書]]の[[リスト]]とします。 == [17] [VAR[節点]]の[[影を含む包括的子孫]]の各[VAR[節点]]について、 [[影を含む木順]]に、 === [18] [VAR[節点]]と[VAR[旧文書]]に関する[[養子化手順群]]を実行します。 ]FIG] [19] [DFN[[RUBYB[養子化手順群]@en[adoption steps]]]] [SRC[>>10]] には、次のものがあります。 [FIG(list)[ - [25] [CODE(HTMLe)@en[[[img]]]] [[要素]]では、 [[update the image data]] やそれに相当する処理 [SRC[>>24]] - [9] [CODE(HTMLe)@en[[[template]]]] [[要素]]では、[[雛形内容]]の [[adopt]] [SRC[>>26]] ]FIG] [HISTORY[ [27] >>9 は [[adopting steps]] が導入される以前に規定されたため、>>33 まで 「[CODE(DOMa)@en[[[ownerDocument]]]]が変化した時」という表現になっていました。 [[adopt]] はそれ以外でも発生しますが、実質的には同じでした。 [28] >>32 以前の [[DOM Standard]] は [[adopt]] された[[節点]] ([[根]]) に対して [[adopting steps]] を呼ぶと言っていますが、 [[HTML Standard]] は変更が発生した[[節点]]すべてに対して [[adopting steps]] が呼ばれることを期待していて、齟齬がありました。 ]HISTORY] ;; [3] >>16 の[[削除]]操作内で [[removing steps]] も実行されます。 -*-*- [78] [[養子化]]は、その[[節点]]だけでなく[[子孫]]にまで影響が及びます。 [[影木]]があれば、そちらにも影響が及びます。 [79] [[養子化]]の時点で[F[親]]があれば、[[削除]] (親子関係が解消) されます。 従って[[養子化]]の影響は ([[子]]の[[削除]]を除き) [[祖先]]には及びません。 [76] [CODE[DocumentFragment]] は[F[ホスト]]を持つ場合には、 同時にのみ[[養子化]]されることになっています。 [55] [[影根]]を [CODE[adoptNode]] (>>72) や [CODE[importNode]] に引き渡すと、 [[例外]]を[[投げ]]ることになっています。その他[[養子化]]が呼び出される場面では、 [[影根]]が(単独で)[[養子化]]されることはありません。 ;; [77] よって[[影根]]は常に[[影ホスト]]と同じ[[文書]]に属します。 -*-*- [80] [[養子化]]は、 - [[節点の挿入]] - [CODE[adoptNode]] から呼び出されます。 * [CODE(DOMi)@en[Document]] インターフェイス [CODE(DOMm)@en[adoptNode]] メソッド (DOM) [20] [CODE[Document]] [[オブジェクト]]の [DFN[[CODE(DOMm)@en[adoptNode]]]] [[メソッド]]は、 指定した[[節点]]をその[[文書]]へと[[養子化]]します。 [SRC[>>11]] [21] 具体的には、次のようにしなければ[MUST[なりません]] [SRC[>>11]]。 [FIG(steps)[ = [63] [VAR[文書]]を、[[文脈オブジェクト]]に設定します。 = [64] [VAR[節点]]を、第1引数を [CODE[Node]] として解釈した結果に設定します。 = [22] [CODE[CEReactions]]: == [62] [VAR[節点]]の[F[節点型]]が[[文書]]の場合、 === [65] [CODE[NotSupportedError]] [CODE[DOMException]] を[[投げ]]、 ここで停止します。 == [66] [VAR[節点]]が[[影根]]の場合、 === [67] [CODE[HierarchyRequestError]] [CODE[DOMException]] を[[投げ]]、 ここで停止します。 == [68] [VAR[節点]]が [CODE[DocumentFragment]] で、 [VAR[節点]]の[F[ホスト]]が [CODE[null]] で''ない''場合、 === [69] [VAR[節点]]を返し [SRC[仕様書になし]]、 ここで停止します。 == [70] [VAR[節点]]を[[文書]]に[[養子化]]します。 == [71] [VAR[節点]]を返します。 ]FIG] [72] つまり[[引数]]の[[節点]]を[[養子化]]するのですが、 [CODE[DocumentFragment]] のとき特殊な挙動になります。 [CODE[DocumentFragment]] は3種類ありますが、そのうち2種類は[F[ホスト]]があります。 [F[ホスト]]がある [CODE[DocumentFragment]] は、 [F[ホスト]]と同時にのみ[[養子化]]できます [SRC[>>58]] (>>76)。 [[例外]]を返したり何もしなかったりするのは、[[後方互換性]]のためとされます [SRC[>>58]]。 この処理は[TIME[令和元(2019)年][2019]]の改正で明文化されました [SRC[>>56]] が、 それ以前の [[Webブラウザー]]の処理は曖昧でした。 ;; [73] そのときの修正ミスで何も返さないケースが生じていますが (>>69)、 [[Chrome]] では常に[VAR[節点]]が返されるようです。 [74] この[[メソッド]]は常に[[引数]]をそのまま返します。つまりあまり意味はありません。 [[chaining]] の便宜とも思われますが、 [[DOM]] にはそういうのはあまりないので、 どうなのでしょう。 ([CODE[appendChild]] に近いパターンなので、やはりそうなのかもしれませんが。) ;; [75] [[DOM3]] は[[文書]]が異なる[[DOM実装]]に属することも想定しているので、 もしかすると[[引数]]と[[返値]]が違うケースがあったのかもしれません。 しかし [[DOM3]] はそのへんのアーキテクチャーをあまりはっきり語っていなかったので、 その場合に[[引数]]の[[節点]]オブジェクトはその後どうなってしまうのかなど、 謎が多いです。 -*-*- [23] [CODE[adoptNode]] [[メソッド]]は、 [[DOM3]] で追加されたものでした。 [[DOM3]] 仕様上は明示的に [CODE(DOMm)@en[[[adoptNode]]]] を呼ばなければ [CODE(DOMm)@en[[[adoptChild]]]] などで違う[[文書]]に挿入することができませんでした。 [61] しかし現実の [[Webブラウザー]]は当時から自動的に [[adopt]] する実装にほぼなっていました。 現在の [CITE[[[DOM Standard]]]] はそちらの動作を採用しているため、 この[[メソッド]]が必要になる場面はほとんどありません。 * 歴史 [1] [CITE[[dom3core] Cross-document appending of nodes from Anne van Kesteren on 2006-08-24 (www-dom@w3.org from July to September 2006)]] ([[名無しさん]] [WEAK[2006-09-10 04:25:33 +00:00]]) [2] [[原始文書]]と[[対象文書]]が同じ場合に [CODE(DOMi)@en[[[UserDataHandler]]]] があれば呼ばれるのかどうか、 [[メソッド]]の返す値は何かは明記されていません。 [4] [CODE(DOMi)@en[[[UserDataHandler]]]] が呼ばれるタイミングは明記されていません。 (複数の[[節点]]が同時に[[養子縁組]]されるとき、 すべての[[節点]]が[[養子縁組]]し終えてから呼ばれるのか? どの順番で呼ばれるのか?) ([[名無しさん]]) [5] [CODE(DOMi)@en[[[Document]]]] や [CODE(DOMi)@en[[[DocumentType]]]] を[[養子縁組]]しようとすると [CODE(DOMc)@en[[[NOT_SUPPORTED_ERR]]]] ですが、 [CODE(DOMi)@en[[[Entity]]]] や [CODE(DOMi)@en[[[Notation]]]] だとどうなるのかは不明です。 [6] [CITE@en[Re: ''''''[''''''dom'''''']'''''' Need to describe the interaction of adoptNode with prototype chains]] ( ([[Boris Zbarsky]] 著, [TIME[2013-01-17 01:27:26 +09:00]] 版)) [7] [CITE@en[Web Applications 1.0 r8270 Share the ownerDocument of template contents amongst the templates of a document.]] ( ([TIME[2013-11-13 06:36:00 +09:00]] 版)) [8] [CITE[Index of /~stewart/css/html-options]] ([TIME[2010-03-04 09:46:12 +09:00]] 版) [REFS[ - [29] [CITE[Make the adopt hook more generic. https://www.w3.org/Bugs/Public/show_bu... · e50fd71 · whatwg/dom]] ( ([TIME[2014-04-11 23:02:31 +09:00]] 版)) - [30] [CITE@en[Web Applications 1.0 r8509 Make reload if inserting it into a new doc causes the URL to change (note that exactly what this does depends on whether the browser's 'list of available images' is maintained per-Doc, or whether there's only one list per origin)]] ([TIME[2014-02-25 07:53:00 +09:00]] 版) ]REFS] [31] [[adopting steps]] は[[要素の基底URL]]の処理の一般化として >>29 で導入されました。 [REFS[ - [32] [CITE@en[Close #66: run the adopting steps recursively · whatwg/dom@5697cf4]] ([TIME[2015-09-08 19:43:43 +09:00]] 版) - [33] [CITE@en[Close #103: use "adopting steps" from DOM and add ID · whatwg/html@a9890f1]] ([TIME[2015-09-08 19:50:25 +09:00]] 版) ]REFS] [34] [CITE@en[Make two loops to adopt a node · whatwg/dom@718ba4a]] ([TIME[2015-09-22 11:04:25 +09:00]] 版) [35] [CITE@en[Fix #146: only run adopting steps when changing documents · whatwg/dom@bb69d0b]] ([TIME[2016-01-30 21:05:15 +09:00]] 版) [37] [CITE@en[Add ''''''[''''''CEReactions'''''']'''''' annotations to mutating methods · whatwg/dom@3cd02d1]] ([TIME[2016-04-26 19:07:48 +09:00]] 版) [39] [CITE@en[Un-customify adopted elements]] ( ([[domenic]]著, [TIME[2016-06-01 20:24:12 +09:00]])) [42] [CITE@en[Set the stage for new custom element adoption semantics]] ([[domenic]]著, [TIME[2016-07-21 18:25:26 +09:00]]) [52] [CITE@en[Pass the old and new document to adoptedCallback]] ([[domenic]]著, [TIME[2016-08-16 16:50:20 +09:00]]) [53] [CITE@en[Make Attr inherit from Node again]] ([[annevk]]著, [TIME[2016-08-19 21:44:07 +09:00]]) - [56] [CITE@en[Run adopt as part of insert]], [[annevk]], [TIME[2019-12-11 17:56:04 +09:00]], [TIME[2023-12-03T05:29:05.000Z]] - [57] [CITE@en[Adoption and DocumentFragment by annevk · Pull Request #16348 · web-platform-tests/wpt · GitHub]], [TIME[2023-12-03T05:29:19.000Z]] - [58] [CITE@en[Don't allow adopting DocumentFragment of a template element · Issue #744 · whatwg/dom · GitHub]], [TIME[2023-12-03T05:29:28.000Z]] - [59] [CITE@en[Run adopt as part of insert by annevk · Pull Request #754 · whatwg/dom · GitHub]], [TIME[2023-12-03T05:29:41.000Z]] [60] >>56 [CODE[DocumentFragment]] の扱いが修正されました。