Cette section définit un ensemble d'objets et d'interfaces pour accéder aux objets du document et les manipuler.
La fonctionnalité définie dans cette section (la fonctionnalité Core) est suffisante
pour permettre aux développeurs de logiciels et aux auteurs de scripts Web l'accès et la manipulation des contenus
HTML, ou XML, interprétés dans des produits conformes. L'interface de programmation d'application (API)
du DOM Core permet également de créer et peupler un objet Document
en se servant seulement d'appels de l'interface de programmation d'application (API) DOM ;
le chargement d'un objet Document
et son stockage permanent sont
laissés au soin du produit mettant en œuvre l'interface de programmation d'application (API) du DOM.
Le DOM présente les documents comme une hiérarchie d'objets Node
qui mettent également en œuvre d'autres interfaces plus spécialisées. Certains types de nœud
peuvent avoir des nœuds enfants de divers types, d'autres sont des nœuds
terminaux qui ne peuvent avoir de descendants dans la structure du document. Pour XML et HTML,
les types de nœud et leurs enfants possibles sont les suivants :
Document
-- Element
(un, au maximum), ProcessingInstruction
, Comment
,
DocumentType
(un, au maximum)DocumentFragment
-- Element
,
ProcessingInstruction
,
Comment
, Text
,
CDATASection
, EntityReference
DocumentType
-- aucun enfantEntityReference
-- Element
,
ProcessingInstruction
, Comment
,
Text
, CDATASection
,
EntityReference
Element
-- Element
,
Text
, Comment
,
ProcessingInstruction
, CDATASection
,
EntityReference
Attr
-- Text
,
EntityReference
ProcessingInstruction
-- aucun enfantComment
-- aucun enfantText
-- aucun enfantCDATASection
-- aucun enfantEntity
-- Element
,
ProcessingInstruction
, Comment
,
Text
, CDATASection
,
EntityReference
Notation
-- aucun enfantLe DOM définit également une interface NodeList
pour
la gestion des listes ordonnées d'objets Node
, tels que les enfants
d'un objet Node
ou les éléments
retournés par la méthode getElementsByTagName
de l'interface
Element
, ainsi qu'une interface
NamedNodeMap
pour la gestion des jeux non ordonnés de nœuds
référencés par leur nom d'attribut, tels que les attributs d'un objet
Element
.
Les objets NodeList
et NamedNodeMap
dans le DOM sont vivants ; ce qui veut dire que les changements survenant dans la structure sous-jacente du document
se reflètent dans tous les objets NodeList
et
NamedNodeMap
concernés. Par exemple, si un utilisateur
du DOM prend un objet NodeList
, contenant les enfants d'un
objet Element
, ajoute ensuite d'autres enfants à cet
élément (ou en retire, ou en modifie), alors ces changements se
répercutent automatiquement sur l'objet NodeList
,
sans autre action de la part de l'utilisateur. De la même manière, les changements sur un objet
Node
dans l'arbre se répercutent dans toutes les références
à cet objet Node
dans les objets
NodeList
et
NamedNodeMap
.
Finalement, les interfaces Text
,
Comment
et
CDATASection
héritent toutes de l'interface
CharacterData
.
La plupart des interfaces de programmation d'application définies par cette spécification se compose d'interfaces plutôt que de classes.
Ce qui veut dire qu'une mise en œuvre doit seulement exposer les méthodes avec les noms et les opérations indiqués,
et non pas appliquer les classes qui correspondent directement aux interfaces. Ceci permet une mise en œuvre des
interfaces (API) du DOM comme une couche mince sur les applications existantes
ayant leurs propres structures de données ou sur les applications plus récentes ayant différentes hiérarchies de classes.
Ceci signifie également que les constructeurs ordinaires (au sens de Java ou C++) ne peuvent pas être utilisés
pour créer des objets DOM, puisque les objets sous-jacents à construire ont peut-être peu de relations
avec les interfaces DOM. Pour cela, la solution conventionnelle en conception orientée objet consiste
à définir des méthodes de construction qui créent des instances d'objets mettant en œuvre les diverses interfaces.
Les objets qui mettent en œuvre une interface X donnée sont créés par une méthode createX()
de l'interface Document
, car tous les objets DOM vivent
dans le contexte d'un objet Document spécifique.
L'interface de programmation d'application (API) du DOM niveau 2 ne définit pas
de moyen standard pour créer des objets DOMImplementation
; les mises en œuvre
DOM doivent fournir une méthode spécialisée pour charger ces interfaces DOM qui permettent, dès lors,
de construire tous les autres objets.
Les interfaces de programmation du DOM Core sont conçues pour être compatibles avec une grande variété de langages, des langages de script courants jusqu'aux langages plus performants utilisés principalement en programmation professionnelle. Ainsi, les interfaces de programmation du DOM doivent opérer selon diverses philosophies de gestion de la mémoire, allant des liaisons de langage qui n'exposent pas du tout la gestion de la mémoire à l'utilisateur, en passant par les langages (notamment Java) qui offrent des constructeurs explicites mais fournissent un mécanisme ramasse-miettes récupérant automatiquement la mémoire qui n'est plus utilisée, jusqu'à ceux (en particulier C/C++) qui imposent au programmeur une allocation explicite de la mémoire objet, une conservation de l'emplacement où elle est utilisée et une libération explicite pour sa réutilisation. Pour garantir un interface de programmation d'application (API) cohérentr entre ces plateformes, le DOM ne se préoccupe pas du tout de l'aspect gestion de la mémoire et laisse plutôt ce soin à la mise en œuvre. Aucune des liaisons de langage définies par l'interface de programmation d'application (API) du DOM (pour ECMAScript et Java) n'impose de méthodes de gestion de la mémoire, mais les liaisons du DOM avec d'autres langages (spécialement C ou C++) peuvent l'imposer. Les développeurs ont la responsabilité d'adapter l'interface de programmation d'application (API) du DOM à un langage particulier, ce n'est pas l'affaire du groupe de travail DOM.
Alors qu'il serait agréable d'avoir des noms d'attribut et de méthode qui soient courts, informatifs, cohérents
en interne et familiers aux utilisateurs d'interface de programmation d'application (API) similaires,
les noms ne devraient pas entrer en conflit avec ceux des interfaces de programmation légitimes gérées
par les mises en œuvre DOM. En plus, les langages OMG IDL comme ECMAScript
sont très limités pour lever l'ambiguïté qui peut résulter de noms issus d'espaces de nommage différents,
ce qui fait qu'il est difficile d'éviter les conflits de nommage avec des noms courts et familiers. C'est pourquoi,
les noms DOM tendent à être longs et descriptifs pour rester uniques dans tous les environnements.
Le groupe de travail a également essayé de rester cohérent en interne dans l'usage des divers termes,
quoique ces choix puissent ne pas concorder avec ceux d'autres interfaces de programmation d'application (API).
Par exemple, l'interface de programmation d'application (API) du DOM emploie
le nom de méthode remove
pour une modification du modèle de structure et le nom de méthode delete
pour l'élimination de quelque chose à l'intérieur de ce modèle. La chose qui est supprimée
[N.d.T. deleted] n'est pas retournée tandis que la chose retirée [N.d.T. removed]
peut l'être au besoin.
Les interfaces de programmation API du DOM Core présentent
d'une certaine manière deux jeux d'interfaces différents vers un document XML/HTML :
l'un offrant une approche orientée objet
avec une hiérarchie d'héritage et
l'autre offrant une vue simplifiée
qui permet d'effectuer toute manipulation, via l'interface
Node
, sans nécessiter un forçage des valeurs
(en Java et autres langages comme C) ou d'appels à une interface de requête en environnements
COM. Ces opérations ayant un coût de traitemement assez important en Java et COM,
on peut utiliser le DOM dans des environnements pour lesquels la performance est critique, et on autorise donc des
fonctionnalités significatives en utilisant simplement l'interface Node
.
Comme de nombreux autres utilisateurs trouveront la hiérarchie d'héritage
plus facile à appréhender que l'approche tout est nœud
du DOM, on gère également des interfaces de haut niveau complètes pour ceux qui préfèrent
une interface de programmation d'application (API) plus orienté objet.
En pratique, cela signifie qu'il y a une certaine redondance dans l'interface de programmation d'application (API).
Le groupe de travail considère que l'approche héritage
est la première vue de l'interface de programmation d'application (API) et le jeu complet de fonctionnalités bâti
sur l'interface Node
comme apportant des fonctionnalités supplémentaires
que les utilisateurs peuvent employer, mais sans éliminer le besoin, qui serait dicté par une analyse orienté objet,
de méthodes pour les autres interfaces. (Bien sûr, si l'analyse orienté objet produit un attribut (ou une méthode) identique à l'un
des attributs (ou l'une des méthodes) de l'interface Node
,
on n'en définit alors pas d'entièrement redondant(e)). Ainsi, même s'il existe un attribut générique nodeName
sur l'interface Node
, il y a un attribut tagName
sur
l'interface Element
; ces deux attributs doivent contenir la même valeur,
toutefois la question demeurant de savoir si cela vaut la peine de gérer les deux, au vu des
différentes compositions que doit satisfaire
l'interface de programmation d'application (API) du DOM.
DOMString
Pour garantir une certaine interopérabilité, le DOM définit ce qui suit :
Un type DOMString
représente une séquence
d'unités de 16 bits.
valuetype DOMString sequence<unsigned short>;
DOMString
en se servant du codage UTF-16
(défini dans [Unicode] et dans le premier amendement de
[ISO/IEC 10646]).DOMString
(une partie forte et une partie faible).
Remarque : Bien que le DOM définisse le nom du type chaîne comme étant
DOMString
, des liaisons peuvent utiliser des noms différents.
Par exemple pour Java, un type DOMString
est lié au
type String
parce que ce type utilise aussi un codage UTF-16.
Remarque : En août 2000, la spécification OMG IDL ([OMGIDL])
comprenait un type wstring
. Cependant, cette définition ne satisfaisait pas aux critères
d'interopérabilité de l'interface de programmation d'application (API) du DOM,
puisqu'elle s'appuyait sur une négociation pour décider de la taille et du codage d'un caractère.
DOMTimeStamp
Pour garantir une certaine interopérabilité, le DOM définit ce qui suit :
Un type DOMTimeStamp
représente un nombre de millisecondes.
typedef unsigned long long DOMTimeStamp;
Remarque : bien que le DOM utilise le type DOMTimeStamp
,
les liaisons peuvent utiliser des types différents. Par exemple pour Java, le type
DOMTimeStamp
est lié au type long
.
En ECMAScript, le type DOMTimeStamp
est lié au type Date
parce que la capacité du
type integer
est trop petite.
Le DOM comprend beaucoup d'interfaces qui impliquent une correspondance de chaînes. Les processeurs HTML
supposent généralement une normalisation des noms en majuscules (moins souvent, en minuscules), par exemple, pour les
éléments, alors que les noms XML sont explicitement sensibles à
la casse. Pour les besoins du DOM, la correspondance de chaînes s'effectue purement par
comparaison binaire des
unités de 16 bits du DOMString
.
En outre, le DOM suppose que toute normalisation de casse a lieu dans le processeur, avant que les structures du
DOM ne soient construites.
Remarque : En marge de la casse, le texte peut recevoir des normalisations supplémentaires. Le groupe de travail I18N du W3C est en passe de définir exactement quelles sont les normalisations nécessaires et où celles-ci devraient s'appliquer. Le groupe de travail I18N prévoit d'imposer une normalisation précoce, c'est-à-dire que les données lues dans le DOM seront censées être déjà normalisées. Le DOM et les applications bâties sur celui-ci doivent seulement s'assurer, dans ce cas, que le texte reste normalisé au cours de ses modifications. Pour plus de détails, voir [Charmod].
Le DOM niveau 2 gère les espaces de nommage XML [Les espaces de nommage] en augmentant plusieurs interfaces du DOM niveau 1 Core pour la création et la manipulation des éléments et des attributs associés à un espace de nommage.
Pour ce qui est du DOM, les attributs spéciaux utilisés pour la déclaration des espaces de nommage XML sont toujours exposés et peuvent être manipulés comme n'importe quel autre attribut. Cependant, les nœuds restent liés en permanence aux adresses URI des espaces de nommage lors de leur création. En conséquence, le déplacement d'un nœud dans un document, en utilisant le DOM, ne produit en aucun cas un changement de son préfixe d'espace de nommage ou de son adresse URI d'espace de nommage. De la même façon, la création d'un nœud, avec un préfixe d'espace de nommage et une adresse URI d'espace de nommage, ou la modification du préfixe d'espace de nommage d'un nœud, ne se traduit pas dans un quelconque ajout, retrait ou changement des attributs spéciaux de déclaration d'espace de nommage XML concernés. La validation de l'espace de nommage n'est pas respectée ; c'est l'application DOM qui en est responsable. En particulier, puisque la correspondance entre les préfixes et les adresses URI des espaces de nommage n'est pas respectée, on ne peut pas en général sérialiser naïvement le document résultant. Par exemple, les applications devront peut-être déclarer chaque espace de nommage utilisé lors de la sérialisation d'un document.
Le DOM niveau 2 n'effectue aucune normalisation d'adresse URI ou canonisation.
Les adresses URI transmises au DOM sont censées être valides
(par exemple, les caractères comme les caractères blancs sont correctement masqués), aucune vérification lexicale n'a lieu.
Les appels d'adresse URI sont traités comme des chaînes et comparés littéralement.
Le traitement de l'appel d'adresse URI relatif d'un espace de nommage n'est pas défini. Pour assurer une interopérabilité minimale,
on devrait seulement employer des appels d'adresse URI absolus d'espaces de nommage
(c.à.d., les appels d'adresse URI commençant par un nom de système
avec un caractère deux-points).
Puisque le DOM n'effectue aucune vérification lexicale, remarquer que la chaîne vide
sera traitée comme une adresse URI d'espace de nommage réel dans les méthodes DOM niveau 2.
Les applications doivent utiliser la valeur
Les applications devraient utiliser la valeur null
comme paramètre namespaceURI
pour ces méthodes,
si aucun espace de nommage n'est voulu.null
comme paramètre namespaceURI
pour ces méthodes
si aucun espace de nommage n'est voulu. Dans les langages de programmation où on peut différencier les chaînes vides
de la valeur null
, la façon dont ces chaînes vides sont traitées, quand elles sont passées comme adresse URI
d'espace de nommage à une méthode DOM niveau 2, dépendra de la mise en œuvre. Cela reste vrai même si
le DOM ne fait aucune vérification lexicale sur les adresses URI.
Remarque : Une déclaration setAttributeNS(null, ...)
place l'attribut dans les partitions par type d'élément.
Remarque : Dans le DOM, tous les attributs de déclaration d'espace de nommage sont, par définition, liés à l'adresse URI de l'espace de nommage "http://www.w3.org/2000/xmlns/" →vf. Il s'agit des attributs dont le préfixe d'espace de nommage ou le nom qualifié sont "xmlns". Bien que (au moment de la publication) ce point ne fasse pas partie de la spécification des espaces de nommage XML [Les espaces de nommage], son incorporation est prévue dans une révision ultérieure.
Dans un document sans espace de nommage, la liste enfant d'un nœud
EntityReference
est toujours la même que celle du nœud
Entity
correspondant. Ceci n'est pas vrai pour un document dans lequel une
entité contient des préfixes d'espaces de nommage non liés.
Auquel cas, les descendants des nœuds
EntityReference
correspondants peuvent être liés
à des adresses URI d'espaces de nommage différentes,
en fonction de l'emplacement des références d'entité. Également, puisque dans le DOM les nœuds
restent toujours liés à la même adresse URI d'espace de nommage, le déplacement de ces nœuds
EntityReference
peut donner des documents qui ne peuvent pas
être sérialisés. Cela se vérifie aussi quand on se sert de la méthode createEntityReference
de l'interface Document
DOM niveau 1 pour créer
des appels d'entité qui correspondent à ces entités, puisque les descendants
de l'objet EntityReference
retourné ne sont pas liés.
Le DOM niveau 2 n'offre aucun mécanisme pour la résolution des préfixes d'espaces de nommage.
Pour toutes ces raisons, on devrait éviter d'utiliser ces entités et appels d'entité ou tout au moins y faire très attention.
Un niveau ultérieur du DOM pourrait inclure d'autres moyens pour les gérer.
Les nouvelles méthodes, comme createElementNS
et createAttributeNS
de l'interface
Document
, sont prévues pour une utilisation par des
applications reconnaissant les espaces de nommage. Les applications simples, qui n'utilisent pas les espaces de nommage, peuvent
employer les méthodes DOM niveau 1, comme createElement
et createAttribute
. Les éléments
et les attributs créés de cette façon n'ont pas de préfixe d'espace de nommage, d'adresse URI d'espace de nommage
ou de nom local.
Remarque : Les méthodes DOM niveau 1 ignorent les espaces de nommage. Quoique leur utilisation soit sûre
quand les espaces de nommage n'interviennent pas, on devrait éviter de les employer simultanément avec les nouvelles méthodes.
Les méthodes DOM niveau 1 identifient les nœuds d'attribut uniquement par leur attribut nodeName
.
Au contraire, les méthodes DOM niveau 2 liées à des espaces de nommage, identifient les nœuds d'attribut
par leurs attributs namespaceURI
et localName
. Du fait de cette distinction fondamentale,
le mélange des deux jeux de méthodes peut conduire à un résultat imprévisible. Notamment, en utilisant la méthode setAttributeNS
,
un élément peut avoir deux attributs (ou plus) avec le même attribut nodeName
,
mais des attributs namespaceURI
différents. Un appel de la méthode getAttribute
avec cette valeur nodeName
pourra alors retourner l'un d'eux. Le résultat dépend de la mise en œuvre. De la même manière, en
utilisant la méthode setAttributeNode
, on peut fixer deux attributs (ou plus) avec des valeurs nodeName
différentes mais les mêmes préfixe
et valeur namespaceURI
. Auquel cas, la méthode getAttributeNodeNS
retournera l'un ou l'autre attribut, selon la mise en œuvre. La seule certitude, dans ces cas, c'est que toutes les méthodes
qui désignent un article nommé par son attribut nodeName
s'adresseront au même article et que toutes les méthodes
qui désignent un nœud par son adresse URI ou son nom local s'adresseront au même nœud. Par exemple,
les méthodes setAttribute
et setAttributeNS
affectent les nœuds respectifs
retournés par les méthodes getAttribute
et getAttributeNS
.
On considère que les interfaces de cette section sont fondamentales et, sauf indication contraire, elles doivent être mises en œuvre en totalité par toutes les applications conformes au DOM, y compris toutes les mises en œuvre HTML DOM [DOM niveau 2 HTML].
Une application DOM peut utiliser la méthode hasFeature(feature, version)
de l'interface DOMImplementation
, avec les paramètres "Core" et "2.0" respectivement,
pour déterminer si ce module est géré ou non par la mise en œuvre. Toute mise en œuvre conforme au DOM niveau 2
ou à un de ses modules, doit se conformer au module Core. Pour plus d'informations, se reporter à la section
sur la conformité dans cette spécification.
Les opérations DOM ne soulèvent des exceptions que dans des circonstances exceptionnelles
,
c.à.d., quand une opération est impossible à réaliser (soit pour des raisons logiques, car des données
sont manquantes, soit parce que la mise en œuvre est devenue instable). En général, les méthodes DOM
retournent des valeurs d'erreur spécifiques au cours de situations de traitement ordinaires, telle qu'une
erreur de dépassement dans l'utilisation
d'un nœud NodeList
.
Les mises en œuvre devraient soulever d'autres exceptions en d'autres circonstances. Par exemple, la mise en œuvre
devrait soulever une exception spécifique au passage d'un argument de valeur null
si cette valeur est inattendue.
Certains systèmes de langage et d'objet ne gèrent pas le concept d'exception. Pour ces systèmes, les conditions d'erreur peuvent être signalées à l'aide de mécanismes de relevé d'erreurs natifs. Pour certaines liaisons, par exemple, les méthodes peuvent retourner des codes d'erreur similaires à ceux listés dans les descriptions de méthode correspondantes.
exception DOMException { unsigned short code; }; // ExceptionCode const unsigned short INDEX_SIZE_ERR = 1; const unsigned short DOMSTRING_SIZE_ERR = 2; const unsigned short HIERARCHY_REQUEST_ERR = 3; const unsigned short WRONG_DOCUMENT_ERR = 4; const unsigned short INVALID_CHARACTER_ERR = 5; const unsigned short NO_DATA_ALLOWED_ERR = 6; const unsigned short NO_MODIFICATION_ALLOWED_ERR = 7; const unsigned short NOT_FOUND_ERR = 8; const unsigned short NOT_SUPPORTED_ERR = 9; const unsigned short INUSE_ATTRIBUTE_ERR = 10; // Introduite dans DOM niveau 2 : const unsigned short INVALID_STATE_ERR = 11; // Introduite dans DOM niveau 2 : const unsigned short SYNTAX_ERR = 12; // Introduite dans DOM niveau 2 : const unsigned short INVALID_MODIFICATION_ERR = 13; // Introduite dans DOM niveau 2 : const unsigned short NAMESPACE_ERR = 14; // Introduite dans DOM niveau 2 : const unsigned short INVALID_ACCESS_ERR = 15;
Un entier indiquant le type de l'erreur générée.
Remarque : D'autres codes numériques sont réservés par le W3C pour un éventuel usage ultérieur.
DOMSTRING_SIZE_ERR
HIERARCHY_REQUEST_ERR
INDEX_SIZE_ERR
INUSE_ATTRIBUTE_ERR
INVALID_ACCESS_ERR
, introduit dans DOM niveau 2.INVALID_CHARACTER_ERR
INVALID_MODIFICATION_ERR
, introduit dans DOM niveau 2.INVALID_STATE_ERR
, introduit dans DOM niveau 2.NAMESPACE_ERR
, introduit dans DOM niveau 2.NOT_FOUND_ERR
NOT_SUPPORTED_ERR
NO_DATA_ALLOWED_ERR
NO_MODIFICATION_ALLOWED_ERR
SYNTAX_ERR
, introduit dans DOM niveau 2.WRONG_DOCUMENT_ERR
L'interface DOMImplementation
fournit un certain nombre de méthodes pour effectuer des opérations
qui sont indépendantes de toute instance particulière du modèle objet du document.
interface DOMImplementation { boolean hasFeature(in DOMString feature, in DOMString version); // Introduite dans DOM niveau 2 : DocumentType createDocumentType(in DOMString qualifiedName, in DOMString publicId, in DOMString systemId) raises(DOMException); // Introduite dans DOM niveau 2 : Document createDocument(in DOMString namespaceURI, in DOMString qualifiedName, in DocumentType doctype) raises(DOMException); };
createDocument
introduit dans DOM niveau 2Document
du type indiqué
avec son élément document. Les mises en œuvre DOM seulement HTML ne sont pas tenues de mettre en œuvre cette méthode.Document
du type indiqué avec son élément document.
namespaceURI
de type DOMString
qualifiedName
de type DOMString
doctype
de type DocumentType
null
.doctype
n'est pas null
, la valeur de son attribut
Node.ownerDocument
correspond au document à créer.
INVALID_CHARACTER_ERR : Soulevée si le nom qualifié indiqué contient un caractère illégal. NAMESPACE_ERR : Soulevée si WRONG_DOCUMENT_ERR : Soulevée si NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas
la fonctionnalité "XML" et que le langage exposé au travers de l'interface |
createDocumentType
introduit dans DOM niveau 2DocumentType
vide.
Les déclarations d'entité et leurs notations ne sont pas disponibles. La résolution des appels d'entité
et l'ajout des attributs implicites n'ont pas lieu. Il est prévu qu'une version ultérieure du DOM fournisse
un moyen de peupler un DocumentType
.qualifiedName
de type DOMString
publicId
de type DOMString
systemId
de type DOMString
Un nouveau nœud |
INVALID_CHARACTER_ERR : Soulevée si le nom qualifié indiqué contient un caractère illégal. NAMESPACE_ERR : Soulevée si NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas
la fonctionnalité "XML" et que le langage exposé au travers de l'interface |
hasFeature
feature
de type DOMString
version
de type DOMString
null
ou la chaîne vide,
la méthode renverra la valeur true
indiquant une gestion de toute version de la fonctionnalité.
|
|
DocumentFragment
est un objet Document
allégé
ou minimal
. On souhaite très souvent pouvoir extraire une portion de l'arbre du document
ou créer un nouveau fragment de document. Imaginez de mettre en œuvre une commande d'utilisateur comme couper ou de
réarranger un document en déplaçant des fragments. Un objet qui puisse contenir de tels fragments est souhaitable
et il semble assez naturel d'utiliser un nœud pour le faire. Quoiqu'un objet Document
puisse tenir ce rôle, ce Document
est potentiellement un objet poids lourd,
en fonction de la mise en œuvre sous-jacente. Ce qui fait vraiment l'affaire, c'est un objet de très faible poids.
Et DocumentFragment
est justement cet objet.
En outre, des opérations diverses, tel qu'insérer des nœuds comme enfants d'un autre objet
Node
, peuvent admettre des objets DocumentFragment
comme arguments.
Le résultat est le suivant : tous les nœuds enfants de l'objet DocumentFragment
sont transférés
dans la liste des enfants de ce nœud.
Les enfants d'un nœud DocumentFragment
, au nombre de zéro ou plus nœuds, représentent les
têtes des sous-arbres définissant la structure du document. Les nœuds DocumentFragment
ne sont pas obligatoirement
des documents XML bien formés
(quoiqu'ils doivent nécessairement suivre les règles imposées aux entités analysables XML bien formées,
qui peuvent avoir plusieurs nœuds de tête). Par exemple, un DocumentFragment
peut n'avoir qu'un seul enfant,
peut-être un nœud Text
. Un tel modèle de structure ne constitue pas
un document HTML ni un document XML bien formé.
Quand un nœud DocumentFragment
est inséré dans un
Document
(ou, en fait, dans tout autre
Node
qui accepte des enfants), les enfants de l'objet DocumentFragment
,
et non l'objet DocumentFragment
en question, sont insérés dans le Node
.
Par conséquent, l'objet DocumentFragment
est très utile lorsque l'utilisateur souhaite créer des nœuds
frères ; l'objet DocumentFragment
fait alors office de parent pour
ces nœuds et l'utilisateur peut donc employer les méthodes standards de l'interface
Node
, telles que insertBefore
et
appendChild
.
interface DocumentFragment : Node { };
L'interface Document
représente le document HTML, ou XML, entier. Conceptuellement, c'est la
racine de l'arbre du document, qui offre l'accès primaire aux
données du document.
Puisque les éléments, les nœuds de texte, les commentaires, les instructions de traitement, etc., ne peuvent pas exister
en-dehors du contexte d'un Document
, l'interface Document
contient aussi les méthodes nécessaires
pour créer ces objets. Les objets Node
créés possèdent un attribut
ownerDocument
qui les associent au Document
dans le contexte duquel ils ont été créés.
interface Document : Node { readonly attribute DocumentType doctype; readonly attribute DOMImplementation implementation; readonly attribute Element documentElement; Element createElement(in DOMString tagName) raises(DOMException); DocumentFragment createDocumentFragment(); Text createTextNode(in DOMString data); Comment createComment(in DOMString data); CDATASection createCDATASection(in DOMString data) raises(DOMException); ProcessingInstruction createProcessingInstruction(in DOMString target, in DOMString data) raises(DOMException); Attr createAttribute(in DOMString name) raises(DOMException); EntityReference createEntityReference(in DOMString name) raises(DOMException); NodeList getElementsByTagName(in DOMString tagname); // Introduite dans DOM niveau 2 : Node importNode(in Node importedNode, in boolean deep) raises(DOMException); // Introduite dans DOM niveau 2 : Element createElementNS(in DOMString namespaceURI, in DOMString qualifiedName) raises(DOMException); // Introduite dans DOM niveau 2 : Attr createAttributeNS(in DOMString namespaceURI, in DOMString qualifiedName) raises(DOMException); // Introduite dans DOM niveau 2 : NodeList getElementsByTagNameNS(in DOMString namespaceURI, in DOMString localName); // Introduite dans DOM niveau 2 : Element getElementById(in DOMString elementId); };
doctype
de type DocumentType
,
en lecture seuleDocumentType
) associée à ce document.
Pour les documents HTML comme XML sans déclaration de type de document, c'est la valeur
null
qui est retournée. Le DOM niveau 2 ne gère pas l'édition de la déclaration de type de document.
On ne peut altérer docType
d'aucune façon, même en utilisant les méthodes héritées de
l'interface Node
, telles que insertNode
ou removeNode
.documentElement
de type Element
,
en lecture seuletagName
est "HTML".implementation
de type DOMImplementation
,
en lecture seuleDOMImplementation
qui contient ce document. Une application DOM
peut utiliser des objets issus de plusieurs mises en œuvre.createAttribute
Attr
avec le nom fourni.
Remarquer que l'instance Attr
peut alors être placée
sur un objet Element
en utilisant la méthode setAttributeNode
.createAttributeNS
.
name
de type DOMString
INVALID_CHARACTER_ERR : Soulevée si le nom indiqué contient un caractère illégal. |
createAttributeNS
introduit dans DOM niveau 2Selon [Les espaces de nommage dans XML],
les applications doivent utiliser la valeur null
comme paramètre namespaceURI
dans les méthodes
pour ne définir aucun espace de nommage.
namespaceURI
de type DOMString
qualifiedName
de type DOMString
Un nouvel objet
|
INVALID_CHARACTER_ERR : Soulevée si le nom qualifié indiqué contient un caractère illégal selon la spécification XML 1.0 [XML]. NAMESPACE_ERR : Soulevée si NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas
la fonctionnalité "XML" et que le langage exposé au travers de l'interface |
createCDATASection
CDATASection
dont la valeur est
la chaîne indiquée.
data
de type DOMString
CDATASection
.
Le nouvel objet |
NOT_SUPPORTED_ERR : Soulevée s'il s'agit d'un document HTML. |
createComment
createDocumentFragment
DocumentFragment
vide.
Un nouveau |
createElement
Element
, et les attributs peuvent donc être
définis directement sur l'objet retourné.Attr
les représentant sont automatiquement créés et liés à l'élément.createElementNS
.
tagName
de type DOMString
tagName
, mais la mise en œuvre doit le faire correspondre
avec la forme canonique.
INVALID_CHARACTER_ERR : Soulevée si le nom indiqué contient un caractère illégal. |
createElementNS
introduit dans DOM niveau 2namespaceURI
de type DOMString
qualifiedName
de type DOMString
Un nouvel objet
|
INVALID_CHARACTER_ERR : Soulevée si le nom qualifié indiqué contient un caractère illégal selon la spécification XML 1.0 [XML]. NAMESPACE_ERR : Soulevée si NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas
la fonctionnalité "XML" et que le langage exposé au travers de l'interface |
createEntityReference
EntityReference
. En outre,
si l'entité appelée est connue, la liste des enfants du nœud
EntityReference
devient la même que celle du nœud
Entity
correspondant.
Remarque : Si un descendant du nœud Entity
a un
préfixe d'espace de nommage non lié, le nœud
EntityReference
correspondant est également non lié
(son paramètre namespaceURI
est null
). Le DOM niveau 2 ne gère aucun mécanisme
de résolution des préfixes d'espaces de nommage.
name
de type DOMString
Le nouvel objet |
INVALID_CHARACTER_ERR : Soulevée si le nom indiqué contient un caractère illégal. NOT_SUPPORTED_ERR : Soulevée s'il s'agit d'un document HTML. |
createProcessingInstruction
ProcessingInstruction
qui
reçoit le nom indiqué et des chaînes de données.
Le nouvel objet |
INVALID_CHARACTER_ERR : Soulevé si la cible indiquée contient un caractère illégal. NOT_SUPPORTED_ERR : Soulevée s'il s'agit d'un document HTML. |
createTextNode
getElementById
introduit dans DOM niveau 2Element
dont l'ID
est donné
par l'attribut elementId
. S'il n'existe pas un tel élément, retourne null
.
Le comportement n'est pas défini si plusieurs éléments ont cet ID
.
Remarque : La mise en œuvre DOM doit conserver l'information qui précise quels attributs
sont du type ID. Les attributs avec le nom "ID" ne sont pas du type ID, à moins d'être définis comme tel.
Les mises en œuvre, ne sachant pas si des attributs sont ou non du type ID, sont censées retourner null
.
elementId
de type DOMString
id
unique d'un élément.
L'élément correspondant. |
getElementsByTagName
NodeList
de tous les
Element
avec un nom de balise donné, dans l'ordre de leur rencontre
au cours de la traversée préordonnée de l'arbre de Document
.
tagname
de type DOMString
getElementsByTagNameNS
introduit dans DOM niveau 2NodeList
de tous les
Element
avec un nom local
et une adresse URI d'espace de nommage donnés dans l'ordre de leur rencontre au cours de la
traversée préordonnée de l'arbre de Document
.
namespaceURI
de type DOMString
localName
de type DOMString
NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas
la fonctionnalité "XML" et que le langage exposé au travers de l'interface |
importNode
introduit dans DOM niveau 2parentNode
est null
). Le nœud source n'est ni altéré
ni retiré du document original ; cette méthode crée une nouvelle copie du nœud source.nodeName
et nodeType
du nœud source,
plus les attributs relatifs aux espaces de nommage (prefix
, localName
et namespaceURI
).
Comme pour l'opération cloneNode
sur un Node
,
le nœud source n'est pas altéré.nodeType
, en essayant de reproduire le comportement attendu
si un fragment de la source XML, ou HTML, était copié d'un document à l'autre,
en reconnaissant que deux documents peuvent avoir des DTD différents dans le cas de XML.
La liste suivante décrit les particularités de chaque type de nœud.
ownerElement
reçoit la valeur de null
et le drapeau specified
la valeur true
sur l'objet Attr
généré ;
Les descendants du nœud source
Attr
sont importés récursivement et les nœuds résultants
réassemblés pour former le sous-arbre correspondant.deep
n'a aucun effet sur les nœuds Attr
;
ceux-ci emportent toujours leurs enfants lors de leur import.deep
reçoit la valeur true
, les descendants
de l'élément source sont importés récursivement et les nœuds résultants réassemblés pour former le sous-arbre correspondant.
Sinon un objet DocumentFragment
vide est simplement généré.Document
ne peuvent pas être importés.DocumentType
ne peuvent pas être importés.Attr
générés sont liés
à l'objet Element
généré. Les attributs implicites
ne sont pas recopiés, quoique si le document à importer définit des attributs implicites pour ce nom d'élément,
ceux-ci sont assignés. Si le paramètre deep
de la méthode importNode
a la valeur true
, les
descendants de l'élément source sont importés récursivement
et les nœuds résultants réassemblés pour former le sous-arbre correspondant.Entity
peuvent être importés mais, pour la version
courante du DOM, l'objet DocumentType
est en lecture seule.
La possibilité de rajouter ces nœuds importés à un DocumentType
est envisagé pour une version ultérieure du DOM.publicId
, systemId
et notationName
sont recopiés.
Si un import avec deep
vérifié est demandé, les descendants
de l'objet Entity
source sont importés et les nœuds résultants
réassemblés pour former le sous-arbre correspondant.EntityReference
en question est recopié, même
si un import avec deep
vérifié est demandé, puisque la source et le document de destination peuvent avoir défini
l'entité différemment. Si le document importé fournit une définition pour ce nom d'entité, sa valeur est assignée.Notation
peuvent être importés mais, dans la version
courante du DOM, l'objet DocumentType
est en lecture seule.
La possibilité de rajouter ces nœuds importés à un DocumentType
est envisagé pour une version ultérieure du DOM.publicId
et systemId
sont recopiés.deep
n'a aucun effet sur les nœuds Notation
puisque ceux-ci n'ont jamais aucun enfant.target
et data
sur celles du nœud source.CharacterData
,
recopient les valeurs de leurs attributs data
et length
sur celles du nœud source.importedNode
de type Node
deep
de type boolean
true
, importe récursivement le sous-arbre à partir du nœud indiqué ;
pour la valeur false
, n'importe que le nœud en question, comme expliqué ci-dessus.
Ceci n'a aucun effet sur les nœuds Attr
,
EntityReference
et Notation
.
Le nœud importé qui apparatient à ce |
NOT_SUPPORTED_ERR : Soulevée si le type du nœud n'est pas reconnu. |
L'interface Node
est le type de données principal pour le modèle objet de document dans son ensemble.
Elle représente un seul nœud dans l'arbre du document. Bien que tous les objets mettant en œuvre
l'interface Node
exposent des méthodes pour la gestion des enfants, certains ne peuvent pas avoir d'enfants.
Par exemple, les nœuds Text
ne peuvent pas avoir d'enfants,
et ajouter un enfant à ces nœuds soulève alors une exception DOMException
.
Les attributs nodeName
, nodeValue
et attributes
composent un mécanisme permettant
d'accéder aux informations d'un nœud sans devoir faire appel aux interfaces dérivées spécifiques.
Au cas où il n'y aurait pas de correspondance évidente entre ces attributs et un type de nœud particulier
(par exemple, nodeValue
pour un objet Element
ou
attributes
pour un objet Comment
), la valeur null
est retournée. Remarquer que les interfaces spécialisées peuvent offrir des mécanismes supplémentaires plus pratiques
pour obtenir ou fixer les informations pertinentes.
interface Node { // Type de nœud const unsigned short ELEMENT_NODE = 1; const unsigned short ATTRIBUTE_NODE = 2; const unsigned short TEXT_NODE = 3; const unsigned short CDATA_SECTION_NODE = 4; const unsigned short ENTITY_REFERENCE_NODE = 5; const unsigned short ENTITY_NODE = 6; const unsigned short PROCESSING_INSTRUCTION_NODE = 7; const unsigned short COMMENT_NODE = 8; const unsigned short DOCUMENT_NODE = 9; const unsigned short DOCUMENT_TYPE_NODE = 10; const unsigned short DOCUMENT_FRAGMENT_NODE = 11; const unsigned short NOTATION_NODE = 12; readonly attribute DOMString nodeName; attribute DOMString nodeValue; // soulève une exception DOMException à l'initialisation // soulève une exception DOMException en retour readonly attribute unsigned short nodeType; readonly attribute Node parentNode; readonly attribute NodeList childNodes; readonly attribute Node firstChild; readonly attribute Node lastChild; readonly attribute Node previousSibling; readonly attribute Node nextSibling; readonly attribute NamedNodeMap attributes; // Modifié dans DOM niveau 2 : readonly attribute Document ownerDocument; Node insertBefore(in Node newChild, in Node refChild) raises(DOMException); Node replaceChild(in Node newChild, in Node oldChild) raises(DOMException); Node removeChild(in Node oldChild) raises(DOMException); Node appendChild(in Node newChild) raises(DOMException); boolean hasChildNodes(); Node cloneNode(in boolean deep); // Modifié dans DOM niveau 2 : void normalize(); // Introduite dans DOM niveau 2 : boolean isSupported(in DOMString feature, in DOMString version); // Introduite dans DOM niveau 2 : readonly attribute DOMString namespaceURI; // Introduite dans DOM niveau 2 : attribute DOMString prefix; // soulève une exception DOMException à l'initialisation // Introduite dans DOM niveau 2 : readonly attribute DOMString localName; // Introduite dans DOM niveau 2 : boolean hasAttributes(); };
Un entier indiquant le type du nœud en question.
Remarque : Les codes numériques jusqu'à 200 sont réservés par le W3C pour un possible usage ultérieur.
ATTRIBUTE_NODE
Attr
.CDATA_SECTION_NODE
CDATASection
.COMMENT_NODE
Comment
.DOCUMENT_FRAGMENT_NODE
DocumentFragment
.DOCUMENT_NODE
Document
.DOCUMENT_TYPE_NODE
DocumentType
.ELEMENT_NODE
Element
.ENTITY_NODE
Entity
.ENTITY_REFERENCE_NODE
EntityReference
.NOTATION_NODE
Notation
.PROCESSING_INSTRUCTION_NODE
ProcessingInstruction
.TEXT_NODE
Text
.Les valeurs des attributs nodeName
, nodeValue
et attributes
varient en fonction
du type du nœud, comme suit :
Interface | nodeName | nodeValue | attributes |
---|---|---|---|
Attr | nom de l'attribut | valeur de l'attribut | null |
CDATASection | #cdata-section | contenu de la section CDATA | null |
Comment | #comment | contenu du commentaire | null |
Document | #document | null | null |
DocumentFragment | #document-fragment | null | null |
DocumentType | nom du type de document | null | null |
Element | nom de la balise | null | objet NamedNodeMap |
Entity | nom de l'entité | null | null |
EntityReference | nom de l'entité appelée | null | null |
Notation | nom de la notation | null | null |
ProcessingInstruction | valeur de target | contenu entier en excluant target | null |
Text | #text | contenu du nœud de texte | null |
attributes
de type NamedNodeMap
,
en lecture seuleNamedNodeMap
contenant les attributs de ce nœud
(si c'est un objet Element
), sinon la valeur null
.childNodes
de type NodeList
,
en lecture seuleNodeList
qui contient tous les enfants de ce nœud.
S'il n'y a aucun enfant, c'est un objet NodeList
ne contenant aucun nœud.firstChild
de type Node
,
en lecture seulenull
.lastChild
de type Node
, en lecture seulenull
.localName
de type DOMString
, en lecture seule,
introduit dans DOM niveau 2ELEMENT_NODE
ou ATTRIBUTE_NODE
et pour les nœuds
créés avec une méthode DOM niveau 1, telle que la méthode createElement
de
l'interface Document
, c'est toujours la valeur null
qui est
retournée.namespaceURI
de type DOMString
, en lecture seule,
introduit dans DOM niveau 2null
si ce n'est pas indiqué.ELEMENT_NODE
ou ATTRIBUTE_NODE
et pour les nœuds
créés par une méthode DOM niveau 1, telle que la méthode createElement
de
l'interface Document
, c'est toujours la valeur null
qui est
retournée.
Remarque : Selon la spécification des espaces de nommage en XML [Les espaces de nommage], un attribut n'hérite pas de l'espace de nommage de l'élément auquel il se rapporte. Si on ne donne pas explicitement d'espace de nommage, l'attribut n'en a simplement pas.
nextSibling
de type Node
,
en lecture seulenull
qui est retournée.nodeName
de type DOMString
,
en lecture seulenodeType
de type unsigned short
,
en lecture seulenodeValue
de type DOMString
null
, son paramétrage ne produit aucun effet
y compris quand le nœud est en lecture seule.
NO_MODIFICATION_ALLOWED_ERR : Soulevée quand le nœud est en lecture seule. |
DOMSTRING_SIZE_ERR : Soulevée si cela devait retourner plus de caractères qu'un objet
|
ownerDocument
de type Document
, en lecture seule,
modifié dans DOM niveau 2Document
associé à ce nœud. C'est aussi l'objet
Document
utilisé pour créer de nouveaux nœuds.
Quand ce nœud est un objet Document
, ou
DocumentType
, qui n'est pas encore utilisé avec un objet
Document
, la valeur null
est retournée.parentNode
de type Node
,
en lecture seuleAttr
, Document
,
DocumentFragment
, Entity
et
Notation
, peuvent avoir un parent. Cependant, si ce nœud vient juste
d'être créé et n'est pas encore ajouté à l'arbre, ou si ce nœud a été retiré de l'arbre, la valeur null
est retournée.prefix
de type DOMString
,
introduit dans DOM niveau 2null
si non indiqué.nodeName
, qui
contient le nom qualifié, tout comme les attributs
tagName
et name
des interfaces Element
et
Attr
, quand celles-ci s'appliquent.namespaceURI
et localName
ne changent pas.ELEMENT_NODE
ou ATTRIBUTE_NODE
et pour les nœuds
créés par une méthode DOM niveau 1, telle que la méthode createElement
de
l'interface Document
, la valeur null
est toujours retournée.
INVALID_CHARACTER_ERR : Soulevée si le préfixe indiqué contient un caractère illégal selon la spécification XML 1.0 [XML]. NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule. NAMESPACE_ERR : Soulevée si le préfixe indiqué est malformé
selon la spécification des espaces de nommage dans XML,
ou si l'attribut |
previousSibling
de type Node
,
en lecture seulenull
.appendChild
newChild
à la fin de la liste des enfants de ce nœud. Si
newChild
est déjà dans l'arbre, il en est d'abord retiré.
newChild
de type Node
DocumentFragment
, le contenu entier du fragment de document
est transféré dans la liste enfant de ce nœud.
Le nœud ajouté. |
HIERARCHY_REQUEST_ERR : Soulevée si ce nœud est d'un type qui n'admet pas d'enfant du type de ce
nœud WRONG_DOCUMENT_ERR : Soulevée si le nœud NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule ou si le parent précédent du nœud à insérer est en lecture seule. |
cloneNode
parentNode
a une valeur de null
).Element
recopie tous les attributs et leurs valeurs,
y compris ceux générés par le processeur XML pour représenter les attributs implicites ;
toutefois, cette méthode ne recopie pas le texte qui y est contenu, à moins qu'il ne s'agisse d'un clone en profondeur,
puisque le texte est contenu dans un nœud Text
enfant.
Le clonage direct d'un objet Attribute
, contrairement au clonage partiel d'un objet
Element
, retourne un attribut spécifié
(specified
a la valeur true
). Le clonage de tout autre type de nœud retourne simplement une copie du nœud.EntityReference
sont
en lecture seule. En outre, les clones de nœuds
Attr
non spécifiés sont indiqués.
Le clonage de nœuds Document
,
DocumentType
, Entity
et
Notation
dépend également de la mise en œuvre.
deep
de type boolean
true
, clone récursivement le sous-arbre à partir du nœud indiqué ;
pour la valeur false
, ne clone que le nœud en question (et ses attributs, si c'est un nœud
Element
).
Le nœud en double. |
hasAttributes
introduit dans DOM niveau 2
|
|
hasChildNodes
|
|
insertBefore
newChild
avant le nœud refChild
existant.
Si refChild
est null
, insère newChild
à la fin de la liste des enfants.newChild
est un objet DocumentFragment
, tous ses enfants sont
insérés, dans le même ordre, avant refChild
. Si le nœud newChild
est
déjà dans l'arbre, il en est d'abord retiré.
Le nœud à insérer. |
HIERARCHY_REQUEST_ERR : Soulevée si ce nœud est d'un type qui n'admet pas d'enfants du type du nœud WRONG_DOCUMENT_ERR : Soulevée si NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud ou si le parent du nœud à insérer sont en lecture seule. NOT_FOUND_ERR : Soulevée si |
isSupported
introduit dans DOM niveau 2feature
de type DOMString
hasFeature
de l'interface DOMImplementation
.version
de type DOMString
true
.
|
Retourne la valeur |
normalize
modifié dans DOM niveau 2Text
dans la profondeur entière
du sous-arbre en aval de ce Node
, y compris les nœuds attributs, dans une forme normaleoù seule la structure (par exemple, les éléments, les commentaires, les instructions de traitement, les sections CDATA et les appels d'entité) distingue les nœuds
Text
, c.à.d. qu'il n'y a pas de nœuds
Text
adjacents ni de nœuds
Text
vides. On peut s'en servir pour s'assurer que
la vue DOM d'un document est identique comme si celui-ci avait été stocké puis rechargé ;
elle est utile quand on doit effectuer des opérations (comme les recherches XPointer
[XPointer]) qui dépendent de la structure d'arbre d'un document particulier.
Remarque : Pour les cas où le document contient des nœuds CDATASection
,
l'opération de normalisation seule sera peut-être insuffisante, puisque les pointeur XPointer ne font aucune différence
entre les nœuds Text
et CDATASection
.
removeChild
oldChild
de la liste des enfants et retourne ce nœud.
oldChild
de type Node
Le nœud retiré. |
NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule. NOT_FOUND_ERR : Soulevée si |
replaceChild
oldChild
par newChild
dans la liste des enfants
et retourne le nœud oldChild
.newChild
est un objet DocumentFragment
, le nœud
oldChild
est remplacé par tous les enfants de
DocumentFragment
, qui sont insérés dans le même ordre.
Si le nœud newChild
est déjà dans l'arbre, il en est d'abord retiré.
Le nœud remplacé. |
HIERARCHY_REQUEST_ERR : Soulevée si ce nœud est d'un type qui n'admet pas d'enfant du type du nœud WRONG_DOCUMENT_ERR : Soulevée si NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud ou le parent du nouveau nœud sont en lecture seule. NOT_FOUND_ERR : Soulevée si |
L'interface NodeList
fournit une abstraction d'une collection de nœuds ordonnée, sans définir
ni contraindre la façon dont elle est mise en œuvre. Les objets NodeList
dans le DOM
sont vivants.
Les articles dans l'objet NodeList
sont accessibles via un index de nombre entier, commençant par 0.
interface NodeList { Node item(in unsigned long index); readonly attribute unsigned long length; };
length
de type unsigned long
,
en lecture seulelength-1
inclus.item
index
de l'article dans la collection. Si index
est supérieur
ou égal au nombre de nœuds dans la liste, retourne la valeur null
.
index
of type unsigned long
Le nœud à la position indiquée par |
Les objets qui mettent en œuvre l'interface NamedNodeMap
sont employés pour représenter des
collections de nœuds auxquels on accède par leur nom. Remarquer que NamedNodeMap
n'hérite pas
de NodeList
; les objets NamedNodeMap
ne sont pas conservés
dans un ordre particulier. On peut aussi accéder aux objets contenus dans un objet mettant en œuvre
NamedNodeMap
par un index ordinal mais simplement pour permettre une énumération pratique
du contenu d'un objet NamedNodeMap
, et cela n'implique pas que le DOM déninisse un ordre pour ces nœuds.
Les objets NamedNodeMap
dans le DOM sont vivants.
interface NamedNodeMap { Node getNamedItem(in DOMString name); Node setNamedItem(in Node arg) raises(DOMException); Node removeNamedItem(in DOMString name) raises(DOMException); Node item(in unsigned long index); readonly attribute unsigned long length; // Introduite dans DOM niveau 2 : Node getNamedItemNS(in DOMString namespaceURI, in DOMString localName); // Introduite dans DOM niveau 2 : Node setNamedItemNS(in Node arg) raises(DOMException); // Introduite dans DOM niveau 2 : Node removeNamedItemNS(in DOMString namespaceURI, in DOMString localName) raises(DOMException); };
length
de type unsigned long
,
en lecture seulelength-1
inclus.getNamedItem
getNamedItemNS
introduit dans DOM niveau 2Selon [Les espaces de nommage dans XML],
les applications doivent utiliser la valeur null
comme paramètre namespaceURI
dans les méthodes
pour ne définir aucun espace de nommage.
namespaceURI
de type DOMString
localName
de type DOMString
NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas
la fonctionnalité "XML" et que le langage exposé au travers de l'interface |
item
index
de l'item dans la carte. Si index
est supérieur ou égal au nombre de nœuds dans cette carte, la méthode retourne null
.
index
de type unsigned long
Le nœud dont la position dans la carte est indiquée par le paramètre |
removeNamedItem
name
de type DOMString
nodeName
du nœud à retirer.
Le nœud retiré de cette carte, s'il en existe un avec ce nom. |
NOT_FOUND_ERR : Soulevée si aucun nœud ne correspond au nom du paramètre NO_MODIFICATION_ALLOWED_ERR : Soulevée si cette carte est en lecture seule. |
removeNamedItemNS
introduit dans DOM niveau 2attributes
de l'interface
Node
. Auquel cas, il apparaît immédiatement un attribut contenant
la valeur par défaut et, le cas échéant, l'adresse URI d'espace de nommage, le nom local et le préfixe correspondants.Selon [Les espaces de nommage dans XML],
les applications doivent utiliser la valeur null
comme paramètre namespaceURI
dans les méthodes
pour ne définir aucun espace de nommage.
namespaceURI
de type DOMString
localName
de type DOMString
Le nœud retiré de cette carte, s'il en existe un avec ce nom local et cette adresse URI d'espace de nommage. |
NOT_FOUND_ERR : Soulevée s'il n'existe aucun nœud correspondant aux paramètres
NO_MODIFICATION_ALLOWED_ERR : Soulevée si cette carte est en lecture seule. NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas
la fonctionnalité "XML" et que le langage exposé au travers de l'interface |
setNamedItem
nodeName
. Si un nœud avec ce nom est
déjà présent dans cette carte, il est remplacé par le nouveau.nodeName
est utilisé pour dériver le nom sous lequel le nœud devra être stocké,
on ne peut pas stocker plusieurs nœuds ayant certains types (ceux qui ont une valeur de chaîne spéciale) car les noms peuvent entrer en conflit. Il semble préférable de recourir à cette solution plutôt qu'à des alias pour les nœuds.
errata : 2002-02-14
arg
de type Node
nodeName
.
WRONG_DOCUMENT_ERR : Soulevée si le paramètre NO_MODIFICATION_ALLOWED_ERR : Soulevée si cette carte est en lecture seule. INUSE_ATTRIBUTE_ERR : Soulevée si HIERARCHY_REQUEST_ERR : Soulevée pour une tentative d'ajout d'un nœud qui n'appartient
pas à cet objet |
setNamedItemNS
introduit dans DOM niveau 2namespaceURI
et localName
. Si un nœud avec cette adresse URI d'espace de nommage et ce nom local est déjà présent
dans cette carte, il est remplacé par le nouveau.Selon [Les espaces de nommage dans XML],
les applications doivent utiliser la valeur null
comme paramètre namespaceURI
dans les méthodes
pour ne définir aucun espace de nommage.
errata : 2002-02-14
arg
de type Node
namespaceURI
et localName
.
WRONG_DOCUMENT_ERR : Soulevée si le paramètre NO_MODIFICATION_ALLOWED_ERR : Soulevée si cette carte est en lecture seule. INUSE_ATTRIBUTE_ERR : Soulevée si HIERARCHY_REQUEST_ERR : Soulevée pour une tentative d'ajout d'un nœud qui n'appartient
pas à cet objet NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas
la fonctionnalité "XML" et que le langage exposé au travers de l'interface |
L'interface CharacterData
renforce l'objet Node par un jeu d'attributs et de méthodes afin d'accéder
aux données textuelles dans le DOM. Pour la lisibilité, on définit ce jeu ici plutôt que dans chaque objet
utilisant ces attributs et méthodes. Aucun objet DOM ne correspond directement à un nœud
CharacterData
, quoique les nœuds Text
et d'autres
héritent de son interface. Tous les paramètres offset
dans cette interface se détermine par rapport à 0.
Comme expliqué dans l'interface DOMString
, les chaînes textuelles
dans le DOM sont représentées dans un codage UTF-16, c.à.d., comme une séquence d'unités de 16 bits.
Par la suite, on emploiera le terme unités de 16 bits,
à chaque fois que c'est nécessaire, pour indiquer que l'indexation des objets CharacterData
a lieu selon des unités de 16 bits.
interface CharacterData : Node { attribute DOMString data; // soulève une exception DOMException à l'initialisation // soulève une exception DOMException en retour readonly attribute unsigned long length; DOMString substringData(in unsigned long offset, in unsigned long count) raises(DOMException); void appendData(in DOMString arg) raises(DOMException); void insertData(in unsigned long offset, in DOMString arg) raises(DOMException); void deleteData(in unsigned long offset, in unsigned long count) raises(DOMException); void replaceData(in unsigned long offset, in unsigned long count, in DOMString arg) raises(DOMException); };
data
de type DOMString
CharacterData
.
Néanmoins, les limitations de la mise en œuvre empêcheront peut-être que la totalité des données d'un nœud
puisse tenir dans un objet DOMString
. Auquel cas, l'utilisateur peut appeler
la méthode substringData
pour récupérer les données par morceaux de dimension appropriée.
NO_MODIFICATION_ALLOWED_ERR : Soulevée quand le nœud est en lecture seule. |
DOMSTRING_SIZE_ERR : Soulevée si cela devait retourner plus de caractères qu'un objet
|
length
de type unsigned long
,
en lecture seuledata
et de la méthode substringData
suivante. Cette valeur peut être nulle, c.à.d. que
les nœuds CharacterData
peuvent être vides.appendData
data
offre un accès à la concaténation de data
et de l'objet
DOMString
indiqué.
NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule. |
deleteData
data
et length
reflètent ce changement.
offset
of type unsigned long
count
of type unsigned long
offset
et count
excède la valeur de l'attribut length
, alors toutes les unités de 16 bits,
en partant de la position de décalage jusqu'au bout des données, sont supprimées.
INDEX_SIZE_ERR : Soulevée si le paramètre NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule. |
insertData
INDEX_SIZE_ERR : Soulevée si le paramètre NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule. |
replaceData
offset
de type unsigned long
count
de type unsigned long
offset
et
count
excède la valeur de l'attribut length
, alors toutes les unités de 16 bits jusqu'au bout des données
sont remplacées (c.à.d., l'effet produit est identique à celui de l'appel de la méthode remove
pour une même étendue
suivi d'une invocation de la méthode append
).arg
de type DOMString
DOMString
qui doit remplacer l'étendue de texte.
INDEX_SIZE_ERR : Soulevée si le paramètre NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule. |
substringData
offset
de type unsigned long
count
de type unsigned long
La sous-chaîne indiquée. Si la somme des paramètres |
INDEX_SIZE_ERR : Soulevée si le paramètre DOMSTRING_SIZE_ERR : Soulevée si l'étendue de texte indiquée ne tient pas dans un objet
|
L'interface Attr
représente un attribut dans un objet Element
.
Les valeurs admises pour l'attribut sont typiquement définies dans la définition de type de document.
Les objets Attr
héritent de l'interface Node
mais,
puisque ceux-ci ne sont pas effectivement des nœuds enfants de l'élément qu'ils décrivent,
le DOM ne les considère pas comme faisant partie de l'arbre du document. Les attributs parentNode
,
previousSibling
et nextSibling
d'un objet Node
ont donc une valeur null
pour les objets Attr
. Le DOM voit les attributs
comme des propriétés d'éléments plutôt que comme ayant une identité distincte des éléments auxquels ils sont associés ;
ceci devrait permettre une mise en œuvre plus efficace de caractéristiques telles que les valeurs par défaut des attributs
associées à tous les éléments d'un type donné. En outre, les nœuds Attr
ne peuvent pas être les enfants immédiats
d'un objet DocumentFragment
. Par contre, on peut les associer aux
nœuds Element
contenus dans un
objet DocumentFragment
. En bref, les utilisateurs et
développeurs DOM doivent savoir que les nœuds Attr
ont des points communs
avec les autres objets héritant de l'interface Node
mais ils s'en distinguent aussi beaucoup.
La valeur effective de l'attribut se détermine de la manière suivante :
si la valeur est affectée explicitement, alors c'est sa valeur effective ;
sinon, s'il existe une déclaration de cet attribut avec une valeur par défaut, alors c'est sa valeur effective ;
sinon l'attribut n'existe pas sur l'élément dans le modèle de structure tant qu'on ne l'a pas ajouté explicitement.
Remarquer qu'on peut aussi utiliser l'attribut nodeValue
sur l'instance Attr
pour récupérer la version littérale de la valeur, ou des valeurs, de l'attribut.
En XML, où la valeur d'un attribut peut contenir des appels d'entité, les nœuds enfants du
nœud Attr
peuvent contenir soit des nœuds Text
,
soit des nœuds EntityReference
(lorsqu'ils sont utilisés ;
cf. EntityReference
pour une explication). Comme DOM Core
ignore le type des attributs, toutes les valeurs d'attribut sont traitées comme de simples chaînes, même si la
définition de type de document (DTD), ou le schéma, les déclare comme étant d'un type atomique.
interface Attr : Node { readonly attribute DOMString name; readonly attribute boolean specified; attribute DOMString value; // soulève une exception DOMException à l'initialisation // Introduite dans DOM niveau 2 : readonly attribute Element ownerElement; };
name
de type DOMString
,
en lecture seuleownerElement
de type Element
, en lecture seule,
introduit dans DOM niveau 2Element
auquel cet attribut est lié, sinon la
valeur null
quand l'attribut n'est pas utilisé.specified
de type boolean
, en lecture seuletrue
;
sinon, la valeur false
. Remarquer que c'est la mise en œuvre qui prend en charge cet attribut, non l'utilisateur.
Si l'utilisateur change la valeur de l'attribut (même si cela revient à avoir une valeur identique à la valeur par défaut),
alors le drapeau specified
se met automatiquement à true
. Pour redéfinir
l'attribut avec la valeur par défaut de la définition de type de document (DTD), l'utilisateur doit supprimer l'attribut.
La mise en œuvre disposera alors un nouvel attribut, avec specified
mis à false
et la valeur par défaut
(s'il y en a une).specified
vaut true
et l'attribut
a cette valeur assignée ;specified
vaut false
et l'attribut prend cette valeur par défaut du DTD ;ownerElement
vaut null
(c.à.d., que l'attribut vient tout juste d'être
créé ou qu'il ait été mis à null
par des opérations de retrait ou de clonage diverses),
alors specified
vaut true
.value
de type DOMString
getAttribute
sur l'interface Element
.Text
est créé avec le contenu non analysé
de la chaîne. C'est-à-dire que tous les caractères qu'un processeur XML reconnaîtrait comme du balisage sont traités
à la place comme du texte littéral. Voir également la méthode setAttribute
sur
l'interface Element
.
NO_MODIFICATION_ALLOWED_ERR : Soulevée quand le nœud est en lecture seule. |
L'interface Element
représente un élément
dans un document HTML ou XML. Les éléments peuvent avoir des attributs associés ; comme l'interface
Element
hérite de celle de Node
, on peut utiliser l'attribut
générique attributes
de l'interface Node
pour récupérer le jeu de tous les attributs d'un élément. L'interface Element
possède des méthodes pour récupérer
par leur nom soit un objet Attr
, soit une valeur d'attribut.
En XML, où une valeur d'attribut peut contenir des appels d'entité, on devrait récupérer
un objet Attr
pour examiner le sous-arbre, qui peut être très complexe,
représentant la valeur d'attribut. En ce qui concerne HTML, où tous les attributs ont des valeurs de chaîne simples,
on peut utiliser par commodité
les méthodes d'accès direct à la valeur d'attribut en toute sécurité.
Remarque : Dans DOM niveau 2, la méthode normalize
est héritée de l'interface
Node
dans laquelle cette méthode a été déplacé.
interface Element : Node { readonly attribute DOMString tagName; DOMString getAttribute(in DOMString name); void setAttribute(in DOMString name, in DOMString value) raises(DOMException); void removeAttribute(in DOMString name) raises(DOMException); Attr getAttributeNode(in DOMString name); Attr setAttributeNode(in Attr newAttr) raises(DOMException); Attr removeAttributeNode(in Attr oldAttr) raises(DOMException); NodeList getElementsByTagName(in DOMString name); // Introduite dans DOM niveau 2 : DOMString getAttributeNS(in DOMString namespaceURI, in DOMString localName); // Introduite dans DOM niveau 2 : void setAttributeNS(in DOMString namespaceURI, in DOMString qualifiedName, in DOMString value) raises(DOMException); // Introduite dans DOM niveau 2 : void removeAttributeNS(in DOMString namespaceURI, in DOMString localName) raises(DOMException); // Introduite dans DOM niveau 2 : Attr getAttributeNodeNS(in DOMString namespaceURI, in DOMString localName); // Introduite dans DOM niveau 2 : Attr setAttributeNodeNS(in Attr newAttr) raises(DOMException); // Introduite dans DOM niveau 2 : NodeList getElementsByTagNameNS(in DOMString namespaceURI, in DOMString localName); // Introduite dans DOM niveau 2 : boolean hasAttribute(in DOMString name); // Introduite dans DOM niveau 2 : boolean hasAttributeNS(in DOMString namespaceURI, in DOMString localName); };
tagName
de type DOMString
,
en lecture seule<elementExemple id="demo"> ... </elementExemple> ,
tagName
a la valeur "elementExemple"
. Remarquer que la casse est préservée
en XML comme dans toutes les opérations DOM. Le DOM HTML retourne
l'attribut tagName
d'un élément HTML dans une forme canonique en majuscules,
quelle que soit la casse dans le document HTML source.getAttribute
getAttributeNS
introduit dans DOM niveau 2Selon [Les espaces de nommage dans XML],
les applications doivent utiliser la valeur null
comme paramètre namespaceURI
dans les méthodes
pour ne définir aucun espace de nommage.
namespaceURI
de type DOMString
localName
de type DOMString
NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas
la fonctionnalité "XML" et que le langage exposé au travers de l'interface |
getAttributeNode
getAttributeNodeNS
.
name
de type DOMString
nodeName
) de l'attribut à récupérer.getAttributeNodeNS
introduit dans DOM niveau 2Attr
par son nom local et
son adresse URI d'espace de nommage.
Selon [Les espaces de nommage dans XML],
les applications doivent utiliser la valeur null
comme paramètre namespaceURI
dans les méthodes
pour ne définir aucun espace de nommage.
namespaceURI
de type DOMString
localName
de type DOMString
NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas
la fonctionnalité "XML" et que le langage exposé au travers de l'interface |
getElementsByTagName
NodeList
de tous les nœuds
Element
descendants avec le nom de balise donné, dans
l'ordre où ils sont rencontrés dans la traversée préordonnée de l'arbre de cet Element
.
name
de type DOMString
Une liste de nœuds |
getElementsByTagNameNS
introduit dans DOM niveau 2NodeList
de tous les nœuds
Element
descendants avec un nom local et une adresse URI d'espace de nommage
donné, dans l'ordre où ils sont rencontrés dans la traversée préordonnée de l'arbre de cet Element
.namespaceURI
de type DOMString
localName
de type DOMString
hasAttribute
introduit dans DOM niveau 2true
quand un attribut avec un nom donné est indiqué
sur cet élément ou quand l'attribut a une valeur par défaut, sinon la valeur false
.
name
de type DOMString
|
La valeur |
hasAttributeNS
introduit dans DOM niveau 2true
quand un attribut avec un nom local et une adresse URI d'espace de nommage donnés
ou quand l'attribut a une valeur par défaut, sinon la valeur false
.
Selon [Les espaces de nommage dans XML],
les applications doivent utiliser la valeur null
comme paramètre namespaceURI
dans les méthodes
pour ne définir aucun espace de nommage.
namespaceURI
de type DOMString
localName
de type DOMString
|
La valeur |
NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas
la fonctionnalité "XML" et que le langage exposé au travers de l'interface |
removeAttribute
removeAttributeNS
.
Si l'attribut n'a pas de valeur indiquée ni de valeur par défaut, l'appel de cette méthode ne produit aucun effet.
name
de type DOMString
NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule. |
removeAttributeNS
introduit dans DOM niveau 2Selon [Les espaces de nommage dans XML],
les applications doivent utiliser la valeur null
comme paramètre namespaceURI
dans les méthodes
pour ne définir aucun espace de nommage.
errata : 2001-08-31
namespaceURI
de type DOMString
localName
de type DOMString
NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule. NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas
la fonctionnalité "XML" et que le langage exposé au travers de l'interface |
removeAttributeNode
Attr
retiré
a une valeur par défaut, il est immédiatement remplacé. L'attribut remplaçant a les mêmes adresse URI d'espace de nommage,
nom local et, le cas échéant, préfixe que l'original.
NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule. NOT_FOUND_ERR : Soulevée si |
setAttribute
value
. Cette valeur est une simple chaîne qui n'est pas analysée lors de l'initialisation.
Tout balisage (comme toute syntaxe devant représenter un appel d'entité) sera donc traité comme du texte littéral et nécessitera
un masquage adéquat par la mise en œuvre lors de son écriture. Pour affecter une valeur contenant des appels d'entité à un attribut,
l'utilisateur doit créer un nœud Attr
et tous les
nœuds Text
et EntityReference
nécessaires, construire le sous-arbre approprié et utiliser la méthode setAttributeNode
pour l'affecter
comme valeur d'attribut.setAttributeNS
.
INVALID_CHARACTER_ERR : Soulevée si le nom indiqué contient un caractère illégal. NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule. |
setAttributeNS
introduit dans DOM niveau 2qualifiedName
et sa valeur est pour celle du paramètre value
. Cette valeur est une simple chaîne qui n'est pas analysée
lors de l'initialisation. Tout balisage (comme toute syntaxe devant être reconnue comme un appel d'entité) sera donc traité comme du
texte littéral et nécessitera un masquage adéquat par la mise en œuvre lors de son écriture.
Pour affecter une valeur d'attribut contenant des appels d'entité à un attribut, l'utilisateur doit créer un nœud
Attr
et tous les nœuds Text
et EntityReference
nécessaires, construire le sous-arbre approprié
et utiliser la méthode setAttributeNodeNS
, ou setAttributeNode
, pour l'assigner comme valeur de l'attribut.Selon [Les espaces de nommage dans XML],
les applications doivent utiliser la valeur null
comme paramètre namespaceURI
dans les méthodes
pour ne définir aucun espace de nommage.
namespaceURI
de type DOMString
qualifiedName
de type DOMString
value
de type DOMString
INVALID_CHARACTER_ERR : Soulevée si le nom qualifié indiqué contient un caractère illégal selon la spécification XML 1.0 [XML]. NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule. NAMESPACE_ERR : Soulevée si NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas
la fonctionnalité "XML" et que le langage exposé au travers de l'interface |
setAttributeNode
nodeName
) est déjà
présent dans l'élément, il est remplacé par le nouveau.setAttributeNodeNS
.
Le remplacement d'un nœud d'attribut par lui-même n'a aucun effet.
WRONG_DOCUMENT_ERR : Soulevée si NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule. INUSE_ATTRIBUTE_ERR : Soulevée si |
setAttributeNodeNS
introduit dans DOM niveau 2Selon [Les espaces de nommage dans XML],
les applications doivent utiliser la valeur null
comme paramètre namespaceURI
dans les méthodes
pour ne définir aucun espace de nommage.
errata : 2002-02-14
Si |
WRONG_DOCUMENT_ERR : Soulevée si le paramètre NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule. INUSE_ATTRIBUTE_ERR : Soulevée si NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas
la fonctionnalité "XML" et que le langage exposé au travers de l'interface |
L'interface Text
hérite de CharacterData
et représente le contenu textuel
(appelé données textuelles →vf
en XML) d'un nœud Element
ou Attr
. S'il n'y aucun balisage dans le contenu de l'élément,
le texte se tient dans un seul objet mettant en œuvre l'interface Text
qui est alors le seul enfant de l'élément.
S'il y a un balisage, celui-ci est analysé dans les nœuds items d'information
(éléments, commentaires, etc.) et Text
qui forment la liste des enfants de l'élément.
Pour la première disponibilité d'un document via le DOM, il n'y a qu'un seul nœud Text
pour chaque bloc de texte. Les utilisateurs peuvent créer des nœuds Text
adjacents qui représentent
le contenu d'un élément donné sans balisage intermédiaire, mais ils devraient tenir compte du fait qu'il n'existe aucun moyen
de représenter les séparations entre ces nœuds en XML ou HTML, et ils ne persisteront donc pas
(en général) entre des sessions d'édition du DOM. La méthode normalize()
de l'interface Node
fusionne ces objets Text
adjacents
en un seul nœud pour chaque bloc de texte.
interface Text : CharacterData { Text splitText(in unsigned long offset) raises(DOMException); };
splitText
offset
indiquée,
en gardant ces deux nœuds dans l'arbre en tant que frères.
Après le partage, ce nœud conservera tout le contenu juqu'à la position de décalage offset
.
Un nouveau nœud du même type, avec tout le contenu depuis la position de décalage offset
et après, est retourné.
Si le nœud original a un nœud parent, le nouveau nœud est inséré
comme frère suivant du nœud original. Si la valeur du
paramètre offset
est égale à la longueur de ce nœud, le nouveau nœud ne contient aucune donnée.
offset
of type unsigned long
Le nouveau nœud du même type que le nœud partagé. |
INDEX_SIZE_ERR : Soulevée si le décalage indiqué est négatif ou supérieur au nombre d'unités de 16 bits du paramètre NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule. |
Cette interface hérite de CharacterData
et représente le
contenu d'un commentaire, c.à.d., tous les caractères entre la balise ouvrante
et la balise fermante <!--
. Remarquer que c'est la définition d'un commentaire dans XML
et, en pratique, dans HTML, quoique certains outils HTML puissent mettre en œuvre
la structure de commentaire SGML complète.-->
interface Comment : CharacterData { };
Les interfaces définies ici forme un sous-ensemble de la spécification du DOM Core ; néanmoins, les objets
qui exposent ces interfaces ne se rencontreront jamais dans une mise en œuvre DOM qui se rapporte seulement
à HTML. Ainsi, les mises en œuvre DOM seulement HTML [DOM niveau 2 HTML]
ne sont pas tenues de produire des objets pour mettre en œuvre ces interfaces.
Les interfaces dans cette section ne sont pas obligatoires. Une application DOM peut employer la méthode
hasFeature(feature, version)
de l'interface DOMImplementation
,
respectivement avec les valeurs de paramètre "XML" et "2.0", pour déterminer si ce module est géré ou non par la mise en œuvre.
Pour la gestion complète de ce module, une mise en œuvre doit également gérer la fonctionnalité "Core",
définie dans la section Les interfaces fondamentales.
Cf. d'autres informations à propos de la conformité dans cette spécification.
On utilise les sections CDATA pour masquer des blocs de texte contenant des caractères qui seraient regardés
comme du balisage sinon. Le seul délimiteur qui soit reconnu dans une section CDATA est la chaîne
]]>
qui clôt la section CDATA en question. Les sections CDATA ne peuvent pas s'imbriquer. Leur but premier est d'inclure
des documents tels que des fragments XML
sans avoir besoin de masquer tous les délimiteurs.
L'attribut DOMString
du nœud Text
contient le texte qui apparaît dans la section CDATA. Remarquer que celui-ci est susceptible de contenir des
caractères nécessitant un masquage en-dehors des sections CDATA et que, selon le codage de caractères ("charset")
choisi pour la sérialisation, il peut être impossible d'écrire certains caractères dans une section CDATA.
L'interface CDATASection
hérite de l'interface CharacterData
au travers de l'interface Text
. Les nœuds CDATASection
adjacents ne sont pas fusionnés par la méthode normalize
de l'interface Node
.
Remarque : Puisqu'aucun balisage n'est reconnu dans un nœud CDATASection
,
on ne peut pas utiliser les appels numériques de caractère comme mécanisme de masquage pour une sérialisation.
Il faudra donc prendre des mesures lors de la sérialisation d'un nœud CDATASection
ayant un codage de caractères
avec lequel certains des caractères qui y sont contenus ne pourront pas être représentés. Ne pas le faire conduirait à un
code XML qui ne sera pas bien formé.
Une solution possible au cours du processus de sérialisation consisterait à clôre la section CDATA juste avant le caractère,
à sortir le caractère en utilisant un appel de caractère ou d'entité puis à ouvrir une nouvelle section CDATA
pour les caractères suivants du nœud de texte. Au moment de la rédaction, remarquer néanmoins que certaines bibliothèques
de conversion de code ne retournent pas de condition d'erreur ou d'exception lorsqu'un caractère manque dans le codage,
ce qui rend plus difficile la tâche de garantir la non-corruption des données dans une sérialisation.
interface CDATASection : Text { };
Chaque objet Document
possède un attribut doctype
dont la valeur est
soit null
, soit un objet DocumentType
. L'interface DocumentType
du DOM Core
fournit une interface pour la liste des entités définies pour ce document et pas tellement plus, dans la mesure où les effets
des espaces de nommage et des divers travaux sur les schémas XML sur la représentation des DTD
ne sont pas encore clairement appréhendés au moment de la rédaction de cette spécification.
Le DOM niveau 2 ne gère pas l'édition des nœuds DocumentType
.
Les nœuds DocumentType
sont en lecture seule.
interface DocumentType : Node { readonly attribute DOMString name; readonly attribute NamedNodeMap entities; readonly attribute NamedNodeMap notations; // Introduite dans DOM niveau 2 : readonly attribute DOMString publicId; // Introduite dans DOM niveau 2 : readonly attribute DOMString systemId; // Introduite dans DOM niveau 2 : readonly attribute DOMString internalSubset; };
entities
de type NamedNodeMap
,
en lecture seuleNamedNodeMap
contenant les entités générales,
celles externes comme celles internes, déclarées dans le DTD. Les entités de paramètre ne s'y trouvent pas.
Les doublons sont écartés. Par exemple :
<!DOCTYPE ex SYSTEM "ex.dtd" [ <!ENTITY truc "truc"> <!ENTITY muche "muche"> <!ENTITY muche "muche2"> <!ENTITY % mache "mache"> ]> <ex/>
truc
et la première déclaration de l'entité muche
mais pas à la seconde déclaration de muche
ni à celle de mache
.
Chaque nœud de cette carte met en œuvre également l'interface Entity
.entities
.internalSubset
de type DOMString
,
en lecture seule, introduit dans DOM niveau 2null
s'il n'y en a pas. Les crochets de délimitation ne sont pas compris.
Remarque : Le contenu réel retourné dépend de la quantité d'informations dont dispose la mise en œuvre. Elle peut varier en fonction de divers paramètres, y compris le processeur XML utilisé pour construire le document.
name
de type DOMString
,
en lecture seuleDOCTYPE
.notations
de type NamedNodeMap
,
en lecture seuleNamedNodeMap
contenant les notations déclarées dans le DTD.
Les doublons sont écartés. Chaque nœud de cette carte met également en œuvre
l'interface Notation
.notations
.publicId
de type DOMString
,
en lecture seule, introduit dans DOM niveau 2systemId
de type DOMString
,
en lecture seule, introduit dans DOM niveau 2Cette interface représente une notation déclarée dans la définition de type de document (DTD).
Une notation déclare, par le nom, le format d'une entité non-analysable (cf. la
section 4.7 →vf
de la spécification XML 1.0 [XML]) ou bien sert à déclarer formellement
des cibles d'instruction de traitement (cf. la
section 2.6 →vf
de la spécification XML 1.0 [XML]).
L'attribut nodeName
, hérité de Node
, prend le nom déclaré de la notation.
Comme le DOM niveau 1 ne permet pas l'édition des nœuds Notation
, ils sont donc
en lecture seule.
Un nœud Notation
n'a aucun parent.
interface Notation : Node { readonly attribute DOMString publicId; readonly attribute DOMString systemId; };
Cette interface représente une entité, analysable ou non, dans un document XML. Remarquer qu'elle modélise
l'entité en question et non la déclaration d'entité. La modélisation de la déclaration d'un objet Entity
est laissée pour un niveau ultérieur de la spécification du DOM.
L'attribut nodeName
, héritée de Node
, contient le nom de l'entité.
Un processeur XML peut choisir de résoudre complètement les entités avant que le passage du modèle de structure
au DOM ; auquel cas, il n'y aura pas de nœuds EntityReference
dans l'arbre du document.
XML n'impose pas à un processeur XML non validant de lire et traiter les
déclarations d'entités effectuées dans le sous-ensemble externe ou dans des entités de paramètre externe.
Cela signifie que les entités analysables, déclarées dans le sous-ensemble externe, n'auront pas besoin d'être résolues
par certaines classes d'application et que
la valeur de remplacement
le texte de remplacement de l'entité pourra être indisponible.
Lorsque la valeur de remplacement
le texte de remplacement →vf
est disponible, la liste enfant du nœud Entity
correspondant représente la structure de
ce texte de remplacement
cette valeur de remplacement. Sinon la liste enfant est vide.
Le DOM niveau 2 ne permet pas l'édition des nœuds Entity
; si un utilisateur veut apporter
des changements au contenu d'un nœud Entity
,
chaque nœud EntityReference
concerné doit être remplacé dans le
modèle de structure par un clonage du contenu de Entity
puis on doit effectuer à la place les changements voulus
sur chacun des éléments clonés. Les nœuds Entity
et tous leurs descendants
sont en lecture seule.
Un nœud Entity
n'a aucun parent.
Remarque : Si l'entité contient un préfixe d'espace de nommage non lié,
l'attribut namespaceURI
du nœud correspondant dans le sous-arbre du nœud Entity
a la valeur null
.
Cela est également vrai pour les nœuds EntityReference
qui se rapportent
à cette entité lorsqu'ils sont créés par la méthode createEntityReference
de
l'interface Document
.
Le DOM niveau 2 n'offre aucun mécanisme de résolution des préfixes d'espace de nommage.
interface Entity : Node { readonly attribute DOMString publicId; readonly attribute DOMString systemId; readonly attribute DOMString notationName; };
notationName
de type DOMString
,
en lecture seulenull
.publicId
de type DOMString
,
en lecture seulenull
.systemId
de type DOMString
,
en lecture seulenull
.
Il peut s'agir d'une adresse URI absolue ou non.
Les objets EntityReference
peuvent s'insérer dans le modèle de structure quand un appel d'entité se trouve
dans le document source ou quand l'utilisateur souhaite insérer un appel d'entité. Remarquer que les appels de caractères et
d'entités prédéfinies sont censés être résolus par le processeur HTML, ou XML ; les caractères
sont donc représentés par leur équivalent Unicode et non par un appel d'entité. En outre, le processeur XML
peut résoudre en totalité les appels d'entités lors de la construction du modèle de structure, au lieu de fournir des
objets EntityReference
. S'il ne les fournit pas, alors, pour un nœud EntityReference
donné,
il se peut qu'il n'y ait aucun nœud Entity
pour représenter l'entité appelée.
Si un tel nœud Entity
existe, alors le sous-arbre du nœud
EntityReference
est en général une copie du sous-arbre du nœud
Entity
. Par contre, cela ne se vérifie pas forcément
lorsqu'une entité contient un préfixe d'espace de nommage non lié.
Dans ce cas, puisque la résolution du préfixe d'espace de nommage dépend de la position de l'appel d'entité,
les descendants du nœud EntityReference
peuvent être liés à des
adresses URI d'espaces de nommage différentes.
Comme pour les nœuds Entity
, les nœuds EntityReference
et tous leurs descendants sont
en lecture seule.
interface EntityReference : Node { };
L'interface ProcessingInstruction
représente une instruction de traitement
utilisée en XML
pour conserver une information spécifique pour le processeur dans le texte du document.
interface ProcessingInstruction : Node { readonly attribute DOMString target; attribute DOMString data; // soulève une exception DOMException à l'initialisation };
data
de type DOMString
?>
.
NO_MODIFICATION_ALLOWED_ERR : Soulevée quand le nœud est en lecture seule. |
target
de type DOMString
,
en lecture seule