Warning:
This wiki has been archived and is now read-only.
HTML5/common-dom-interfaces
通用DOM接口
在IDL属性中反射内容属性
一些IDL属性被定义用来反映特定的内容属性。这意味着,当获取该属性时,IDL属性必须返回内容属性当前的值;当设置该属性时,IDL属性用给出的值修改内容属性的值。
总体来说,在获取该属性时,如果内容属性不存在,则IDL属性必须被认为在内容属性的值为空字符串的情况下被调用;在设置该属性时,如果内容属性不存在,则必须首先添加该内容属性。
如果一个IDL属性所反映的是一个其内容属性被定义包含一个URL的DOMString属性,则在获取该属性是,该IDL属性必须解释关联到该元素的内容属性的值,并且,如果成功则返回解释而得的绝对URL,否则返回空字符串;在设置该属性时,必须将内容属性设为指定的字面上的值。如果内容属性不存在,若内容属性拥有默认值,则IDL属性必须返回该默认值,否则返回空字符串。
如果一个IDL属性所反映的是一个其内容属性被定义包含一个或多个URL的DOMString属性,则在获取该属性是,该IDL属性必须首先将该内容属性以空格分隔,之后解释关联到该元素的每一个URL标记,返回一串解释而得的绝对URL,每个URL之间由一个单独的U+0020空白字符分隔,忽略结束不成功的标记;如果内容属性不存在,则IDL属性必须返回该默认值,否则返回空字符串。在设置该属性时,必须将内容属性设为指定的字面上的值。
如果一个IDL属性所反映的是一个其内容属性是枚举属性的DOMString属性,且该IDL属性被限制仅支持已知的值,则在获取该属性是,该IDL属性必须返回与该属性所处状态先关联的对应的值(在其典型情况下),或者如果该属性场所处的状态没有与之关联的关键字值则返回空字符串;在设置该属性时,该内容属性必须被设置为指定的新值。
如果一个IDL属性所反映的是一个上述情况以外的DOMString属性,则获取及设置该属性都必须在透明的、保留大小写的方式下进行。
如果一个IDL属性所反映的是一个boolean属性,则在获取该属性时,如果内容属性被设置必须返回真,覆盖内容属性不存在返回假。在设置该属性时,如果IDL属性被设为假必须删除该内容属性,如果IDL属性被设为真必须将该内容属性设为空字符串。(这符合布尔型内容属性规则。)
如果一个IDL属性所反映的属性是一个有符号整数类型(long),则在获取该属性时,该内容属性必须按照解析有符号整数的规则进行解析,并且如果解析成功且该值在IDL属性的类型的范围之内,则必须返回解析的结果。如果解析失败或者解析返回的值超出了该值应有的范围,或者该属性不存在,则如果存在默认值则返回该默认值,否则返回0。在设置该属性时,给出的值必须被转换成能够表示该数字的有效整数形式的最短的可能的字符串,并且该字符串必须被用作新的内容属性的值。
如果一个IDL属性所反映的属性是一个有符号整数类型(long)且被限制为仅支持非负数字,则在获取该属性时,该内容属性必须按照解析非负整数的规则解析,并且如果解析成功且该值在IDL属性的类型的范围之内,则必须返回解析的结果。如果解析失败或者解析返回的值超出了该值应有的范围,或者该属性不存在,则如果存在默认值则返回该默认值,否则返回-1。在设置该属性时,如果给出的值是负数,用户代理必须抛出一个INDEX_SIZE_ERR异常。否则,给出的值必须被转换成能够表示该数字的有效非负整数形式的最短的可能的字符串,并且该字符串必须被用作新的内容属性的值。
如果一个IDL属性所反映的属性是一个无符号整数类型(unsigned long),则在获取该属性时,该内容属性必须按照解析非负整数的规则进行解析,并且如果解析成功且该值在0至2147483647(含)范围之内,则必须返回解析的结果。如果解析失败或者解析返回的值超出了该值应有的范围,或者该属性不存在,则如果存在默认值则返回该默认值,否则返回0。在设置该属性时,给出的值必须被转换成能够表示该数字的有效非负整数形式的最短的可能的字符串,并且该字符串必须被用作新的内容属性的值。
如果一个IDL属性所反映的属性是一个无符号整数类型(unsigned long)且被限制为仅支持大于零的非负数字,则其行为与上一种情况相似,但是其值不能为零。在获取该属性时,该内容属性必须按照解析非负整数的规则解析,并且如果解析成功且该值在1至2147483647(含)范围之内,则必须返回解析的结果。如果解析失败或者解析返回的值超出了该值应有的范围,或者该属性不存在,则如果存在默认值则返回该默认值,否则返回1。在设置该属性时,如果给出的值是零,用户代理必须抛出一个INDEX_SIZE_ERR异常。否则,给出的值必须被转换成能够表示该数字的有效非负整数形式的最短的可能的字符串,并且该字符串必须被用作新的内容属性的值。
如果一个IDL属性所反映的属性是一个浮点数字类型(double),则在获取该属性时,该内容属性必须按照解析浮点数字的规则进行解析,并且如果解析成功,则必须返回解析的结果。如果解析失败,或者该属性不存在,则如果存在默认值则返回该默认值,否则返回0.0。在设置该属性时,给出的值必须被转换成浮点型数字的最佳表现形式,并且该字符串必须被用作新的内容属性的值。
如果一个IDL属性所反映的属性是DOMTokenList或DOMSettableTokenList类型,则在获取该属性时,必须返回一个隐含字符串是该元素相应内容属性的值得DOMTokenList或DOMSettableTokenList对象(恰当的)。如果对象改变的起隐含字符串,则内容属性也必须立即改变。如果属性不存在,则对象所表示的字符串为空字符串;如果对象改变该空字符串,则用户代理必须增加对应的内容属性,并且该内容属性的值被设为空字符串改变后的值。对于每个属性,每次返回的都是同一个DOMTokenList或DOMSettableTokenList对象。
如果一个没有属性的元素调用了element.classList.remove()方法,隐含字符串将不会变化,因为移除了某一标记的空字符串仍然为空字符串。然而,如果调用了element.classList.add()方法,一个class属性将被添加到该元素之上,且该属性的值为将要加入的标记。
如果一个IDL属性所反映的属性是一个HTMLElement类型,或者继承自HTMLElement的接口,则在获取该属性时,必须执行下列算法(如果返回了一个值,则停止第一点):
- 如果相应的内容属性不存在,则该IDL属性必须返回null。
- 设候选对象为在内容属性所属文档中使用相应内容属性的当前值作为参数执行document.getElementById()方法所获得的元素。
- 如果候选对象为null,或者其不是该IDL属性兼容的类型,则该IDL属性必须返回null。
- 否则,必须返回候选对象。
在设置该属性时,如果给出的元素拥有一个id属性,则内容属性必须被设置为该id属性的值。否则,该IDL属性必须被设为空字符串。
集合
HTMLCollection、HTMLAllCollection、HTMLFormControlsCollection以及HTMLOptionsCollection接口描述了不同类型的DOM节点列表。总体来说,实现了这些接口的对象被称为集合。
当创建一个集合时,将其与一个过滤器和一个根相关联。
举例说明,若创建一个document.images属性的HTMLCollection对象,该对象与一个仅选择img元素的过滤器相关联,且植根于文档的根。
集合表示一个植根于集合的根的子树的活动的视图,其只包含给出的过滤器所匹配的节点。该视图是线性的。如果没有其他的特殊要求,集合中的节点按照树形结构顺序排列。
一个返回集合的属性在每次调用时都返回相同的对象。
HTMLCollection
HTMLCollection接口表示一个元素的普通集合。
interface HTMLCollection {
readonly attribute unsigned long length;
caller getter Element item(in unsigned long index);
caller getter object namedItem(in DOMString name); //仅返回元素
};
collection . length
返回集合中元素的数目。
element = collection . item(index)
collection[index]
collection(index)
返回集合中索引为index的元素。元素按照树形结构顺序排列。
如果index超出范围则返回null。
element = collection . namedItem(name)
collection[name]
collection(name)
返回集合中ID或名称为name的第一个元素。
如果没有ID或名称为name的元素则返回null。
仅有a、applet、area、embed、form、frame、frameset、iframe、img及object元素拥有用于该方法的名称;它们的名称由它们name属性的值给出。
对象的支持的属性索引是在零至集合所表示的节点的数量减一范围内的数字。如果没有这样的元素,则没有支持的属性索引。
length属性必须返回集合所表示的节点的数目。
item(index)方法必须返回集合中的第index个节点。如果集合中没有第index个节点,则该方法必须返回null。
支持的属性名称包含了集合所表示的拥有一个name属性的a、applet、area、embed、form、frame、frameset、iframe、img及object元素的name属性的值,加上集合所表示的元素的ID列表。
namedItem(key)方法必须返回集合中的第一个符合下列要求之一的节点:
如果没有找到这样的元素,则方法必须返回null。
HTMLAllCollection
HTMLAllCollection接口和HTMLCollection类似,表示一个元素的普通集合,不同的是,在调用namedItem()方法时,若存在多个匹配的元素,则返回一个HTMLAllCollection对象。
interface HTMLAllCollection : HTMLCollection {
// inherits length and item()
caller getter object namedItem(in DOMString name); //重写继承的namedItem()方法
HTMLAllCollection tags(in DOMString tagName);
};
collection . length
返回集合中元素的数目。
element = collection . item(index)
collection[index]
collection(index)
返回集合中索引为index的元素。元素按照树形结构顺序排列。
如果index超出范围则返回null。
element = collection . namedItem(name)
collection = collection . namedItem(name)
collection[name]
collection(name)
返回集合中ID或名称为name的元素。
如果存在多个匹配的元素,则返回一个包含了所有这些元素的HTMLAllCollection对象。
如果没有ID或名称为name的元素则返回null。
仅有a、applet、area、embed、form、frame、frameset、iframe、img及object元素拥有用于该方法的名称;它们的名称由它们name属性的值给出。
collection = collection . tags(tagName)
返回一个对当前集合进行过滤后的集合,在新的集合中只包含拥有给出标记名称的元素。
对象的支持的属性索引及支持的属性名称在HTMLCollection对象中定义。
namedItem(key)方法必须执行下列算法:
- 设集合为一个HTMLAllCollection对象,且该对象的根为调用该方法的HTMLAllCollection对象的同一个节点,其过滤器只匹配调用该方法的HTMLAllCollection对象中已经匹配的元素以及:
- 如果在方法被调用时,集合中只有一个节点,则返回该节点且停止算法。
- 否则,如果在方法被调用时,集合为空,则返回null且停止算法。
- 否则,返回集合。
tags(tagName)方法必须返回一个HTMLAllCollection对象,且该对象的根为调用该方法的HTMLAllCollection对象的同一个节点,其过滤器只匹配调用该方法的HTMLAllCollection对象中已经匹配的且其本地名称为tagName参数的HTML元素。在HTML文档中,参数必须首先被转换为ASCII小写形式。
HTMLFormControlsCollection
HTMLFormControlsCollection接口表示一个form及fieldset元素中的列出的元素的集合。
interface HTMLFormControlsCollection : HTMLCollection {
// inherits length and item()
caller getter object namedItem(in DOMString name); //重写继承的namedItem()方法
};
interface RadioNodeList : NodeList {
attribute DOMString value;
};
collection . length
返回集合中元素的数目。
element = collection . item(index)
collection[index]
collection(index)
返回集合中索引为index的元素。元素按照树形结构顺序排列。
如果index超出范围则返回null。
element = collection . namedItem(name)
radioNodeList = collection . namedItem(name)
collection[name]
collection(name)
如果存在多个匹配的元素,则返回一个包含了所有这些元素的RadioNodeList对象。
radioNodeList . value [ = value ]
返回对象所表示的单选按钮中第一个被选中的值。
可以被设置,选中对象所表示的单选按钮中第一个满足给出的值的单选按钮。
对象的支持的属性索引在HTMLCollection对象中定义。
支持的属性名称由集合所表示的所有元素的所有id及name属性所组成。
namedItem(name)方法必须执行下列算法:
- 如果在方法被调用时,已经确切的集合中只有一个节点,其id或name属性等于name,则返回该节点并停止算法。
- 否则,如果集合中不存在id或name属性等于name的节点,则返回null并停止算法。
- 否则,创建一个新的RadioNodeList对象,表示一个HTMLFormControlsCollection对象的活跃的视图,进一步进行筛选,使得RadioNodeList对象中只包含id或name属性等于name的节点。RadioNodeList对象中的节点必须按照树形结构顺序排序。
- 返回RadioNodeList对象。
RadioNodeList接口中继承自NodeList接口的成员其行为必须按照其在NodeList对象中一样进行。
RadioNodeList对象上的value IDL属性,在获取该属性时,必须返回其在下列步骤中运行的返回值:
- 设元素为RadioNodeList对象所表示的按照树形结构顺序排序的第一个type属性处于单选按钮状态且checkedness为真的input元素。
- 如果元素为null,或者如果该元素没有value属性,则返回空字符串。
- 否则,返回元素的value属性的值。
在设置该属性时,value IDL属性必须执行下列步骤:
- 设元素为RadioNodeList对象所表示的按照树形结构顺序排序的第一个value内容属性存在且等于新值的input元素。否则,设其为null。
- 如果元素不是null,则设其checkedness为真。
HTMLOptionsCollection
HTMLOptionsCollection接口表示一个option元素的列表。其总是植根于select元素,并且拥有控制该元素后裔的属性和方法。
interface HTMLOptionsCollection : HTMLCollection {
// inherits tem()
attribute unsigned long length; ////重写继承的length属性
caller getter object namedItem(in DOMString name); //重写继承的namedItem()方法
void add(in HTMLElement element, in optional HTMLElement before);
void add(in HTMLElement element, in long before);
void remove(in long index);
attribute long selectedIndex;
};
collection . length [ = value ]
返回集合中元素的数目。
当设置一个较小的数字时,截断相应的容器中的option元素的数目。
当设置一个较大的数字时,向容器中增加新的空option元素。
element = collection . item(index)
collection[index]
collection(index)
返回集合中索引为index的元素。元素按照树形结构顺序排列。
如果index超出范围则返回null。
element = collection . namedItem(name)
nodeList = collection . namedItem(name)
collection[name]
collection(name)
如果存在多个匹配的元素,则返回一个包含了所有这些元素的NodeList对象。
如果没有ID为name的元素则返回null。
collection . add(element [, before ] )
将element插入到before所给出的节点之前。
before参数可以是一个数字,在这种情况下element将被插入到该数字的元素前;before参数还可以是集合中的一个元素,在这种情况下element将被插入到该元素之前。
如果before被忽略、为null或者是一个超出范围的数字,则element将被插入到列表的结尾。
如果element是一个其要插入到的元素的祖先,则该方法抛出一个HIERARCHY_REQUEST_ERR异常。如果element不是一个option或optgroup元素,则该方法不进行操作。
collection . selectedIndex [ = value ]
如果存在被选定的元素,则返回第一个这样的元素的索引,否则返回-1。
可以被设置,以改变选定项。
对象的支持的属性索引在HTMLCollection对象中定义。
在获取该属性时,length元素必须返回集合所表示的的节点的数目。
在设置该属性时,其行为取决于新值大于、等于或小于操作时集合所表示的的节点的数目。如果数目相等,则不进行任何操作。如果新值大于节点的数目,则两者之间的差值(新值减旧值)n个没有属性和字节的的option元素必须被追加到作为HTMLOptionsCollection的根的select元素之中。变化事件必须像一个包含了新option元素的DocumentFragment被插入一样触发。如果新值较小,则集合中的最后两者之间的差值(旧值减新值)n个节点必须从它们的父节点中被删除。
支持的属性名称包含集合所表示的所有元素的所有id及name属性的值。
namedItem(name)方法必须按照下列算法执行:
- 如果,在方法被调用时,集合中确切的存在一个节点,其id属性或name属性等于name,则返回该节点并停止算法。
- 否则,如果集合中不存在id属性或name属性等于name的节点,则返回null并停止算法。
- 否则,创建一个新的NodeList对象,表示一个HTMLOptionsCollection对象的活动的视图,进一步进行过滤,使NodeList对象只包含id属性或name属性等于name的节点。NodeList对象中的节点必须按照树形结构顺序排列。
- 返回该NodeList对象。
add(element, before)方法必须按照下列算法执行:
- 如果element不是一个option或optgroup元素,则返回并跳过这些步骤。
- 如果element是作为HTMLOptionsCollection对象的根的select元素的一个祖先,则抛出一个HIERARCHY_REQUEST_ERR异常。
- 如果before是一个元素,但该元素不是作为HTMLOptionsCollection对象的根的select元素的一个后裔,则抛出一个NOT_FOUND_ERR异常。
- 如果element和before是同一个元素,则返回并跳过这些步骤。
- 如果before是一个节点,则设参考点为该节点。否则,如果before是一个整数,且集合中存在第before个节点,则设参考点为该节点,否则,设参考点为null。
- 如果参考点不为null,设父节点为参考点的父节点。否则,设父节点为作为HTMLOptionsCollection的根的select元素。
- 在父节点节点上调用DOM Core的insertBefore()方法,使用element作为第一个参数、参考点为第二个参数。
remove(index)方法必须按照下列算法执行:
- 如果集合所标示的节点的数目为零,则跳过这些步骤。
- 如果index不是一个大于等于0且小于集合所标示的节点的数目的数字,设element为集合中的第一个元素。否则,设element为集合中的第index个元素。
- 从element的父节点中将其移除。
selectedIndex IDL属性必须像作为HTMLOptionsCollection对象的根的select元素的名称完全相同的属性一样被执行。
DOMTokenList
DOMTokenList接口描述一个空格分隔的标记的集的隐含字符串的接口。
interface DOMTokenList {
readonly attribute unsigned long length;
getter DOMString item(in unsigned long index);
boolean contains(in DOMString token);
void add(in DOMString token);
void remove(in DOMString token);
boolean toggle(in DOMString token);
stringifier DOMString();
};
tokenlist . length
返回字符串中的标记数目。
element = tokenlist . item(index)
tokenlist[index]
返回索引为index的标记。标记按照其在隐含字符串中被发现的顺序返回。
如果index超出范围,则返回null。
hastoken = tokenlist . contains(token)
如果token存在则返回真,否则返回假。
如果token为空,则抛出SYNTAX_ERR异常。
如果token包含任何空格,则抛出INVALID_CHARACTER_ERR异常。
tokenlist . add(token)
如果token不存在,则添加该标记。
如果token为空,则抛出SYNTAX_ERR异常。
如果token包含任何空格,则抛出INVALID_CHARACTER_ERR异常。
tokenlist . remove(token)
如果token存在,则移除该标记。
如果token为空,则抛出SYNTAX_ERR异常。
如果token包含任何空格,则抛出INVALID_CHARACTER_ERR异常。
hastoken = tokenlist . toggle(token)
如果token不存在则添加该标记,如果存在则移除该标记。如果token现在存在(被添加)则返回真;如果不存在(被移除)则返回假。
如果token为空,则抛出SYNTAX_ERR异常。
如果token包含任何空格,则抛出INVALID_CHARACTER_ERR异常。
length属性必须返回按照空格分隔隐含字符串所返回的标记的数目。这是长度。
如果长度不为零,对象的支持的属性索引为零到长度-1范围内的数字,否则不存在支持的属性索引。
item(index)方法必须按照空格分隔隐含字符串,维持标记在隐含字符串中被发现时的顺序,并返回列表中的第index项。如果index大于等于标记的数量,则该方法必须返回null。
举例说明,如果字符串为“a b a c”,则存在四个标记:索引0的标记为“a”、索引1的标记为“b”、索引2的标记为“a”、索引3的标记为“c”。
contains(token)方法必须执行下列算法:
- 如果token参数为空字符串,则抛出一个SYNTAX_ERR异常并停止算法。
- 如果token参数包含任意空白字符,则抛出一个INVALID_CHARACTER_ERR异常并停止算法。
- 否则,按照空格分隔隐含字符串,获得DOMTokenList对象的隐含字符串中的标记列表。
- 如果token指出的标记是大小写敏感匹配的DOMTokenList对象的隐含字符串中的标记中的一个,则返回真并停止算法。
- 否则返回假。
add(token)方法必须执行下列算法:
- 如果token参数为空字符串,则抛出一个SYNTAX_ERR异常并停止算法。
- 如果token参数包含任意空白字符,则抛出一个INVALID_CHARACTER_ERR异常并停止算法。
- 否则,按照空格分隔隐含字符串,获得DOMTokenList对象的隐含字符串中的标记列表。
- 如果给出的token是大小写敏感匹配的DOMTokenList对象的隐含字符串中的标记中的一个,则停止算法。
- 否则,如果DOMTokenList对象的隐含字符串不是一个空字符串且字符串的最后一个字符不是一个空白字符,则向该字符串的结尾追加一个U+0020空白字符。
- 向DOMTokenList对象的隐含字符串的结尾追加token的值。
remove(token)方法必须执行下列算法:
- 如果token参数为空字符串,则抛出一个SYNTAX_ERR异常并停止算法。
- 如果token参数包含任意空白字符,则抛出一个INVALID_CHARACTER_ERR异常并停止算法。
- 否则,从隐含字符串中移除给出的token。
toggle(token)方法必须执行下列算法:
- 如果token参数为空字符串,则抛出一个SYNTAX_ERR异常并停止算法。
- 如果token参数包含任意空白字符,则抛出一个INVALID_CHARACTER_ERR异常并停止算法。
- 否则,按照空格分隔隐含字符串,获得DOMTokenList对象的隐含字符串中的标记列表。
- 如果给出的token是大小写敏感匹配的DOMTokenList对象的隐含字符串中的标记中的一个,则从隐含字符串中移除一个token并停止算法,返回假。
- 否则,如果DOMTokenList对象的隐含字符串不是一个空字符串且字符串的最后一个字符不是一个空白字符,则向该字符串的结尾追加一个U+0020空白字符。
- 向DOMTokenList对象的隐含字符串的结尾追加token的值。
- 返回真。
一个DOMTokenList对象必须字符串化(stringify)到DOMTokenList对象的隐含字符串的值。
DOMSettableTokenList
DOMSettableTokenList接口与DOMTokenList接口相同,但是其允许直接修改隐含字符串。
interface DOMSettableTokenList : DOMTokenList {
attribute DOMString value;
};
tokenlist . value
返回隐含字符串。
可以被设置,以改变隐含字符串。
一个实现DOMSettableTokenList接口的对象的行为必须和DOMTokenList接口中定义的相同,但其中value属性在此定义。
value属性在获取时必须返回隐含字符串,在设置时必须用新值替换隐含字符串。
安全地传递结构体类型数据
若一个用户代理被要求获得一个值的结构体副本,其必须执行下列算法。该算法将返回一个独立的值或者抛出一个异常。
- 设输入为将要被复制的值。
- 设存储为成对的对象的相关联的列表,初始状态为空。其用于处理重复引用。对于每对对象,一个被称为源对象,另一个被称为目的对象。
- 设输出为使用输入和存储调用内部结构体复制算法的结果。
- 返回输出。
内部结构体复制算法调用时总是拥有两个参数——输入及存储,且其行为如下:
- 如果输入是存储之中某对对象的源,则返回该对对象的目标并跳过这些步骤。
- 如果输入是一个原始值(译:基本数据类型),则返回该值并跳过这些步骤。
- 如果输入值是一个对象。跳转至下列适当的步骤:
- 如果输入是一个布尔型(Boolean)对象
- 设输出为一个新的使用与输入相同的值构造的布尔型对象。
- 如果输入是一个数字(Number)对象
- 设输出为一个新的使用与输入相同的值构造的数字对象。
- 如果输入是一个字符串(String)对象
- 设输出为一个新的使用与输入相同的值构造的字符串对象。
- 如果输入是一个日期(Date)对象
- 设输出为一个新的使用与输入相同的值构造的日期对象。
- 如果输入是一个正则表达式(RegExp)对象
- 设输出为一个新的使用与输入相同的值构造的正则表达式对象。注:属性lastIndex的值不被复制。
- 设输出为一个新的使用与输入相同的值构造的正则表达式对象。
- 如果输入是一个图片数据(ImageData)对象
- 如果输入是一个文件(File)对象
- 设输出为一个包含相同隐含数据的新构造的文件对象。
- 如果输入是一个二进制大型对象(Blob)对象
- 设输出为一个包含相同隐含数据的新构造的二进制大型对象对象。
- 如果输入是一个文件列表(FileList)对象
- 如果输入是一个数组(Array)对象
- 设输出为一个新构造的空数组对象。
- 如果输入是一个对象(Object)对象
- 设输出为一个新构造的空对象对象。
- 如果输入为其他原生对象类型(例如:Error,Function)
- 如果输入为一个宿主对象(例如:一个DOM节点)
- 抛出一个DATA_CLONE_ERR异常并且跳过所有结构体复制算法。
- 如果输入是一个布尔型(Boolean)对象
- 向存储加一个一个从输入(源对象)到输出(目标对象)的映射。
- 如果输入是一个数组对象或对象对象,则对于输入中的每一个可列举的属性,向输出添加一个拥有相同名称的新的属性,其值为一个通过使用属性的值作为“输入”参数、存储作为“存储”参数递归调用内部结构体复制算法创建的值。输入和输出中属性的顺序必须相同。注:这不走的原型链。(This does not walk the prototype chain.)注:属性描述、设值方法、取值方法以及相同的特性不再此过程中复制。举例说明,输入中的属性可以被标为只读,但在输出中其仅拥有默认状态(通常情况下为读写状态,这取决于脚本环境)。
- 返回输出
DOMStringMap
DOMStringMap接口表示一系列名值对。
当一个DOMStringMap对象被实例化时,其与三个算法相关联。一个用于获取名值对列表、一个用于为某些值设置名称、一个用于删除指定名称。
interface DOMStringMap {
getter DOMString (in DOMString name);
setter void (in DOMString name, in DOMString value);
creator void (in DOMString name, in DOMString value);
deleter void (in DOMString name);
};
在某时刻,一个DOMStringMap对象的支持的属性名称为那一时刻获得名值对的算法所返回的结果中的每对名值对的名称。
对于DOMStringMap中的name,为了确定一个命名属性的值,用户代理必须返回获取名值对列表算法所返回的列表中名称部分为name的名值对的值部分。
为了设置一个新的或已有的名为name的属性的值为value,必须执行为某值设置名称的算法,其中name作为名称、将value转化为一个DOMString的结果作为值。
为了删除一个存在的命名属性name,必须执行删除命名的算法,其中name作为名称。
下面给出的片段及元素拥有相似的结果:
<img class="tower" id="tower5" data-x="12" data-y="5" data-ai="robotarget" data-hp="46" data-ability="flames" src="towers/rocket.png alt="Rocket Tower">
...可以想象一个方法splashDamage(),该方法拥有一些参数,其中第一个参数为正在处理的元素:
function splashDamage(node, x, y, damage) { if (node.classList.contains('tower') && // 检查'class'属性 node.dataset.x == x && // 读取'data-x'属性 node.dataset.y == y) { // 读取'data-y'属性 var hp = parseInt(node.dataset.hp); // 读取'data-hp'属性 hp = hp - damage; if (hp < 0) { hp = 0; node.dataset.ai = 'dead'; // 设置'data-ai'属性 delete node.dataset.ability; // 删除'data-ability'属性 } node.dataset.hp = hp; // 设置'data-hp'属性 } }
DOM特征字符串
DOM3 Core使用特征字符串定义了用于检查接口支持情况和获取接口实现的机制。[DOMCORE]
我们强烈的建议编码人员不要使用这些特征字符串,因为它们非常不可靠且不精确。我们鼓励编码人员对本规范中的一些特性进行明确的特征测试或适当的降级行为。
由于历史原因,用户代理在DOMImplementation接口的hasFeature(feature, version)方法被调用时返回真值,其中feature设为“HTML”或“XHTML”、version设为“1.0”或“2.0”。
异常
下列为DOMException码。[DOMCORE]
- INDEX_SIZE_ERR
- DOMSTRING_SIZE_ERR
- 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
- INVALID_STATE_ERR
- SYNTAX_ERR
- INVALID_MODIFICATION_ERR
- NAMESPACE_ERR
- INVALID_ACCESS_ERR
- VALIDATION_ERR
- TYPE_MISMATCH_ERR
- SECURITY_ERR
- NETWORK_ERR
- ABORT_ERR
- URL_MISMATCH_ERR
- QUOTA_EXCEEDED_ERR
- TIMEOUT_ERR
- DATA_CLONE_ERR
[Supplemental] exception DOMException {
const unsigned short URL_MISMATCH_ERR = 21;
const unsigned short QUOTA_EXCEEDED_ERR = 22;
const unsigned short DATA_CLONE_ERR = 25;
};
垃圾回收
存在一种从返回一个预先存在的对象的IDL属性到该对象的隐含的强关联。