|
|
|
|
|
|
|
この節は、文書オブジェクトにアクセスしたり操作するためのオブジェクトやインターフェイスの最小限のセットを定義する。この節で仕様化されている機能(コア機能)は、ソフトウェア開発者やウェブスクリプト制作者が、解析されたHTMLおよびXML内容を適合的な製品の内部でアクセスしたり操作したりできるようにするのに充分なはずである。DOMコアAPIもまた、DOM API呼び出しだけを使った Document オブジェクトの入植を可能にする。スケルトン Document を作成し、それを永続的に保存することは、DOM APIを実装する製品に任される。
DOMは文書を、より特化した他のインターフェイスを実装もする Node オブジェクトの階層構造として表わす。ノード型の中には多様な型の子ノードをもってよいものもあるし、文書構造内でその下に何ももつことができないリーフノードであるものもある。ノード型や、それらが子としてもってよいノード型は、以下の通りである。
Document -- Element(最大で1つ), ProcessingInstruction, Comment, DocumentType
DocumentFragment -- Element, ProcessingInstruction, Comment, Text, CDATASection, EntityReference
DocumentType -- 子をもたない
EntityReference -- Element, ProcessingInstruction, Comment, Text, CDATASection, EntityReference
Element -- Element, Text, Comment, ProcessingInstruction, CDATASection, EntityReference
Attr -- Text, EntityReference
ProcessingInstruction -- 子をもたない
Comment -- 子をもたない
Text -- 子をもたない
CDATASection -- 子をもたない
Entity -- Element, ProcessingInstruction, Comment, Text, CDATASection, EntityReference
Notation -- 子をもたない
DOMはまた、Node の子や Element.getElementsByTagName メソッドにより返される要素といったようなノードの順序つきリストを処理するための NodeList インターフェイスや、Element の属性といったような、それらの name 属性により参照されるノードの順序なしセットを処理するための NamedNodeMap インターフェイスも仕様化する。DOMの NodeList や NamedNodeMap は「生き」ている、すなわち基礎にある文書構造への変更が関連するすべての NodeList や NamedNodeMap に反映される。たとえば、DOMユーザが、ある Element の子を含んでいる NodeList オブジェクトを取得し、その後にその要素にもっと多くの子を追加(または子を除去または修正)すれば、それらの変更は、ユーザの側でさらなるアクションがなくとも NodeList に自動的に反映されるのである。同様に、樹の中の Node への変更は、NodeList や NamedNodeMap 内にあるそのノードへの参照すべてで反映される。
この仕様書によって定義されるAPIのほとんどは、クラスというよりもインターフェイスである。それは、実際の実装は、定義された名前と規定された操作とだけしか露出する必要がなく、インターフェイスに直接に対応するクラスを実際に実装する必要はないという意味である。このことは、独自のデータ構造をもつ伝統的なアプリケーションの頂上や、異なるクラス階層構造をもつ新しいアプリケーションの頂上に、DOM APIを薄い化粧板として実装できるようにする。これはまた、通常の(Java や C++ の意味での)コンストラクタは、DOMオブジェクトを作成するために使うことができないという意味でもある。なぜなら、構築されるべき基礎にあるオブジェクトはDOMインターフェイスとほとんど関係をもたない場合があるからである。オブジェクト指向設計においてこれに対する伝統的な解決策は、その多様なインターフェイスを実装するオブジェクトのインスタンスを作成するファクトリーメソッドを定義することである。DOM1では、ある "X" というインターフェイスを実装しているオブジェクトは、Document インターフェイス上の "createX()" メソッドにより作成される。これは、DOMオブジェクトはすべて、特定の Document の文脈の中で生きるからである。
DOM1APIは、DOMImplementation や Document オブジェクトを作成するための標準的な方法を定義しない。実際のDOM実装は、これらのDOMインターフェイスをブートストラップするための専用の方法を提供しなければならず、そうして他のすべてのオブジェクトが Document上の Create メソッドから(またはその他多様な簡便メソッドにより)構築できるのである。
コアDOM APIは、一般的なユーザスクリプト言語も、大抵はプロのプログラマによって使われるより挑戦的な言語も含め、広範な言語と互換的であるように設計されている。そこで、DOM APIは、多様なメモリ管理哲学にわたり動作する必要がある。メモリ管理をユーザに全く露出しない言語プラットフォームから、明示的なコンストラクタを提供するが、不用メモリを自動的に回収するための自動ガベージコレクション機能を提供するもの(特に Java)を通って、プログラマがオブジェクトメモリを明示的に割り当て、それがどこで使われているかを追跡し、再利用のためにそれを明示的に解放する必要があるもの(特に C や C++)にまでわたるのである。これらのプラットフォームにわたって一貫性のあるAPIを確保するため、DOMはメモリ管理の問題に全く関わらず、代わりにこれを実装に委ねている。DOMワーキンググループによって開発された明示的な言語バインディング(ECMAScript や Java)はどれも何らメモリ管理メソッドを要求しないが、その他の言語(特に C や C++)DOMバインディングはおそらくそうしたサポートを要求することになる。これらの拡張は、DOM APIを特定の言語に適合させる者の責任であって、DOMワーキンググループの責任ではないことになる。
短くて情報的であり、内部的に一貫性があって類似のAPIのユーザに馴染みのある属性名やメソッド名をもつことはよいかもしれないが、DOM実装によりサポートされる伝統的なAPIの名前と衝突を起こすべきでもない。さらに、OMG IDLと ECMAScript とはともに、異なるネームスペースからの名前を曖昧さがないように区別する能力に制約があり、そのため短くて馴染みのある名前では命名の衝突を避けることが難しい。そこで、DOMの名前は、すべての環境にわたって一意的であるように、長くてとても説明的なものとなる傾向がある。
ワーキンググループは、他のAPIでは一般的な区別ではないものの、多様な用語の利用において内部的に一貫性があるようにも試みている。たとえば、我々は、メソッドが構造モデルを変更するときには "remove" というメソッド名を使い、メソッドが構造モデル内部にあるものを取り除くときには "delete" というメソッド名を使う。delete されたものは返されない。remove されたものは、それを返すことに意味があるときには、返される場合がある。
DOMコアAPIは、XML文書およびHTML文書へのインターフェイスについて、いくぶん異なった2つのセットを提示する。継承の階層構造をもつ「オブジェクト指向」アプローチを表わすものと、すべての操作を、 (Java やその他の C 風言語の)キャストや、COM環境のクエリーインターフェイスの呼び出しを要求することなく、インターフェイス内の Node を経由してできるようにする「単純化された」ビューとである。これらの操作は、Java やCOMにおいては相当に高くつき、DOMは性能が決定的要因である環境で使われる場合があるので、我々は、単なる Node インターフェイスを使う重要な機能を認める。他の多くのユーザは、「なんでも Node」というDOMへのアプローチよりも、継承の階層構造の方が理解しやすいと思うであろうから、我々は、よりオブジェクト指向的なAPIを好むユーザのためにより高水準の完全なインターフェイスもサポートする。
実際には、これは、APIに一定量の冗長性があることを意味する。ワーキンググループは、「継承」アプローチをAPIの主要なビューであり、Node 上のフルセットの機能はユーザが利用してもよい「補充的」機能であるとみなすが、それは、オブジェクト指向的な分析が探知するような他のインターフェイス上のメソッドの必要性を消し去るものではない。(もちろん、O-O 分析が Node インターフェイス上のものと同一の属性やメソッドを生み出すときに、我々は完全な余分なものまで仕様化するわけではない。) そこで、Node インターフェイス上に一般的な nodeName 属性がある場合であっても、Element インターフェイス上にはなお tagName 属性があるのである。これら2つの属性は同じ値をもたなければならないが、ワーキンググループは、DOM APIが満足させなければならない異なる支持基盤が与えられる以上、両方をサポートする意味があると考える。
DOMString 型
相互運用性を確保するため、DOMは DOMString を以下のように仕様化する。
DOMString は、16ビット量の物の連なりである。これはIDL用語では
typedef sequence<unsigned short> DOMString;
と表現してよい。
DOMString をエンコードしなければならない。UTF-16 エンコーディングが選ばれたのは、広く普及した工業的慣習だからである。HTMLについてもXMLについてもともに文書キャラクタセット(したがって数的キャラクタ参照の表記法も)は UCS-4 に基づいていることに注意すること。したがって、ソース文書内の単一の数的キャラクタ参照は、ある場合には DOMString 内の2つの配列位置(高サロゲートと低サロゲート)に対応する場合がある。注意: DOMは、文字列型の名前を DOMString と定義するが、バインディングは違った名前を使ってもよい。たとえば、Java を例にとると、DOMString は String 型へ結ばれる。それもそのエンコーディングとして UTF-16 を使っているからである。wstring 型を含んでいた。しかしながら、これはキャラクタ幅を決定するためのエンコーディング=ネゴシエーションに依存するので、その定義はDOM APIの相互運用性基準に合致しなかったのである。
DOMは、文字列照合を含んでいるインターフェイスを数多くもっている。HTMLプロセッサは一般的に要素といったようなものの名前を大文字(まれに小文字)に標準化することを想定するが、XMLは大文字小文字の区別があることが明示されている。DOMの目的のため、文字列照合は、キャラクタコード対キャラクタコードのベースで、DOMString の16ビット値に関して発生する。そうしたものとして、DOMは、DOM構造が構築される前に、プロセッサにおいて何らかの標準化がおこるものと想定する。
これは、厳密にどのような標準化が発生するかについての問題を生じさせる。W3CのI18Nワーキンググループは、DOMを実装しているアプリケーションにとって厳密にはどのような標準化が必要であるかを定義する過程にある。
この節にあるインターフェイスは基本的なものとみなされ、すべてのHTML DOMを含め、DOMの適合的な実装すべてにより完全に実装されなければならない。
DOMオペレーションは、「例外的」環境、すなわちオペレーションが(論理的理由や、データが失われているとか、実装が不安定になっているせいで)実行できないときにには、例外を発生させるだけである。一般的に、DOMメソッド処理は通常の状況では、NodeList を使ったときの境界外エラーといったような、特定のエラー値を返す。
実装は、他の環境の下では他の例外を発生させる場合がある。たとえば、null 引数が渡されれば、実装は実装依存の例外を発生させる場合がある。
言語やオブジェクトシステムの中には、例外の概念をサポートしないものがある。そうしたシステムについては、エラー条件はは、ネイティブなエラー報告機構を使って示される。たとえばいくつかのバインディングについては、メソッドが、応当するメソッドの解説の中に列挙されているものに似たエラーコードを返す場合がある。
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;
エラーの型を示す整数が生成される。
| INDEX_SIZE_ERR |
添え字またはサイズが負であるか、許容値よりも大きい場合。 |
| DOMSTRING_SIZE_ERR |
指定された範囲のテキストが1つの DOMString に収まらない場合。 |
| HIERARCHY_REQUEST_ERR |
ノードの属さない箇所にノードが挿入された場合。 |
| WRONG_DOCUMENT_ERR |
ノードを作成した文書と異なる(そのノードをサポートしない)文書でノードが使われた場合。 |
| INVALID_CHARACTER_ERR |
名前の中などで、不当なキャラクタが指定された場合。 |
| NO_DATA_ALLOWED_ERR |
データをサポートしないノードにデータが指定された場合。 |
| NO_MODIFICATION_ALLOWED_ERR |
修正が許されないオブジェクトを修正しようと試みられた場合。 |
| NOT_FOUND_ERR |
ノードが存在しない文脈でそのノードを参照しようと試みられた場合。 |
| NOT_SUPPORTED_ERR |
実装が、要求されたオブジェクトの型をサポートしない場合。 |
| INUSE_ATTRIBUTE_ERR |
既に他の箇所で利用されている属性を追加しようと試みられた場合。 |
DOMImplementation インターフェイスは、文書オブジェクトモデルの特定のインスタンスに依存しないオペレーションを実行するための多数のメソッドを提供する。
DOM1は、文書インスタンスを作成する方法を指定せず、このため文書の作成は実装特有のオペレーションである。将来の水準のDOM仕様書は、文書を直接に作成するためのメソッドが提供されるものと期待される。
interface DOMImplementation {
boolean hasFeature(in DOMString feature,
in DOMString version);
};
hasFeature
feature
|
テストするべき機能のパッケージ名。第1水準では、合法な値は "HTML" と "XML" とである(大文字小文字は問わない)。 |
|
version
|
これはテストするべきパッケージ名のバージョン番号である。第1水準では、これは "1.0" という文字列である。バージョンが指定されない場合は、その機能がどれかのバージョンでサポートされていればメソッドは |
true、それ以外の場合は false。
DocumentFragment は、「軽量」または「最小限」の Document オブジェクトである。ある文書の樹の一部分を抜き出せたり、文書の新しいフラグメントを作成できたりすることを望むのはとてもよくあることである。フラグメントを移動させることで文書の切り張りのようなユーザコマンドを実装することを考えてみよ。そうしたフラグメントを保持できるオブジェクトをもつことは望ましいことであり、この目的のために Node を使うということはごく当然である。Document オブジェクトもこの役割を果たしうるのは確かであるが、Document オブジェクトは、基礎にある実装次第で潜在的に重いオブジェクトとなりうるのである。このことのために本当に必要とされるのは、ごく軽量のオブジェクトである。DocumentFragment はそうしたオブジェクトである。
さらに、多様なオペレーション -- ノードを他の Node の子として挿入するといったようなもの -- が、DocumentFragment オブジェクトを引数としてとってよい。これは、DocumentFragment の子ノードすべてを、このノードの子リストへ動かす。
DocumentFragment ノードの子は、文書の構造を定義するサブツリーの頂上を表わす0個以上のノードである。DocumentFragment ノードは整形式のXML文書である必要はない(整形式の解析されるXMLエンティティに課された規則に従う必要はあり、複数のトップノードを持つことができるが)。たとえば、DocumentFragment がもってよい子は1つだけであり、その子ノードは Text ノードであってもよい。そうした構造モデルは、HTML文書や整形式のXML文書を表わすものではない。
DocumentFragment が Document(または実際は子を取ってよいその他の Node どれでも)に挿入されるとき、その Node に挿入されるのは、DocumentFragment の子であって、DocumentFragment そのものではない。ユーザが兄弟であるノードを作成しようと思うときには、このことは DocumentFragment をとても便利なものにする。DocumentFragment はこれらのノードの親として行動し、ユーザは insertBefore() や appendChild() といったような Node インターフェイスからの標準的なメソッドを使うことができるのである。
interface DocumentFragment : Node {
};
Document インターフェイスは、HTML文書またはXML文書の全体を表わす。概念的には、これは文書樹のルートであり、その文書のデータへの主要なアクセスを提供する。
要素、テキストノード、注釈、処理命令などは Document の文脈の外側では存在しえないから、Document インターフェイスはこれらのオブジェクトを作成するために必要なファクトリーメソッドも含む。Node オブジェクトは ownerDocument 属性をもつ。これは、オブジェクトを、それが作成された文脈の Document と結びつけるものである。
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);
};
doctype
DocumentType を見ること)。HTML文書や文書型宣言のないXML文書については、これは null を返す。DOM1は文書型宣言の編集をサポートせず、ゆえに docType はどのようにしても変更できない。
implementation
DOMImplementation オブジェクト。DOMアプリケーションは、複数の実装からのオブジェクトを使ってもよい。
documentElement
createElement
tagName
|
インスタンス化するべき要素型の名前。XMLについては、これは大文字小文字の区別がある。HTMLについては、 |
Element オブジェクト。
DOMException
INVALID_CHARACTER_ERR: 指定された名前に不当なキャラクタが含まれている場合に発生する。
createDocumentFragment
createTextNode
createComment
createCDATASection
CDATASection ノードを作成する。
data
|
|
CDATASection オブジェクト。
DOMException
NOT_SUPPORTED_ERR: この文書がHTML文書である場合に発生する。
createProcessingInstruction
ProcessingInstruction ノードを作成する。
target
|
処理命令のターゲット部分。 |
|
data
|
ノードのデータ。 |
ProcessingInstruction オブジェクト。
DOMException
INVALID_CHARACTER_ERR: 不当な値が指定された場合に発生する。
NOT_SUPPORTED_ERR: この文書がHTML文書である場合に発生する。
createAttribute
Attr を作成する。Attr インスタンスは後で setAttribute メソッドを使って設定できることに注意すること。
name
|
属性の名前。 |
Attr オブジェクト。
DOMException
INVALID_CHARACTER_ERR: 不当なキャラクタが指定された名前に含まれている場合に発生する。
createEntityReference
name
|
参照すべきエンティティの名前。 |
EntityReference オブジェクト。
DOMException
INVALID_CHARACTER_ERR: 指定された名前に不当なキャラクタが含まれている場合に発生する。
NOT_SUPPORTED_ERR: この文書がHTML文書である場合に発生する。
getElementsByTagName
Node インターフェイスは、DOM全体にとって主要なデータ型である。これは、文書樹の中にある単一のノードを表わす。Node インターフェイスを実装するオブジェクトはすべて、子を扱うためのメソッドを露出するが、Node インターフェイスを実装するオブジェクトのすべてが子をもってよいとは限らない。たとえば、Text ノードは子をもってはならず、そうしたノードに子を追加すれば DOMException を発生させることになる。
nodeName 属性、nodeValue 属性、および attributes は、引き出された特定のインターフェイスへのキャストダウンなしにノード情報をつかむための機構として組み込まれる。特定の nodeType にこれらの属性の明確な割り付けがない場合(例. Element の nodeValue や Comment の attributes)には、これは null を返す。特化されたインターフェイスは関連する情報を取得したり設定するためより簡便な追加的機構を含む場合があることに注意すること。
interface Node {
// NodeType
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;
// 設定時に DOMException を発生させる。
// 取出し時に DOMException を発生させる。
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;
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);
};
これがどのノード型であるかを示す整数。
| ELEMENT_NODE |
ノードは |
| ATTRIBUTE_NODE |
ノードは |
| TEXT_NODE |
ノードは |
| CDATA_SECTION_NODE |
ノードは |
| ENTITY_REFERENCE_NODE |
ノードは |
| ENTITY_NODE |
ノードは |
| PROCESSING_INSTRUCTION_NODE |
ノードは |
| COMMENT_NODE |
ノードは |
| DOCUMENT_NODE |
ノードは |
| DOCUMENT_TYPE_NODE |
ノードは |
| DOCUMENT_FRAGMENT_NODE |
ノードは |
| NOTATION_NODE |
ノードは |
nodeName, nodeValue, attributes の値は、以下の通り、ノード型によって異なる。
| nodeName | nodeValue | attributes | |
| Element | tagName | null | NamedNodeMap |
| Attr | 属性の名 | 属性の値 | null |
| Text | #text | テキストノードの内容 | null |
| CDATASection | #cdata-section | CDATA 部の内容 | null |
| EntityReference | 参照されるエンティティの名前 | null | null |
| Entity | エンティティ名 | null | null |
| ProcessingInstruction | ターゲット | ターゲットを除いた内容全部 | null |
| Comment | #comment | 注釈の内容 | null |
| Document | #document | null | null |
| DocumentType | 文書型名 | null | null |
| DocumentFragment | #document-fragment | null | null |
| Notation | 表記法名 | null | null |
nodeName
nodeValue
DOMException
NO_MODIFICATION_ALLOWED_ERR: ノードが読み出し専用であるとき発生する。
DOMException
DOMSTRING_SIZE_ERR: 実装プラットフォーム上で1つの DOMString 変数に収まるのを超えたキャラクタを返すことになるときに発生する。
nodeType
parentNode
Document, DocumentFragment, Attr を除き、すべてのノードが親をもってもよい。もっとも、ノードが作成されたばかりでまだ樹に追加されていない場合や、樹から取り除かれている場合は、これは null である。
childNodes
NodeList。子がなければ、これはノードを含まない NodeList である。返される NodeList の内容は、たとえば、ノードの作成元のノードオブジェクトの子への変更が、直ちに NodeList アクセス器により返されるノードに反映されるという意味で、「生きて」いる。ノードの内容の静的なスナップショットではないのである。これは、getElementsByTagName メソッドによって返されるものを含め、各 NodeList について当てはまる。
firstChild
null を返す。
lastChild
null を返す。
previousSibling
null を返す。
nextSibling
null を返す。
attributes
Element である場合)の属性を含んでいる NamedNodeMap。それ以外の場合は null。
ownerDocument
Document オブジェクト。これは、新しいノードを作成するために使われた Document オブジェクトでもある。このノードが Document であるとき、これは null である。
insertBefore
refChild の前にノード newChild を挿入する。refChild が null である場合は、newChild を子のリストの末尾に挿入する。
newChild は DocumentFragment オブジェクトであり、その子のすべてが同じ順序で、refChild の前に挿入される。newChild が既に樹の中にある場合には、まずそれが取り除かれる。
newChild
|
挿入すべきノード。 |
|
refChild
|
参照ノード、すなわち、その前に新しいノードが挿入されるべきノード。 |
DOMException
HIERARCHY_REQUEST_ERR: これが newChild の型の子を許さない型のノードである場合、または挿入されるべきノードがこのノードの祖先のうちのひとつである場合に発生する。
WRONG_DOCUMENT_ERR: このノードを作成したのと異なる文書から newChild が作成された場合に発生する。
NO_MODIFICATION_ALLOWED_ERR: このノードが読み出し専用である場合に発生する。
NOT_FOUND_ERR: refChild がこのノードの子でない場合に発生する。
replaceChild
oldChild を newChild で置き換え、oldChild ノードを返す。newChild が既に樹の中にある場合には、まずそれが取り除かれる。
newChild
|
子リストの中に置くべき新しいノード。 |
|
oldChild
|
リストの中の置き換えられるノード。 |
DOMException
HIERARCHY_REQUEST_ERR: このノードが newChild ノードの型の子を許さない型である場合、または置くべきノードがこのノードの祖先のうちのひとつである場合に発生する。
WRONG_DOCUMENT_ERR: このノードを作成したのと異なる文書から newChild が作成された場合に発生する。
NO_MODIFICATION_ALLOWED_ERR: このノードが読み出し専用である場合に発生する。
NOT_FOUND_ERR: oldChild がこのノードの子でない場合に発生する。
removeChild
oldChild で示される子ノードを子のリストから取り除き、それを返す。
oldChild
|
取り除かれるノード。 |
DOMException
NO_MODIFICATION_ALLOWED_ERR: このノードが読み出し専用である場合に発生する。
NOT_FOUND_ERR: oldChild がこのノードの子でない場合に発生する。
appendChild
newChild をこのノードの子のリストの末尾に追加する。newChild が既に樹の中にある場合には、まずそれが取り除かれる。
newChild
|
追加するべきノード。
それが |
DOMException
HIERARCHY_REQUEST_ERR: このノードが newChild の型の子を許さない型のノードである場合、または追加されるべきノードがこのノードの祖先の内のひとつである場合に発生する。
WRONG_DOCUMENT_ERR: このノードを作成したのと異なる文書から newChild が作成された場合に発生する。
NO_MODIFICATION_ALLOWED_ERR: このノードが読み出し専用である場合に発生する。
hasChildNodes
true、子をもっていない場合には false。
cloneNode
parentNode は null を返す)。
Element を複製すれば、XMLプロセッサによってデフォルト属性を表現するために生成されたものを含めてすべての属性とその値とがコピーされるが、このメソッドは、それが深部までの複製でない限り、それが含んでいるテキストを複製しない。テキストは子 Text ノードの中に含まれているからである。その他の型のノードを複製すれば、単にこのノードのコピーが返されるだけである。
deep
|
|
NodeList インターフェイスは、この集合体の実装方法を定義したり強制したりすることなく、ノードの順序つき集合体の抽象体を提供する。
NodeList の中の項目は、0 で始まる整数の添え字を経由してアクセス可能である。
interface NodeList {
Node item(in unsigned long index);
readonly attribute unsigned long length;
};
item
index 番目の項目を返す。index がリスト内のノードの数よりも大きい場合には、これは null を返す。
index
|
集合体への添え字。 |
NodeList の中の index 番目にある項目。合法な添え字でない場合には null。
length
length-1 までである。
NamedNodeMap インターフェイスを実装するオブジェクトは、名前でアクセスできるノードの集合体を表現するために使われる。NamedNodeMap は NodeList からの承継をしないことに注意すること。NamedNodeMap は何らかの特定の順序で維持されないのである。NamedNodeMap を実装しているオブジェクトの中に含まれているオブジェクトは、順序を表わす添え字でアクセスしてもよいが、これは単に NamedNodeMap の内容を簡単に列挙できるようにするものであって、DOMがこれらのノードに順序を指定するという意味合いを含むのではない。
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;
};
getNamedItem
name
|
引き出すべきノードの名前。 |
Node(型を問わない)。指定された名前がマップ内のどのノードも特定しない場合には、null。
setNamedItem
nodeName 属性を使っているノードを追加する。
nodeName 属性は、そのノードをその下にストアすべき名前を派生させるために使われるので、一定の型(「特殊」な文字列値をもつ型)の複数のノードは、名前が衝突することになるためにストアできない。これは、ノードに別名をつけられるようにするために望ましいものと見られる。
arg
|
指名ノードマップ (named node map) の中にストアするべきノード。そのノードは後に、そのノードの |
DOMException
WRONG_DOCUMENT_ERR: NamedNodeMap を作成したのと異なる文書から arg が作成された場合に発生する。
NO_MODIFICATION_ALLOWED_ERR: NamedNodeMap が読み出し専用である場合に発生する。
INUSE_ATTRIBUTE_ERR: arg が、すでに他の Element オブジェクトの属性である Attr である場合に発生する。他の要素で Attr を再利用するためには、DOMユーザは明示的に Attr を複製しなければならない。
removeNamedItem
Attr である場合は、それは直ちに置き換えられる。
name
|
取り除くべきノードの名前。 |
null。
DOMException
NOT_FOUND_ERR: マップ内に name と名付けられたノードがない場合に発生する。
item
index 番目の項目を返す。index がマップ内のノードの数よりも大きい場合には、これは null を返す。
index
|
マップへの添え字。 |
NamedNodeMap の index 番目の位置にあるノード。それが合法な添え字でない場合には、null。
length
length-1 である。
CharacterDate インターフェイスは、DOM内のキャラクタデータにアクセスするための属性やメソッドのセットで Node を拡張するものである。The CharacterData interface extends Node with a set 明確性のため、このセットは、これらの属性やメソッドを使うオブジェクトごとにではなく、ここで定義される。Text その他は CharacterData からインターフェイスを承継するけれども、CharacterDAte に直接に対応するDOMオブジェクトはない。このインターフェイスにおける offset はすべて 0 から始まる。
interface CharacterData : Node {
attribute DOMString data;
// raises(DOMException) on setting
// raises(DOMException) on retrieval
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
CharacterData ノードにストアしてよいデータの量に勝手な制約を設けてはならない。もっとも、実装の制約とは、あるノードの全体が単一の DOMString に収まらないという意味である場合もある。そうした場合には、ユーザは substringData を呼び出して、適切なサイズの断片の形でデータを引き出してもよい。
DOMException
NO_MODIFICATION_ALLOWED_ERR: ノードが読み出し専用である場合に発生する。
DOMException
DOMSTRING_SIZE_ERR: その実装プラットフォーム上で1つの DOMString 変数に収まるのを超えるキャラクタが返されることになる場合に発生する。
length
date と下記の substringData メソッドとを通じて利用可能なキャラクタの数。これは 0 という値をもつ場合もある。すなわち、CharacterData ノードが空であってもよいのである。
substringData
offset
|
抜き出すべきサブ文字列の開始オフセット。 |
|
count
|
抜き出すべきキャラクタの数。 |
offset と count との合計が length を超える場合には、データの末尾までのキャラクタすべてが返される。
DOMException
INDEX_SIZE_ERR: 指定されたオフセットが負であるか、data のキャラクタ数より大きい場合、または指定された count が負である場合に発生する。
DOMSTRING_SIZE_ERR: 指定された範囲のテキストが1つの DOMString に収まらない場合に発生する。
appendData
data は、data と 指定された DOMString とを結合したものへのアクセスを提供する。
arg
|
追加すべき |
DOMException
NO_MODIFICATION_ALLOWED_ERR: このノードが読み出し専用である場合に発生する。
insertData
offset
|
挿入をするべき箇所のキャラクタオフセット。 |
|
arg
|
挿入すべき |
DOMException
INDEX_SIZE_ERR: 指定されたオフセットが負であるか、data のキャラクタ数よりも大きい場合に発生する。
NO_MODIFICATION_ALLOWED_ERR: このノードが読み出し専用である場合に発生する。
deleteData
data と length とは変更を反映する。
offset
|
キャラクタ除去を開始するべき箇所のオフセット。 |
|
count
|
削除すべきキャラクタの数。 |
DOMException
INDEX_SIZE_ERR: 指定されたオフセットが負であるか、data のキャラクタ数よりも大きい場合、または指定された count が負である場合に発生する。
NO_MODIFICATION_ALLOWED_ERR: このノードが読み出し専用である場合に発生する。
replaceData
offset
|
置換を開始すべき箇所のオフセット。 |
|
count
|
置換すべきキャラクタ数。 |
|
arg
|
範囲の置き換えとなる |
DOMException
INDEX_SIZE_ERR: 指定されたオフセットが負であるか、data のキャラクタ数よりも大きい場合、または指定された count が負である場合に発生する。
NO_MODIFICATION_ALLOWED_ERR: このノードが読み出し専用である場合に発生する。
Attr インターフェイスは、Element オブジェクトの属性を表わすものである。概して、属性の許容値は文書型定義の中で定義されている。
Attr オブジェクトは Node インターフェイスを継承するが、それらは実際にはそれらが記述する要素の子ノードではないので、DOMはそれらを文書樹の一部とみなさない。そこで、Node の parentNode, previousSibling, nextSibling は、Attr オブジェクトについては null 値をとる。DOMは、それらの結びつけられている要素からの分離した同一性をもつというよりも、属性は要素のプロパティであるという見方をとる。これは、そうした機能を、与えられた型の要素すべてに結びつけられたデフォルト属性として実装することをより効率的にするはずである。さらに、Attr ノードは、DocumentFragment の直接の子であってはならない。もっとも、DocumentFragment の内部に含まれている Element ノードに結びつけることはできる。要するに、DOMのユーザや実装者は、Attr ノードが、Node インターフェイスを継承している他のオブジェクトには一般的であるものをもつが、大きく異なる点もあるということを意識しなければならないのである。
属性の実効値は以下のように決定される。この属性が明示的に何かの値を割り当てられている場合は、その値が属性の実効値である。そうではない場合、この属性について宣言があり、その宣言がデフォルト値を含んでいるときには、デフォルト値が属性の実効値である。そうでないならば、属性は、明示的に追加されるまでは、構造モデルないのこの要素上には存在しない。Attr インスタンスの nodeValue 属性は、文字列版の属性値を取出すためにも使えることに注意すること。
XMLでは、属性の値はエンティティ参照を含むことができ、Attr ノードの子ノードは、エンティティ参照が展開されていない表現を提供する。これらの子ノードは、Text であっても EntityReference ノードであってもよい。属性型は未知である場合があるので、トークン化された属性値はない。
interface Attr : Node {
readonly attribute DOMString name;
readonly attribute boolean specified;
attribute DOMString value;
};
name
specified
true である。そうでない場合には false である。この属性に責任があるのはユーザではなく実装であることに注意すること。ユーザが属性の値を変更した場合には(それがデフォルトちと同じ値をもつこととなる場合でも)specified フラグは自動的に true に切り替わる。属性をDTDのデフォルト値に再指定するためには、ユーザは属性を削除しなければならない。そうすれば、実装は、specified が false に設定され(あれば)デフォルト値をもつ新しい属性を利用可能にすることになる。
まとめると、
specified は true であり、値は割り当てられた値である。
specified は false であり、値はDTDのデフォルト値である。
value
設定時には、これは、文字列の解析されない内容をもった Text ノードを作成する。
文書をトラバースするときに制作者が遭遇するオブジェクト(テキストは別にして)のうちずば抜けて大多数は Element ノードである。以下のXML文書を想定してみよ。
<elementExample id="demo"> <subelement1/> <subelement2><subsubelement/></subelement2> </elementExample>
DOMを使って表現すると、トップノードは "elementExample" の Element ノードであり、これが、"subelement1" という要素と "subelement2" という要素の2つの子 Element を内容としている。"subelement1" は子ノードを含んでいない。
要素は、それと結びつけられた属性をもつ場合がある。Element インターフェイスは Node から継承をするので、通有的な Node インターフェイスメソッド getAttributes を使って、要素のすべての属性のセットを引き出してよい。Element インターフェイス上には、名前で Attr オブジェクトを引き出し、または名前で属性値を引き出すためのメソッドがある。XMLでは、属性値はエンティティ参照を含む場合があり、属性値を表現しているおそらく相当に複雑なサブツリーを試すためには、Attr オブジェクトが使われるべきである。他方、HTMLでは、すべての属性が単純な文字列値をもち、属性値に直接にアクセスするためメソッドを、簡便な手段として安心して使うことができる。
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);
void normalize();
};
tagName
<elementExample id="demo">
...
</elementExample> ,
では、tagName は "elementExample" という値をもつ。これは、DOMの操作のすべてと同様に、XMLでは大文字小文字の区別を維持することに注意すること。HTML DOMは、ソースHTML文書での大文字小文字の差とは無関係に、正典的な大文字形式でHTML要素の tagName を返す。
getAttribute
name
|
引き出すべき属性の名前。 |
Attr 値。その属性が指定された値やデフォルト値をもたない場合には、空文字列。
setAttribute
Attr ノードに加えて何かの Text ノードや EntityReference ノードを作成し、適切なサブツリーを構築して、setAttributeNode を使ってそれを属性の値としてそれを割り当てなければならない。
name
|
作成または変更するべき属性の名前。 |
|
value
|
設定されるべき文字列形式での値。 |
DOMException
INVALID_CHARACTER_ERR: 指定された名前に不当なキャラクタが含まれている場合に発生する。
NO_MODIFICATION_ALLOWED_ERR: このノードが読み出し専用である場合に発生する。
removeAttribute
name
|
取り除くべき属性の名前。 |
DOMException
NO_MODIFICATION_ALLOWED_ERR: このノードが読み出し専用である場合に発生する。
getAttributeNode
setAttributeNode
newAttr
|
属性リストに追加すべき |
newAttr 属性が同じ名前の既存の属性を置き換える場合には、以前からの既存の Attr ノードが返される。それ以外の場合には、null が返される。
DOMException
WRONG_DOCUMENT_ERR: 要素を作成したのと異なる文書から作成された場合に newAttr が作成された場合に発生する。
NO_MODIFICATION_ALLOWED_ERR: このノードが読み出し専用である場合に発生する。
INUSE_ATTRIBUTE_ERR: newAttr が既に他の Element オブジェクトの属性である場合に発生する。それを他の文書で再利用するためには、DOMユーザは明示的に Attr ノードを複製しなければならない。
removeAttributeNode
Attr ノード。
DOMException
NO_MODIFICATION_ALLOWED_ERR: このノードが読み出し専用である場合に発生する。
NOT_FOUND_ERR: oldAttr がその要素の属性でない場合に発生する。
getElementsByTagName
NodeList を、Element 樹の命令前トラバーサルにおいて遭遇するであろう順に返す。
name
|
照合するべきタグ名。"*" という特殊な値はすべてのタグに合致する。 |
Element ノードのリスト。
normalize
Text インターフェイスは、Element または Attr のテキスト的内容(XMLではキャラクタデータと呼ばれる)を表わす。要素の内容の内部にマークアップがない場合には、テキストは、要素の唯一の子である Text インターフェイスを実装した単一のオブジェクトの中に含まれる。マークアップがある場合には、それは、その要素の子のリストを形成する要素と Text ノードとのリストへと解析される。
最初に文書がDOMを経由して利用可能にされたときには、各テキストブロックごとに Text ノードは1つしかない。ユーザは、間に挟まるマークアップなしで、与えられた要素の内容を表わす隣接した Text を作成してもよいが、XMLやHTMLでこれらのノードの間の分離を表わす方法がなく、そのためそれらは(一般的に)DOM編集の期間と期間の間は永続しないことになることを意識して置くべきである。Element オブジェクト上の normalize() メソッドは、そうした隣接する Text オブジェクトを、テキストブロックごとに単一のノードへと併合する。これは、XPointer でのナビゲーションといったような、特定の文書構造に依存する操作を採用するより前に推奨される。
interface Text : CharacterData {
Text splitText(in unsigned long offset)
raises(DOMException);
};
splitText
Text ノードを、指定されたオフセットの箇所で2つの Text ノードに分割する。両者は樹の中で兄弟のままである。このノードはその後、offset の地点までのすべての内容だけを含むことになる。そして新しい Text ノードは、このノードのつぎの兄弟として挿入され、offset の地点およびそれ以降のすべての内容を含む。
offset
|
分割すべき箇所のオフセット。0から始まる。 |
Text ノード.
DOMException
INDEX_SIZE_ERR: 指定されたオフセットが負であるか data のキャラクタ数よりも大きい場合に発生する。
NO_MODIFICATION_ALLOWED_ERR: このノードが読み出し専用である場合に発生する。
これは注釈の内容、すなわち、開始記号 '<!--' と終了記号 '-->' との間のすべてのキャラクタを表現する。これはXMLや(HTMLツールの中には完全なSGML注釈構造を実装するものもあるかもしれないけれども実際には)HTMLの注釈の定義であることに注意すること。
interface Comment : CharacterData {
};
ここで定義されているインターフェイスは、DOM1コア仕様書の一部を形成するが、これらのインターフェイスを露出するオブジェクトは、HTMLだけを扱うDOM実装の中では決して出会うことがない。そうしたものなので、HTML専用DOM実装は、これらのインターフェイスを実装するオブジェクトをもつ必要はない。
CDATA 部は、さもなくばマークアップとみなされるキャラクタを含んだテキストのブロックをエスケープするために使われる。CDATA 部内で認識される唯一の区切り子は、CDATA 部を終結する "]]>" という文字列である。CDATA 部はネストできない。主な目的は、XMLの断片といったような素材を、区切り子すべてをエスケープする必要なしに組み込むためである。
Text ノードの DOMString 属性は、CDATA 部に含まれているテキストを保持する。これは CDATA 部の外側ならばエスケープする必要のあるキャラクタを含んでもよいことや、シリアル化のために選ばれたキャラクタエンコーディング ("charset") 次第ではいくつかのキャラクタを CDATA 部の一部として書き出すことが不可能な場合があることに注意すること。
CDATASection インターフェイスは、Text インターフェイスを通じて CharacterData インターフェイスを継承する。隣接する CDATASctions ノードは Element.normalize() メソッドの使用によって併合されない。
interface CDATASection : Text {
};
Document は各自、null か DocumentType オブジェクトかのいずれかをその値とする doctype 属性をもつ。DOM1コアにおける DocumentType インターフェイスは、その文書について定義されたエンティティのリストへのインターフェイスを提供するが、これを書いた時点ではネームスペースの効果やDTD表現に関する多様なXMLスキームの努力が明確に理解されていないため、その他のものはほとんど提供しない。
DOM1は DocumentType ノードの編集をサポートしない。
interface DocumentType : Node {
readonly attribute DOMString name;
readonly attribute NamedNodeMap entities;
readonly attribute NamedNodeMap notations;
};
name
DOCTYPE というキーワードの直後に続く名前。
entities
NamedNodeMap。重複は切り捨てられる。たとえば、
<!DOCTYPE ex SYSTEM "ex.dtd" [ <!ENTITY foo "foo"> <!ENTITY bar "bar"> <!ENTITY % baz "baz"> ]> <ex/>では、インターフェイスは
foo や bar へのアクセスを提供するが、baz へのアクセスは提供しない。このマップ内のノードはノードごとに Entity インターフェイスも実装する。
DOM1はエンティティの編集をサポートせず、したがって entities はどのようにしても変更できない。
notations
NamedNodeMap 。重複は切り捨てられる。このマップ内のノードはノードごとに Notation インターフェイスも実装する。
DOM1は表記法の編集をサポートせず、したがって notations はどのようにしても変更できない。
このインターフェイスは、DTDで定義されている表記法を表わす。表記法は、解析されないエンティティ(XML 1.0 仕様書の section 4.7 を見ること)のフォーマットを名前で宣言するか、処理命令(PI)ターゲット(XML 1.0 仕様書の section 2.6 を見ること)の形式的宣言にために使われるかのいずれかである。Node から継承された nodeName 属性は、表記法の宣言された名前に設定される。
DOM1は Notation ノードの編集をサポートせず、したがってそれらは読み出し専用である。
Notation ノードは親をもたない。
interface Notation : Node {
readonly attribute DOMString publicId;
readonly attribute DOMString systemId;
};
publicId
null である。
systemId
null である。
このインターフェイスは、XML文書の中の解析対象または非対象のエンティティを表現する。これはエンティティ宣言ではなくエンティティ自体をモデル化するものであることに注意すること。Entity 宣言モデリングは、後の水準のDOM仕様書に委ねられている。
Node から継承された nodeName 属性は、エンティティ名を内容とする。
XMLプロセッサは、構造モデルがDOMに渡される前にエンティティを完全に展開することを選んでもよい。この場合には文書樹の中に EntityReference はないことになる。
XMLは、妥当性を検証しないXMLプロセッサが、内部サブセットで作られ、あるいは外部パラメータエンティティで宣言されたエンティティ宣言を読んで処理するように命令しない。これは、外部サブセットで宣言された解析対象エンティティはあるクラスのアプリケーションにより展開される必要がなく、そのエンティティの置換値が利用可能でない場合があるという意味である。置換値が利用可能であるときは、対応する Entity ノードの子リストはその置換テキストの構造を表現する。そうでないときは、子ノードは空である。
Entity の子の解釈(置換値)は不精な評価をされてもよい。ユーザによるアクション(Entity ノード上の childNodes メソッドの呼び出しといったようなもの)が、この評価の引き金となるものと想定される。
DOM1は Entity ノードの編集をサポートしない。ユーザが Entity の内容に変更を加えたい場合には、関連する EntityReference ノードごとが、構造モデル内でその Entity の内容の複製によって置き換えられる必要があり、求められる変更は代わりにそれらの複製それぞれへ加えられなければならない。Entity ノードの子孫はすべて読み出し専用である。
Entity ノードは親をもたない。
interface Entity : Node {
readonly attribute DOMString publicId;
readonly attribute DOMString systemId;
readonly attribute DOMString notationName;
};
publicId
null である。
systemId
null である。
notationName
null である。
エンティティ参照がソース文書の中にあるとき、またはユーザがエンティティ参照を挿入したいと思うときには、EntityReference オブジェクトは構造モデルの中に挿入されてよい。そのキャラクタ参照および定義済みエンティティへの参照は、エンティティ参照ではなく Unicode の透過物によってキャラクタが表現されるようにHTMLプロセッサやXMLプロセッサによって展開されるとみなされることに注意すること。そのうえ、XMLプロセッサは、構造モデルの構築中に、EntityReference オブジェクトを提供する代わりに完全にエンティティへの参照を展開してもよい。それがそうしたオブジェクトを提供する場合には、与えられた EntityReference ノードについて、その参照されたエンティティを表現する Entity ノードがないかもしれない。しかし、そうした Entity が存在する場合は、EntityReference ノードの子リストは Entity ノードのものと同じである。Entity ノードと同様に、EntityReference コードの子孫はすべて読み出し専用である。
EntityReference の子の解釈(参照された Entity の置換値)は不精な評価をされてもよい。ユーザによるアクション(EntityReference ノード上の childNodes メソッドの呼び出しといったようなもの)が評価の引き金となると想定される。
interface EntityReference : Node {
};
ProcessingInstruction インターフェイスは、文書のテキスト内のプロセッサ特有の情報を保持する手段としてXMLで使われている「処理命令(PI)」を表わす。
interface ProcessingInstruction : Node {
readonly attribute DOMString target;
attribute DOMString data;
// 設定時に DOMException を発生させる。
};
target
data
> の直前のキャラクタまでである。
DOMException
NO_MODIFICATION_ALLOWED_ERR: ノードが読み出し専用である場合に発生する。
|
|
|
|