dom.spec.whatwg.orgDOM Standard

DOM Living Standard — Last Updated 22 April 2024 Participate: GitHub whatwg/dom ( new issue , open issues ) Chat on Matrix Commits: GitHub whatwg/dom/commits Snapshot as of this commit @thedomstandard Tests: web-platform-tests dom/ ( ongoing work ) Translations (non-normative) : 日本語 Abstract DOM defines a platform-neutral model for events, aborting activities, and node trees. Table of Contents 1 Infrastructure 1.1 Trees 1.2 Ordered sets 1.3 Selectors 1.4 Namespaces 2 Events 2.1 Introduction to "DOM Events" 2.2 Interface Event 2.3 Legacy extensions to the Window interface 2.4 Interface CustomEvent 2.5 Constructing events 2.6 Defining event interfaces 2.7 Interface EventTarget 2.8 Observing event listeners 2.9 Dispatching events 2.10 Firing events 2.11 Action versus occurrence 3 Aborting ongoing activities 3.1 Interface AbortController 3.2 Interface AbortSignal 3.2.1 Garbage collection 3.3 Using AbortController and AbortSignal objects in APIs 4 Nodes 4.1 Introduction to "The DOM" 4.2 Node tree 4.2.1 Document tree 4.2.2 Shadow tree 4.2.2.1 Slots 4.2.2.2 Slottables 4.2.2.3 Finding slots and slottables 4.2.2.4 Assigning slottables and slots 4.2.2.5 Signaling slot change 4.2.3 Mutation algorithms 4.2.4 Mixin NonElementParentNode 4.2.5 Mixin DocumentOrShadowRoot 4.2.6 Mixin ParentNode 4.2.7 Mixin NonDocumentTypeChildNode 4.2.8 Mixin ChildNode 4.2.9 Mixin Slottable 4.2.10 Old-style collections: NodeList and HTMLCollection 4.2.10.1 Interface NodeList 4.2.10.2 Interface HTMLCollection 4.3 Mutation observers 4.3.1 Interface MutationObserver 4.3.2 Queuing a mutation record 4.3.3 Interface MutationRecord 4.4 Interface Node 4.5 Interface Document 4.5.1 Interface DOMImplementation 4.6 Interface DocumentType 4.7 Interface DocumentFragment 4.8 Interface ShadowRoot 4.9 Interface Element 4.9.1 Interface NamedNodeMap 4.9.2 Interface Attr 4.10 Interface CharacterData 4.11 Interface Text 4.12 Interface CDATASection 4.13 Interface ProcessingInstruction 4.14 Interface Comment 5 Ranges 5.1 Introduction to "DOM Ranges" 5.2 Boundary points 5.3 Interface AbstractRange 5.4 Interface StaticRange 5.5 Interface Range 6 Traversal 6.1 Interface NodeIterator 6.2 Interface TreeWalker 6.3 Interface NodeFilter 7 Sets 7.1 Interface DOMTokenList 8 XPath 8.1 Interface XPathResult 8.2 Interface XPathExpression 8.3 Mixin XPathEvaluatorBase 8.4 Interface XPathEvaluator 9 XSLT 9.1 Interface XSLTProcessor 10 Security and privacy considerations 11 Historical Acknowledgments Intellectual property rights Index Terms defined by this specification Terms defined by reference References Normative References Informative References IDL Index 1. Infrastructure This specification depends on the Infra Standard. [INFRA] Some of the terms used in this specification are defined in Encoding , Selectors , Trusted Types , Web IDL , XML , and Namespaces in XML . [ENCODING] [SELECTORS4] [TRUSTED-TYPES] [WEBIDL] [XML] [XML-NAMES] When extensions are needed, the can be updated accordingly, or a new standard can be written that hooks into the provided extensibility hooks for applicable specifications . 1.1. Trees A tree is a finite hierarchical tree structure. In tree order is preorder, depth-first traversal of a tree . An object that participates in a tree has a parent , which is either null or an object, and has children , which is an ordered set of objects. An object A whose parent is object B is a child of B . The root of an object is itself, if its parent is null, or else it is the root of its parent . The root of a tree is any object participating in that tree whose parent is null. An object A is called a descendant of an object B , if either A is a child of B or A is a child of an object C that is a descendant of B . An inclusive descendant is an object or one of its descendants . An object A is called an ancestor of an object B if and only if B is a descendant of A . An inclusive ancestor is an object or one of its ancestors . An object A is called a sibling of an object B , if and only if B and A share the same non-null parent . An inclusive sibling is an object or one of its siblings . An object A is preceding an object B if A and B are in the same tree and A comes before B in tree order . An object A is following an object B if A and B are in the same tree and A comes after B in tree order . The first child of an object is its first child or null if it has no children . The last child of an object is its last child or null if it has no children . The previous sibling of an object is its first preceding sibling or null if it has no preceding sibling . The next sibling of an object is its first following sibling or null if it has no following sibling . The index of an object is its number of preceding siblings , or 0 if it has none. 1.2. Ordered sets The ordered set parser takes a string input and then runs these steps: Let inputTokens be the result of splitting input on ASCII whitespace . Let tokens be a new ordered set . For each token in inputTokens , append token to tokens . Return tokens . The ordered set serializer takes a set and returns the concatenation of set using U+0020 SPACE. 1.3. Selectors To scope-match a selectors string selectors against a node , run these steps: Let s be the result of parse a selector selectors . [SELECTORS4] If s is failure, then throw a " SyntaxError " DOMException . Return the result of match a selector against a tree with s and node ’s root using scoping root node . [SELECTORS4] . Support for namespaces within selectors is not planned and will not be added. 1.4. Namespaces To validate a qualifiedName , throw an " InvalidCharacterError " DOMException if qualifiedName does not match the QName production. To validate and extract a namespace and qualifiedName , run these steps: If namespace is the empty string, then set it to null. Validate qualifiedName . Let prefix be null. Let localName be qualifiedName . If qualifiedName contains a U+003A (:), then: Let splitResult be the result of running strictly split given qualifiedName and U+003A (:). Set prefix to splitResult [0]. Set localName to splitResult [1]. If prefix is non-null and namespace is null, then throw a " NamespaceError " DOMException . If prefix is " xml " and namespace is not the XML namespace , then throw a " NamespaceError " DOMException . If either qualifiedName or prefix is " xmlns " and namespace is not the XMLNS namespace , then throw a " NamespaceError " DOMException . If namespace is the XMLNS namespace and neither qualifiedName nor prefix is " xmlns ", then throw a " NamespaceError " DOMException . Return namespace , prefix , and localName . 2. Events 2.1. Introduction to "DOM Events" Throughout the web platform events are dispatched to objects to signal an occurrence, such as network activity or user interaction. These objects implement the EventTarget interface and can therefore add event listeners to observe events by calling addEventListener() : obj . addEventListener ( "load" , imgFetched ) function imgFetched ( ev ) { // great success … } Event listeners can be removed by utilizing the removeEventListener() method, passing the same arguments. Alternatively, event listeners can be removed by passing an AbortSignal to addEventListener() and calling abort() on the controller owning the signal. Events are objects too and implement the Event interface (or a derived interface). In the example above ev is the event . ev is passed as an argument to the event listener ’s callback (typically a JavaScript Function as shown above). Event listeners key off the event ’s type attribute value (" load " in the above example). The event ’s target attribute value returns the object to which the event was dispatched ( obj above). Although events are typically dispatched by the user agent as the result of user interaction or the completion of some task, applications can dispatch events themselves by using what are commonly known as synthetic events: // add an appropriate event listener obj . addEventListener (...