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 objetHTMLHtmlElement
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. -
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 objetsCSSStyleSheet
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
, etunloaded
.
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.
-
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 valeurselectedStyleSheetSet
. 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'objetsDOMString
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
ouDOMString
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
Compatibilité des navigateurs
BCD tables only load in the browser