XML DOM - l'objet Range

L'objet Range représente une région continue dans le document.

l'objet Range

L'objet Range représente une région continue du document, telle que la région sélectionnée par l'utilisateur avec le curseur de la souris dans la fenêtre du navigateur.

Si une implémentation prend en charge le module Range, alors l'objet Documentdéfini méthode createRange()，en l'appelant, un nouveau objet Range peut être créé.

Remarque :IE a défini une méthode Document.createRange() incompatibles, l'objet retourné par laquelle est similaire à l'interface Range, mais incompatibles.

L'interface Range définit une grande quantité de méthodes pour définir la zone sélectionnée du document, en plus de plusieurs méthodes qui peuvent être utilisées pour effectuer des opérations de couper et coller dans la zone sélectionnée.

Les propriétés de l'interface Range fournissent des méthodes pour obtenir les nœuds de bord et l'offset de la portée. Ses méthodes fournissent des méthodes pour définir les limites de la portée. Notez que les limites de la portée peuvent être définies comme Document ou l'objet DocumentFragmentdes nœuds. Une fois que les points de bord de la portée sont définis, les opérations de couper, de copier et de coller peuvent être réalisées en utilisant les méthodes deleteContents(), extractContents(), cloneContents() et insertNode().

Lorsque le document est modifié par une opération d'insertion ou de suppression, tous les objets Range représentant une partie du document changeront (si nécessaire), de sorte que leurs points de bord restent valides et qu'ils représentent (autant que possible) le même contenu de document.

Terminologie : portée, point de bord et offset

Une portée a deux points de bord, à savoir un point de début et un point de fin. Chaque point de bord est spécifié par un nœud et l'offset de ce nœud. Ce nœud est généralement nœud Element、nœud Documentou nœud TextePour les nœuds Element et Document, l'offset fait référence aux sous-nœuds de ce nœud. Un offset de 0 signifie que le point de bord se trouve avant le premier sous-nœud de ce nœud. Un offset de 1 signifie que le point de bord se trouve après le premier sous-nœud de ce nœud, avant le deuxième sous-nœud. Mais si le nœud de bord est un nœud Texte, l'offset fait référence à la position entre deux caractères dans le texte.

Constantes de l'objet Range

Ces constantes spécifient la manière dont les points de limite des objets Range doivent être comparés.

Ils sont les méthodes compareBoundaryPoints(). how Valeurs légitimes des paramètres :

Constantes Description
START_TO_START Comparez le point de départ actuel de la plage avec le point de départ de la plage spécifiée.
START_TO_END Comparez le point de fin actuel de la plage avec le point de fin de la plage spécifiée.
END_TO_END Comparez le point de fin de la plage spécifiée avec le point de fin actuel de la plage.
END_TO_START Comparez le point de fin de la plage spécifiée avec le point de départ actuel de la plage.

Propriétés de l'objet Range

Remarque :Toutes les propriétés sont en lecture seule, vous ne pouvez pas modifier le point de départ et le point de fin de la plage en définissant ces propriétés. Vous devez appeler les méthodes setEnd() et setStart() pour cela.

Remarque :Toute lecture des propriétés après l'appel de la méthode detach() provoquera une erreur INVALID_STATE_ERR. Exception DOMException.

Propriétés Description
collapsed Vrai si le point de départ et le point de fin de la plage sont à la même position dans le document, c'est-à-dire que la plage est vide ou repliée.
commonAncestorContainer Le point de départ et le point de fin de la plage (c'est-à-dire leurs nœuds ancêtres), le Document nœud le plus profondment imbriqué.
endContainer Nœud Document contenant la pointe de fin de la plage.
endOffset Position de la pointe de fin dans endContainer.
startContainer Nœud Document contenant le point de départ de la plage.
startOffset Position du point de départ dans startContainer.

Méthodes de l'objet Range

Remarque :Si la méthode detach() de la plage a été appelée, toute autre méthode appelée sur l'objet Range provoquera une erreur INVALID_STATE_ERR. Exception DOMException.

Méthode Description
cloneContents() Retourne un nouveau DocumentFragment objet, contenant une copie de la zone de document représentée par cette plage.
cloneRange() Créer un nouveau Range objet, représentant la même zone de document que l'objet Range actuel.
collapse() Plie cette plage pour que ses points de limite coïncident.
compareBoundaryPoints() Compare les points de limite des plages spécifiées et les points de limite de la plage actuelle, et retourne -1, 0 ou 1 en fonction de leur ordre. Le point de limite à comparer est spécifié par le premier paramètre, et sa valeur doit être l'une des constantes définies précédemment.
deleteContents() Supprime la zone de document représentée par l'objet Range actuel.
detach() Notifie l'implémentation que l'utilisation actuelle de la plage n'est plus utilisée et peut arrêter de suivre. Si cette méthode de plage est appelée, toute autre méthode appelée sur cette plage suivante déclenchera une exception INVALID_STATE_ERR. Exception DOMException.
extractContents() Supprime la zone de document représentée par la plage actuelle et retourne le contenu de cette zone sous forme d'un objet DocumentFragment. Cette méthode, combinée avec deleteContents(), est très similaire à cloneContents().
insertNode() Insère le noeud spécifié au début de la plage de document.
selectNode() Définit les points de limite de cette plage pour qu'elle contienne le noeud spécifié et tous ses descendants.
selectNodeContents() Définit les points de limite de cette plage pour qu'elle contienne les descendants du noeud spécifié, mais pas le noeud spécifié lui-même.
setEnd() Définit le point de fin de cette plage pour être à l'offset spécifié dans le noeud.
setEndAfter() Définit le point de fin de cette plage pour être immédiatement après le noeud spécifié.
setEndBefore() Définit le point de fin de cette plage pour être immédiatement avant le noeud spécifié.
setStart() Définit le point de début de cette plage pour être à l'offset spécifié dans le noeud.
setStartAfter() Définit le point de début de cette plage pour être immédiatement après le noeud spécifié.
setStartBefore() Définit le point de début de cette plage pour être immédiatement avant le noeud spécifié.
surroundContents() Insère le noeud spécifié au début de la plage de document, puis redéfinit le noeud parent de tous les noeuds dans la plage pour qu'ils deviennent des descendants du noeud inséré.
toString() Retourne le contenu de texte brut de la zone de document représentée par cette plage.