Document

L'interface Document représente n'importe quelle page web chargée dans le navigateur et sert de point d'entrée pour accéder au contenu de la page qui est formé par l'arbre du DOM.

L'arbre du DOM inclut les éléments tels que <body>, <table> et tous les autres présents dans la page. Il fournit des fonctionnalités à l'ensemble du document et permet, par exemple, d'obtenir l'URL de la page et de créer de nouveaux éléments dans le document.

L'interface Document décrit les propriétés et méthodes communes à toutes sortes de documents. Selon le type de document (par exemple HTML, XML, SVG, etc.), une API plus grande pourra être disponible. Ainsi, les documents HTML, servis avec le type de contenu text/html implémenteront également l'interface HTMLDocument tandis que les documents XML et SVG implémenteront l'interface XMLDocument.

Constructeur

Document(): Crée un nouvel objet Document.

Propriétés

Cette interface hérite également des interfaces Node et EventTarget.

Document.activeElement Lecture seule: Renvoie l'objet Element correspondant à l'élément qui possède le focus.
Document.body: Renvoie le nœud <body> ou <frameset> du document courant.
Document.characterSet Lecture seule: Renvoie le jeu de caractères utilisé par le document.
Document.childElementCount Lecture seule: Renvoie le nombre d'éléments enfants pour le document courant.
Document.children Lecture seule: Renvoie les éléments enfants pour le document courant.
Document.compatMode Expérimental Lecture seule: Indique si le document est rendu à l'écran selon le mode quirks ou strict.
Document.contentType Expérimental Lecture seule: Renvoie le type MIME du document courant.
Document.currentScript Lecture seule: Renvoie l'élément <script> dont le script est actuellement en cours de traitement et qui n'est pas un module JavaScript.
Document.doctype Lecture seule: Renvoie la définition du type de document (Document Type Definition ou DTD) du document courant.
Document.documentElement Lecture seule: Renvoie l'objet Element correspondant à l'élément qui est un enfant direct du document. Pour les documents HTML, il s'agit normalement d'un objet HTMLHtmlElement qui représente l'élément <html> du document.
Document.documentURI Lecture seule: Renvoie l'emplacement du document sous la forme d'une chaîne de caractères.
Document.embeds Lecture seule: Renvoie un objet HTMLCollection des éléments embarqués (via <embed>) dans le document.
Document.firstElementChild Lecture seule: Renvoie le premier élément enfant du document courant.
Document.fonts: Renvoie l'interface FontFaceSet pour le document courant.
Document.forms Lecture seule: Renvoie un objet HTMLCollection des éléments <form> du document.
Document.fullscreenElement Lecture seule: Renvoie l'élément actuellement en mode plein écran pour ce document.
Document.head Lecture seule: Renvoie l'élément <head> pour le document courant.
Document.hidden Lecture seule: Renvoie une valeur booléenne qui indique si la page est considérée masquée ou non.
Document.images Lecture seule: Renvoie un objet HTMLCollection des images du document.
Document.implementation Lecture seule: Renvoie l'implémentation du DOM associée au document courant.
Document.lastElementChild Lecture seule: Renvoie le dernier élément enfant du document courant.
Document.links Lecture seule: Renvoie un objet HTMLCollection contenant l'ensemble des hyperliens du document.
Document.mozSyntheticDocument Non standard: Renvoie true uniquement si le document est synthétique (par exemple une page indépendante, un fichier audio ou vidéo).
Document.pictureInPictureElement Lecture seule: Renvoie l'objet Element pour l'élément affiché en mode d'incrustation vidéo (picture-in-picture) pour ce document.
Document.pictureInPictureEnabled Lecture seule: Renvoie true si la fonctionnalité d'incrustation vidéo est activée.
Document.plugins Lecture seule: Renvoie un objet HTMLCollection contenant les plugins disponibles.
Document.pointerLockElement Lecture seule: Renvoie l'élément définit comme cible pour les évènements de souris pendant que le pointeur est verrouillé. Cette propriété vaut null si le verrouillage est en cours, si le pointeur est déverrouillé ou si la cible est située dans un autre document.
Document.featurePolicy Expérimental Lecture seule: Renvoie l'interface FeaturePolicy qui fournit une API pour l'introspection des règles de fonctionnalité (feature policies) appliquées au document.
Document.scripts Lecture seule: Renvoie un objet HTMLCollection contenant les éléments <script> du document.
Document.scrollingElement Lecture seule: Renvoie une référence à l'objet Element correspondant à l'élément qui fait défiler le document.
Document.styleSheets Lecture seule: Renvoie un objet StyleSheetList contenant les objets CSSStyleSheet pour les feuilles de style CSS liées explicitement ou embarquées dans le document.
Document.timeline Expérimental Lecture seule: Renvoie la chronologie, sous la forme d'une instance DocumentTimeline, qui est automatiquement créée au chargement de la page.
Document.visibilityState Lecture seule: Renvoie une chaîne de caractères qui indique l'état de visibilité du document. Les valeurs possibles sont visible, hidden, prerender, et unloaded.

Extensions pour `HTMLDocument`

L'interface Document pour les documents HTML hérite de l'interface HTMLDocument. Depuis HTML5, ce n'est plus un héritage mais une extension de l'interface pour ces documents.

Document.cookie: Renvoie une liste, dont les éléments sont séparés par des points-virgules, des cookies du document ou permet de définir un cookie.
Document.defaultView Lecture seule: Renvoie une référence à l'objet de la fenêtre.
Document.designMode: Permet d'accéder ou de définir la possibilité d'éditer l'ensemble du document.
Document.dir: Permet d'accéder ou de définir la directionnalité (écriture de droite à gauche ou de gauche à droite) du document.
Document.domain Obsolète: Permet d'accéder ou de définir le domaine du document courant.
Document.lastModified Lecture seule: Renvoie la date à laquelle le document a été modifié pour la dernière fois.
Document.location Lecture seule: Renvoie l'URI du document courant.
Document.readyState Lecture seule: Renvoie l'état de chargement du document.
Document.referrer Lecture seule: Renvoie l'URI de la page qui a lié vers cette page.
Document.title: Permet d'accéder ou de définir le titre du document courant.
Document.URL Lecture seule: Renvoie l'emplacement du document sous la forme d'une chaîne de caractères.

Gestionnaires d'évènement

L'interface Document est étendue avec des gestionnaires d'évènement supplémentaires définis dans l'interface GlobalEventHandlers.

GlobalEventHandlers.onselectionchange Expérimental: Un gestionnaire d'évènement qui représente le code à appeler lorsque l'évènement selectionchange est déclenché.

Propriétés dépréciées

Document.alinkColor Obsolète: Permet d'accéder ou de définir la couleur des liens actifs pour le corps du document.
Document.all Obsolète Non standard: Fournit un accès à tous les éléments du document. Elle renvoie un objet HTMLAllCollection dont la racine est le nœud du document. Il s'agit d'une propriété historique non-standard qui ne devrait pas être utilisée.
Document.anchors Obsolète Lecture seule: Renvoie une liste de toutes les ancres du document.
Document.applets Obsolète Lecture seule: Renvoie une liste ordonnée des applets contenus dans le document.
Document.bgColor Obsolète: Permet d'accéder ou de définir la couleur d'arrière-plan du document courant.
Document.charset Obsolète Lecture seule: Un synonyme de Document.characterSet, cette dernière devrait être utilisée à la place.
Document.fgColor Obsolète: Permet d'accéder ou de définir la couleur de premier plan ou la couleur du texte du document courant.
Document.fullscreen Obsolète: true lorsque le document est en mode plein écran.
Document.height Non standard Obsolète: Permet d'accéder ou de définir la hauteur du document courant.
Document.inputEncoding Obsolète Lecture seule: Un synonyme de Document.characterSet, cette dernière devrait être utilisée à la place.
Document.lastStyleSheetSet Obsolète Lecture seule: Renvoie le nom de la feuille de styles qui a été activée en dernière. Vaut null jusqu'à ce que la feuille de style soit changée avec la définition de la valeur selectedStyleSheetSet.
Document.linkColor Obsolète: Permet d'accéder ou de définir la couleur des hyperliens contenus dans le document.
Document.preferredStyleSheetSet Obsolète Lecture seule: Renvoie l'ensemble de feuilles de styles préféré comme indiqué par l'autrice ou l'auteur de la page.
Document.rootElement Obsolète: Agit comme Document.documentElement, mais uniquement pour les éléments racines <svg>. C'est cette dernière qu'il faudra utiliser à la place.
Document.selectedStyleSheetSet Obsolète: Renvoie l'ensemble de feuilles de styles actuellement utilisé.
Document.styleSheetSets Obsolète Lecture seule: Renvoie une liste des ensembles de feuilles de styles disponibles sur le document.
Document.vlinkColor Obsolète: Permet d'accéder ou de définir la couleur des hyperliens visités.
Document.width Non standard Obsolète: Renvoie la largeur du document courant.
Document.xmlEncoding Obsolète: Renvoie l'encodage tel que déterminé par la déclaration XML.
Document.xmlStandalone Obsolète: Renvoie true si la déclaration XML indique que le document est autonome (par exemple qu'une partie externe du DTD affecte le contenu du document), false sinon.
Document.xmlVersion Obsolète: Renvoie le numéro de version tel qu'indiqué dans la déclaration XML, ou 1.0 si la déclaration est absente.

Méthodes

Cette interface hérite également des méthodes des interfaces Node et EventTarget interfaces.

Document.adoptNode(): Adopte un nœud d'un document externe.
Document.append(): Insère un ensemble d'objets Node ou d'objets DOMString après le dernier enfant du document.
Document.captureEvents() Obsolète: Voir Window.captureEvents.
Document.caretPositionFromPoint(): Renvoie un objet CaretPosition qui contient le nœud DOM contenant le curseur et le décalage du curseur au sein de ce nœud.
Document.caretRangeFromPoint() Non standard: Obtient un objet Range pour le fragment de document situé aux coordonnées indiquées.
Document.createAttribute(): Crée un nouvel objet Attr et le renvoie.
Document.createAttributeNS(): Crée un nouveau nœud d'attribut dans un espace de noms donné et le renvoie.
Document.createCDATASection(): Crée un nouveau nœud CDATA et le renvoie.
Document.createComment(): Crée un nouveau nœud de commentaire et le renvoie.
Document.createDocumentFragment(): Crée un nouveau fragment de document.
Document.createElement(): Crée un nouvel élément avec le nom de balise indiqué.
Document.createElementNS(): Crée un nouvel élément avec le nom de balise indiqué et l'espace de noms passé via un URI.
Document.createEntityReference() Obsolète: Crée un nouvel objet de référence d'entité et le renvoie.
Document.createEvent(): Crée un objet d'évènement.
Document.createNodeIterator(): Crée un objet NodeIterator.
Document.createProcessingInstruction(): Crée un nouvel objet ProcessingInstruction.
Document.createRange(): Crée un objet Range.
Document.createTextNode(): Crée un nœud texte.
Document.createTouch() Obsolète: Crée un objet Touch.
Document.createTouchList() Obsolète: Crée un objet TouchList.
Document.createTreeWalker(): Crée un objet TreeWalker.
Document.elementFromPoint(): Renvoie l'élément situé le plus en haut pour les coordonnées indiquées.
Document.elementsFromPoint(): Renvoie un tableau de tous les éléments situés aux coordonnées indiquées.
Document.enableStyleSheetsForSet() Obsolète: Active les feuilles de styles pour l'ensemble de feuilles de styles indiqué.
Document.exitPictureInPicture(): Retire la vidéo de la fenêtre d'incrustation vidéo pour la replacer dans son conteneur original.
Document.exitPointerLock() Expérimental: Relâche le verrou du pointeur.
Document.getAnimations(): Renvoie un tableau contenant tous les objets Animation actuellement actifs et dont les éléments cibles sont des descendants du document courant.
Document.getBoxQuads() Expérimental: Renvoie une liste d'objets DOMQuad qui représente les fragments CSS du nœud.
Document.getElementById(): Renvoie une référence objet vers l'élément identifié.
Document.getElementsByClassName(): Renvoie une liste d'éléments avec le nom de classe indiqué.
Document.getElementsByTagName(): Renvoie une liste d'éléments avec la balise indiquée.
Document.getElementsByTagNameNS(): Renvoie une liste d'éléments avec le nom de balise et pour l'espace de noms indiqués.
Document.getSelection(): Renvoie un objet Selection qui représente la portion de texte sélectionnée par l'utilisatrice ou l'utilisateur, ou la position du curseur.
Document.hasStorageAccess() Expérimental: Renvoie un objet Promise qui est résolu avec une valeur booléenne selon que le document a accès à du stockage de premier rang.
Document.importNode(): Renvoie un clone d'un nœud d'un document externe.
Document.normalizeDocument() Obsolète: Remplace les entités et normalise les nœuds textuels, etc.
Document.prepend(): Insère un ensemble d'objet Node ou DOMString avant le premier enfant du document.
Document.querySelector(): Renvoie le premier nœud Element au sein du document, selon l'ordre du document, qui correspond aux sélecteurs indiqués.
Document.querySelectorAll(): Renvoie une liste de tous les nœuds Element du document qui correspondent aux sélecteurs indiqués.
Document.releaseCapture() Non standard: Relâche la capture de la souris si celle-ci est sur un élément du document courant.
Document.releaseEvents() Non standard Obsolète: Voir Window.releaseEvents().
Document.replaceChildren(): Remplace l'enfant existant du document avec un ensemble de nouveaux enfants indiqué.
Document.requestStorageAccess(): Renvoie un objet Promise qui est résolu si l'accès au stockage de premier rang a été accordé et qui est rompu si l'accès a été refusé.
Document.mozSetImageElement() Non standard: Permet de changer l'élément utilisé comme image d'arrière-plan par un élément dont on passe l'identifiant en argument.

L'interface Document est étendue avec l'interface XPathEvaluator :

Document.createExpression(): Compile une expression XPathExpression qui peut ensuite être utilisée pour des évaluations (répétées).
Document.createNSResolver(): Crée un objet XPathNSResolver.
Document.evaluate(): Évalue une expression XPath.

Extension pour les documents HTML

Pour les documents HTML, l'interface Document hérite de HTMLDocument. Depuis HTML5, ce n'est plus un héritage mais une extension de l'interface pour ces documents.

Document.clear() Non standard Obsolète: Pour la majorité des navigateurs récents, y compris pour les versions récentes de Firefox et d'Internet Explorer, cette méthode ne fait rien.
Document.close(): Ferme le flux d'écriture sur un document.
Document.execCommand() Obsolète: Pour un document éditable, exécute une commande de formatage.
Document.getElementsByName(): Renvoie une liste des éléments avec le nom indiqué.
Document.hasFocus(): Renvoie true si le focus est situé à l'intérieur du document indiqué.
Document.open(): Ouvre le flux d'écriture sur un document.
Document.queryCommandEnabled() Obsolète: Renvoie true si la commande de formatage peut être exécutée sur l'intervalle indiqué.
Document.queryCommandIndeterm() Obsolète: Renvoie true si la commande de formatage est dans un état indéterminé pour l'intervalle courant.
Document.queryCommandState() Obsolète: Renvoie true si la commande de formatage a été exécutée sur l'intervalle courant.
Document.queryCommandSupported() Obsolète: Renvoie true si la commande de formatage est prise en charge sur l'intervalle courant.
Document.queryCommandValue() Obsolète: Renvoie la valeur de l'intervalle courant pour une commande de formatage.
Document.write(): Écrit du texte dans un document.
Document.writeln(): Écrit une ligne de texte dans un document.

Évènements

L'écoute de ces évènements peut être effectuée avec addEventListener() ou en affectant un gestionnaire d'évènement à la propriété on<nomdevenement> correspondante à cette interface.

afterscriptexecute Non standard: Déclenché lorsqu'un élément statique <script> finit d'exécuter son script.
beforescriptexecute Non standard: Déclenché lorsqu'un élément statique <script> est sur le point de commencer son exécution.
scroll: Déclenché lorsque la vue du document ou d'un élément a défilé. Également disponible avec la propriété onscroll.
visibilitychange: Déclenché lorsque le contenu d'un onglet est devenu visible ou lorsqu'il a été masqué.
wheel: Déclenché lorsque la personne utilise la roulette d'un appareil de pointage (généralement une souris). Également disponible avec la propriété onwheel.

Évènements liés aux animations

animationcancel: Déclenché lorsqu'une animation est interrompue de façon inattendue. Également disponible avec la propriété onanimationcancel.
animationend: Déclenché lorsqu'une animation s'est terminée normalement. Également disponible avec la propriété onanimationend.
animationiteration: Déclenché lorsqu'une itération d'une animation est terminée. Également disponible avec la propriété onanimationiteration.
animationstart: Déclenché au démarrage d'une animation. Également disponible avec la propriété onanimationstart.

Évènements liés au presse-papier

copy: Déclenché lorsqu'une personne initie une action de copie avec l'interface utilisateur du navigateur.
cut: Déclenché lorsque l'utilisateur initie une action de coupe avec l'interface utilisateur du navigateur.
paste: Déclenché lorsque l'utilisateur initie une action de colle avec l'interface utilisateur du navigateur.

Évènements pour le glisser-déposer

drag: Déclenché toutes les quelques centaines de millisecondes lorsqu'un élément ou une sélection de texte est glissée par l'utilisatrice ou l'utilisateur. Également disponible avec la propriété ondrag.
dragend: Déclenché lorsqu'une opération de glisser-déposer se termine (en relâchant un bouton de la souris ou en appuyant sur la touche Echap). Également disponible avec la propriété ondragend.
dragenter: Déclenché lorsqu'un élément ou une sélection de texte que l'on fait glisser rentre sur une zone de dépôt valide. Également disponible avec la propriété ondragenter.
dragleave: Déclenché lorsqu'un élément ou une sélection de texte que l'on fait glisser quitte une zone de dépôt valide. Également disponible avec la propriété ondragleave.
dragover: Déclenché lorsqu'un élément ou une sélection de texte que l'on fait glisser survole une zone de dépôt valide. Également disponible avec la propriété ondragover.
dragstart: Déclenché lorsqu'une personne commence à glisser un élément ou une sélection de texte. Également disponible avec la propriété ondragstart.
drop: Déclenché lorsqu'un élément ou une sélection de texte est déposée sur une zone de dépôt valide. Également disponible avec la propriété ondrop.

Évènements liés au mode plein écran

fullscreenchange: Déclenché lorsque le document rentre ou sort du mode plein écran.
fullscreenerror: Déclenché en cas d'erreur lors d'une tentative d'entrée ou de sortie du mode plein écran.

Évènements clavier

keydown: Déclenché lors de l'appui sur une touche. Également disponible avec la propriété onkeydown.
keypress Obsolète: Déclenché lors de l'appui sur une touche qui produit un caractère. Également disponible avec la propriété onkeypress.
keyup: Déclenché lors du relâchement d'une touche. Également disponible avec la propriété onkeyup.

Évènements de chargement et de déchargement

DOMContentLoaded: Déclenché lorsque le chargement et l'analyse (parsing) du document sont terminées, sans attendre la fin du chargement des feuilles de style, des images et des frames.
readystatechange: Déclenché lorsque l'attribut readyState a changé.

Évènements de pointeurs

gotpointercapture: Déclenché lorsqu'un élément capture un pointeur avec setPointerCapture(). Également disponible avec la propriété ongotpointercapture.
lostpointercapture: Déclenché lorsqu'un pointeur capturé est libéré. Également disponible avec la propriété onlostpointercapture.
pointercancel: Déclenché lorsqu'un évènement de pointeur est annulé. Également disponible avec la propriété onpointercancel.
pointerdown: Déclenché lorsqu'un pointeur devient actif. Également disponible avec la propriété onpointerdown.
pointerenter: Déclenché lorsqu'un pointeur est déplacé au sein des frontières de la zone interactive d'un élément ou d'un de ses descendants. Également disponible avec la propriété onpointerenter.
pointerleave: Déclenché lorsqu'un pointeur quitte les limites de la zone interactive d'un élément. Également disponible avec la propriété onpointerleave.
pointerlockchange: Déclenché lorsque le pointeur est verrouillé/déverrouillé. Également disponible avec la propriété onpointerlockchange.
pointerlockerror: Déclenché lorsque le verrouillage du pointeur échoue. Également disponible avec la propriété onpointerlockerror.
pointermove: Déclenché lorsqu'un pointeur change de coordonnées. Également disponible avec la propriété onpointermove.
pointerout: Déclenché lorsqu'un pointeur est déplacé en dehors des limites de la zone interactive d'un élément (entre autres). Également disponible avec la propriété onpointerout.
pointerover: Déclenché lorsqu'un pointeur est déplacé à l'intérieur des limites de la zone interactive d'un élément. Également disponible avec la propriété onpointerover.
pointerup: Déclenché lorsqu'un pointeur n'est plus actif. Également disponible avec la propriété onpointerup.

Évènements de sélection

selectionchange: Déclenché lorsque la sélection textuelle courante d'un document a changé. Également disponible avec la propriété onselectionchange.
selectstart: Déclenché lorsque l'utilisateur commence une nouvelle sélection. Également disponible avec la propriété onselectstart.

Évènements tactiles

touchcancel: Déclenché lorsqu'un ou plusieurs points de toucher ont été perturbés d'une façon propre à l'implémentation (par exemple lorsque de trop nombreux points de toucher ont été créés). Également disponible avec la propriété ontouchcancel.
touchend: Déclenché lorsqu'un ou plusieurs points de toucher ont été retirés de la surface tactile. Également disponible avec la propriété ontouchend.
touchmove: Déclenché lorsqu'un ou plusieurs points de toucher ont été déplacés sur la surface tactile. Également disponible avec la propriété ontouchmove.
touchstart: Déclenché lorsqu'un ou plusieurs points de toucher ont été placés sur la surface tactile. Également disponible avec la propriété ontouchstart.

Évènements de transition

transitioncancel: Déclenché lorsqu'une transition CSS est annulée. Également disponible avec la propriété ontransitioncancel.
transitionend: Déclenché lorsqu'une transition CSS est terminée. Également disponible avec la propriété ontransitionend.
transitionrun: Déclenché lorsqu'une transition CSS est créée. Également disponible avec la propriété ontransitionrun.
transitionstart: Déclenché lorsqu'une transition CSS a effectivement démarré. Également disponible avec la propriété ontransitionstart.

Extensions non-standard Non standard

Non standard: Cette fonctionnalité n'est ni standard, ni en voie de standardisation. Ne l'utilisez pas pour des sites accessibles sur le Web : elle ne fonctionnera pas pour tout utilisateur. Il peut également y avoir d'importantes incompatibilités entre les implémentations et son comportement peut être modifié dans le futur.

Notes relatives à Firefox

Firefox définit certaines méthodes non-standard :

Document.execCommandShowHelp() Obsolète: Cette méthode n'a jamais rien fait et a toujours levé une exception. Elle a été retirée avec Gecko 14.0.
Document.getBoxObjectFor() Obsolète: On utilisera la méthode Element.getBoundingClientRect() à la place.
Document.loadOverlay() Obsolète: Charge un overlay XUL de façon dynamique. Cette méthode fonctionne uniquement pour les documents XUL.
Document.queryCommandText() Obsolète: Cette méthode n'a jamais rien fait et a toujours levé une exception. Elle a été retirée avec Gecko 14.0.

Notes relatives à Internet Explorer

Microsoft définit certaines propriétés non-standard :

Document.fileSize* Non standard Obsolète: Renvoie la taille du document, exprimée en octets. Cette propriété n'est plus prise en charge à partir d'Internet Explorer 11.

Spécifications

Specification
DOM Standard # interface-document
HTML Standard # the-document-object
CSSOM View Module # extensions-to-the-document-interface
Pointer Lock 2.0 # extensions-to-the-document-interface
Selection API # extensions-to-document-interface

Compatibilité des navigateurs

BCD tables only load in the browser