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, EntityReferenceDocumentType -- aucun enfantEntityReference -- Element,
ProcessingInstruction, Comment,
Text, CDATASection,
EntityReferenceElement -- Element,
Text, Comment,
ProcessingInstruction, CDATASection,
EntityReferenceAttr -- Text,
EntityReferenceProcessingInstruction -- aucun enfantComment -- aucun enfantText -- aucun enfantCDATASection -- aucun enfantEntity -- Element,
ProcessingInstruction, Comment,
Text, CDATASection,
EntityReferenceNotation -- 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.
DOMStringPour 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.
DOMTimeStampPour 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_ERRHIERARCHY_REQUEST_ERRINDEX_SIZE_ERRINUSE_ATTRIBUTE_ERRINVALID_ACCESS_ERR, introduit dans DOM niveau 2.INVALID_CHARACTER_ERRINVALID_MODIFICATION_ERR, introduit dans DOM niveau 2.INVALID_STATE_ERR, introduit dans DOM niveau 2.NAMESPACE_ERR, introduit dans DOM niveau 2.NOT_FOUND_ERRNOT_SUPPORTED_ERRNO_DATA_ALLOWED_ERRNO_MODIFICATION_ALLOWED_ERRSYNTAX_ERR, introduit dans DOM niveau 2.WRONG_DOCUMENT_ERRL'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 DOMStringqualifiedName de type DOMStringdoctype de type DocumentTypenull.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 DOMStringpublicId de type DOMStringsystemId 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 |
hasFeaturefeature de type DOMStringversion de type DOMStringnull 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.createAttributeAttr 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 DOMStringqualifiedName 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 |
createCDATASectionCDATASection dont la valeur est
la chaîne indiquée.
data de type DOMStringCDATASection.|
Le nouvel objet |
|
NOT_SUPPORTED_ERR : Soulevée s'il s'agit d'un document HTML. |
createCommentcreateDocumentFragmentDocumentFragment vide.
|
Un nouveau |
createElementElement, 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 DOMStringtagName, 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 DOMStringqualifiedName 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 |
createEntityReferenceEntityReference. 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. |
createProcessingInstructionProcessingInstruction 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. |
createTextNodegetElementById 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 DOMStringid unique d'un élément.|
L'élément correspondant. |
getElementsByTagNameNodeList 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 DOMStringgetElementsByTagNameNS 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 DOMStringlocalName 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 Nodedeep de type booleantrue, 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_NODEAttr.CDATA_SECTION_NODECDATASection.COMMENT_NODEComment.DOCUMENT_FRAGMENT_NODEDocumentFragment.DOCUMENT_NODEDocument.DOCUMENT_TYPE_NODEDocumentType.ELEMENT_NODEElement.ENTITY_NODEEntity.ENTITY_REFERENCE_NODEEntityReference.NOTATION_NODENotation.PROCESSING_INSTRUCTION_NODEProcessingInstruction.TEXT_NODEText.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 DOMStringnull, 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.appendChildnewChild à 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 NodeDocumentFragment, 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. |
cloneNodeparentNode 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 booleantrue, 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|
|
|
insertBeforenewChild 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 DOMStringhasFeature de l'interface DOMImplementation.version de type DOMStringtrue.|
|
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.
removeChildoldChild 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 |
replaceChildoldChild 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.itemindex 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.getNamedItemgetNamedItemNS 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 DOMStringlocalName 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 |
itemindex 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 |
removeNamedItemname de type DOMStringnodeName 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 DOMStringlocalName 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 |
setNamedItemnodeName. 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 NodenodeName.|
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 NodenamespaceURI 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 DOMStringCharacterData.
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.appendDatadata 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. |
deleteDatadata et length reflètent ce changement.
offset of type unsigned longcount of type unsigned longoffset 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. |
replaceDataoffset de type unsigned longcount de type unsigned longoffset 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 DOMStringDOMString 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. |
substringDataoffset de type unsigned longcount 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 DOMStringgetAttribute 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.getAttributegetAttributeNS 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 DOMStringlocalName 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 |
getAttributeNodegetAttributeNodeNS.
name de type DOMStringnodeName) 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 DOMStringlocalName 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 |
getElementsByTagNameNodeList 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 DOMStringlocalName de type DOMStringhasAttribute 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 DOMStringlocalName 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 |
removeAttributeremoveAttributeNS.
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 DOMStringlocalName 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 |
removeAttributeNodeAttr 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 |
setAttributevalue. 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 DOMStringqualifiedName de type DOMStringvalue 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 |
setAttributeNodenodeName) 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);
};
splitTextoffset 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