HTML5/dom

HTML文档的语义、结构及API

文档

在HTML用户代理中，每个XML和HTML文档都表现为一个Document对象。

文档的地址是一个在Document对象被创建是设置的绝对URL。文档的当前地址是一个可以在Document对象生命周期内被修改的绝对URL。举例说明，当用户导航到一个页面的片段标识时，或者使用一个新的URL调用pushState()方法时，文档的当前地址将被修改。在Document对象被创建时，文档的当前地址必须被设为文档的地址。

当通过createDocument()或createHTMLDocument() API创建一个Document对象时，文档的地址与脚本程序的文档的文档的地址相同。

当Document对象被创建时，除非它们被标记为HTML文档，否则将被假定为XML文档。一个文档是HTML文档还是XML文档将影响某些API的行为和一些选择器的大小写区分情况。

每个Document对象拥有一个原本未设置的重载覆盖标志。该标志在某些情况下通过document.open()和document.write()方法设置。若设置了该标志，Document对象同时还拥有一个重载覆盖缓冲区，该缓冲区是一个用作文档在被重载之后的源的Unicode字符串。

当用户代理执行一个覆盖的重载时，必须执行下列操作：

1. 设source为浏览器上下文的活动文档的重载覆盖缓冲区的值。
2. 通过启用更换（replacement enabled）导航浏览器上下文到源为source的资源。当导航算法为此目的而创建一个Document对象时，设置该Document对象的重载覆盖标志并设置它的重载覆盖缓冲区为source。

DOM中的文档

所有Document对象（对于实现本标准的用户代理而言）必须实现HTMLDocument接口，这可以通过绑定机制实现。（也就是说，文档是不是一个HTML文档，甚至是不是包含任何HTML元素都无所谓）对于用户代理支持的其他命名空间，Document对象必须实现对应的文档级别的接口。

[OverrideBuiltins]
interface HTMLDocument {
  // 资源元数据管理属性
  [PutForwards=href] readonly attribute Location location;
  readonly attribute DOMString URL;
           attribute DOMString domain;
  readonly attribute DOMString referrer;
           attribute DOMString cookie;
  readonly attribute DOMString lastModified;
  readonly attribute DOMString compatMode;
           attribute DOMString charset;
  readonly attribute DOMString characterSet;
  readonly attribute DOMString defaultCharset;
  readonly attribute DOMString readyState;

  // DOM树访问接口
  getter any (in DOMString name);
           attribute DOMString title;
           attribute DOMString dir;
           attribute HTMLElement body;
  readonly attribute HTMLHeadElement head;
  readonly attribute HTMLCollection images;
  readonly attribute HTMLCollection embeds;
  readonly attribute HTMLCollection plugins;
  readonly attribute HTMLCollection links;
  readonly attribute HTMLCollection forms;
  readonly attribute HTMLCollection scripts;
  NodeList getElementsByName(in DOMString elementName);
  NodeList getElementsByClassName(in DOMString classNames);
  NodeList getItems(in optional DOMString typeNames); // microdata 
  readonly attribute DOMElementMap cssElementMap;

  // 动态标签插入接口
           attribute DOMString innerHTML;
  HTMLDocument open(in optional DOMString type, in optional DOMString replace);
  WindowProxy open(in DOMString url, in DOMString name, in DOMString features, in optional boolean replace);
  void close();
  void write(in DOMString... text);
  void writeln(in DOMString... text);

  // 用户交互接口
  readonly attribute WindowProxy defaultView;
  readonly attribute Element activeElement;
  boolean hasFocus();
           attribute DOMString designMode;
  boolean execCommand(in DOMString commandId);
  boolean execCommand(in DOMString commandId, in boolean showUI);
  boolean execCommand(in DOMString commandId, in boolean showUI, in DOMString value);
  boolean queryCommandEnabled(in DOMString commandId);
  boolean queryCommandIndeterm(in DOMString commandId);
  boolean queryCommandState(in DOMString commandId);
  boolean queryCommandSupported(in DOMString commandId);
  DOMString queryCommandValue(in DOMString commandId);
  readonly attribute HTMLCollection commands;

  // 事件接口
           attribute Function onabort;
           attribute Function onblur;
           attribute Function oncanplay;
           attribute Function oncanplaythrough;
           attribute Function onchange;
           attribute Function onclick;
           attribute Function oncontextmenu;
           attribute Function oncuechange;
           attribute Function ondblclick;
           attribute Function ondrag;
           attribute Function ondragend;
           attribute Function ondragenter;
           attribute Function ondragleave;
           attribute Function ondragover;
           attribute Function ondragstart;
           attribute Function ondrop;
           attribute Function ondurationchange;
           attribute Function onemptied;
           attribute Function onended;
           attribute Function onerror;
           attribute Function onfocus;
           attribute Function oninput;
           attribute Function oninvalid;
           attribute Function onkeydown;
           attribute Function onkeypress;
           attribute Function onkeyup;
           attribute Function onload;
           attribute Function onloadeddata;
           attribute Function onloadedmetadata;
           attribute Function onloadstart;
           attribute Function onmousedown;
           attribute Function onmousemove;
           attribute Function onmouseout;
           attribute Function onmouseover;
           attribute Function onmouseup;
           attribute Function onmousewheel;
           attribute Function onpause;
           attribute Function onplay;
           attribute Function onplaying;
           attribute Function onprogress;
           attribute Function onratechange;
           attribute Function onreadystatechange;
           attribute Function onreset;
           attribute Function onscroll;
           attribute Function onseeked;
           attribute Function onseeking;
           attribute Function onselect;
           attribute Function onshow;
           attribute Function onstalled;
           attribute Function onsubmit;
           attribute Function onsuspend;
           attribute Function ontimeupdate;
           attribute Function onvolumechange;
           attribute Function onwaiting;
};
Document implements HTMLDocument;

由于HTMLDocument接口定义了几个不同特性的方法和属性，它的成员将在不同的章节中分别介绍。

安全

当一个HTMLDocument对象被一个脚本访问，且这个脚本的有效脚本源和文档的有效脚本源不同时，用户代理必须抛出一个SECURITY_ERR异常。

资源元数据管理

URL屬性需要返回文档地址。

referrer属性需要返回任意<fragment>组件删除后导航操作开始时（将浏览器上下文导航到当前文档的页面）资源浏览器上下文的活动文档的当前地址，或者当没有这样的原始页面、用户代理被设置为在这种情况下不报告引用、以及导航是通过包含noreferrer关键字的超链接启动的情况下，返回空字符串。

cookie属性表示创建Document所用资源的cookie。

一个Document对象如果满足一下几条之一，则在对象是无CookieDocument对象：

• Document没有浏览器上下文。
• Document的地址没有使用基于服务器的命名机构。

当获取Cookie时，如果文档是一个无CookieDocument对象，则用于代理必须返回空字符串。否则，如果Document的源不是“协议/主机/端口”元组，用户代理必须抛出SECURITY_ERR异常。否则，用户代理必须首先“获得存储互斥”之后返回一个“non-HTTP”API的文档地址的用UTF-8解码且包含错误处理的Cookie字符串。[COOKIES]

当设置Cookie时，如果文档是一个无CookieDocument对象，则用户代理必须停止执行操作。否则，如果Document的源不是“协议/主机/端口”元组，用户代理必须抛出SECURITY_ERR异常。否则，用户代理必须首先“获得存储互斥”之后执行操作，将通过“non-HTTP”API收到的一个文档地址的设置Cookie字符串用UTF-8编码并构成一个新的值。[COOKIES] [RFC3629]

当获取lastModified属性时，必须返回Document源文件的最后修改的日期和时间，日期和时间为用户所在的时区，且遵循以下格式：

1. 日期的月份部分
2. 一个U+002F斜线号字符（/）
3. 日期的天数部分
4. 一个U+002F斜线号字符（/）
5. 日期的年份部分
6. 一个U+0020空格字符
7. 时间的小时部分
8. 一个U+003A冒号字符
9. 时间的分钟部分
10. 一个U+003A冒号字符
11. 时间的秒钟部分

以上所有的数字部分，除年份以外，都必须由两个U+0030数字零（0）至U+0039数字九（9）之间的十进制数字组成，如果必要使用零填充。年份必须由四位或四位以上尽可能短的U+0030数字零（0）到U+0039数字九（9）组成的十进制数字，如果必要使用零填充。

Document源文件的最近修改的日期和时间必须必须来源于网络所使用的协议的相关特征，例如：来源于文档的HTTP Last-Modified头的值，或者本地文件系统中的元数据（metadata）。如果最近修改的日期和时间不确定，这个属性必须返回遵循上述格式的当前的日期和时间。

Document被划分为三种模式：默认的非怪癖模式（no-quirks mode）、通常用于旧文档的怪癖模式（quirks mode）以及被认为“几乎标准”模式的“限制怪癖模式（limited-quirks mode）。模式只能由HTML解释器基于文档类型声明（DOCTYPE）字符串是否存在以及它的值从默认模式修改。

如果文档没有被HTML解释器设置为怪癖模式，则compatModeIDL属性必须返回字符串“CSS1Compat”，否则应返回字符串“BackCompat”。

文档拥有一个关联的字符编码。当Document对象被创建时，文档的字符编码必须被初始化为UTF-16。在页面加载过程中，各种算法通过charset设值函数影响它的值。[IANACHARSET]

当获取charsetIDL属性时，必须返回文档的字符编码的首选MIME名称。当设置charsetIDL属性时，如果新值是浏览器支持的IANA注册的别名，则文档的字符编码必须被设置为这个字符编码。（否则不进行操作）

当获取characterSetIDL属性时，必须返回文档的字符编码的首选MIME名称。

当获取defaultCharsetIDL属性时，必须返回字符编码的首选MIME名称。该字符编码可能是用户的默认编码，也可能是关于用户当前地理位置的编码，或者任意的编码名称。

每个文档都有一个当前文档准备（current document readiness）。当一个Document对象被创建时，该文档必须拥有它的当前文档准备。如果该文档与HTML解释器或XML解释器相关，那么当前文档准备应设为字符串“loading”；否则设为字符串“complete”。页面加载过程中，各种算法将影响此值。当这个值被设置时，用户代理必须触发一个Document对象的名为readystatechange的简单事件。

如果一个Document与HTML解释器或XML解释器相关，且解释器尚未结束或终止，则称该Document拥有一个活动的解释器（active parser）。

当获取readyStateIDL属性时，必须当前文档准备。

DOM树存取器

如果存在一个文档的html元素，则它是文档的根元素。否则html元素为null。

如果存在一个文档的head元素，则它是html元素子元素中的的第一个head元素。否则head元素为null。

当获取head属性时，必须返回当前文档的head元素（一个head元素或null）。

如果存在一个文档的title元素，则它是文档中的第一个title元素（在树结构中），否则title元素为null。

当获取title属性时，运行下列算法：

1. 如果根元素是一个拥有“http://www.w3.org/2000/svg ”命名空间的svg元素，且用户代理支持SVG，则返回SVGDocument接口中同名的IDL属性所返回的值。[SVG]
2. 否则，将值设置为树结构中title所有子文本节点的数据的数据连接。如果title元素为null，则返回空字符串。
3. 将值中任何单一或连续的空白字符替换为一个单独的U+0020空格字符。
4. 去除值中开头或结尾的空白字符。
5. 返回值。

当设置title属性时，必须运行下列算法。突变事件必须被适当的出发。

1. 如果根元素是一个拥有“http://www.w3.org/2000/svg ”命名空间的svg元素，且用户代理支持SVG，则设值函数必须把操作交由SVGDocument接口中同名的IDL属性的设值函数进行（如果后者为只读，则抛出异常），并在此处结束算法。[SVG]
2. 如果title元素和head元素均为空，则属性必须不进行任何操作，且在此处结束算法。
3. 如果title元素为空，则新建一个新的title元素，将其追加至head元素之中，并将元素设为新建的元素。否则将元素设为title元素。
4. 必须将元素的所有子节点（如果存在）移除。
5. 一个独立的数据为被分配的值的Text节点必须被追加到元素之中。

如果用户代理同时支持HTML及SVG，则HTMLDocument接口中的title属性应该与SVGDocument接口制动同名属性相同。[SVG]

文档的body元素是html元素子元素中的第一个body或frameset元素。如果没有这样的元素，则body元素为null，进而，规范要求的由“body元素”触发的时间需要由Document对象代为触发。

当获取body属性时，必须返回当前文档的body元素（body元素、frameset元素或null）。当设置body属性时，必须执行下列算法：

1. 如果新值不是body或frameset元素，则抛出一个HIERARCHY_REQUEST_ERROR_ERR异常，且在此处结束算法。
2. 否则，如果新值与body元素相同，则不进行操作，且在此处结束算法。
3. 否则，如果body元素为null，则使用DOM中的新值替换该元素。操作与调用根元素的replaceChild()方法相同，其中两个参数分别为新值和当前body元素。之后在此处结束算法。
4. 否则，body元素为空。将新值追加到根元素中。

images属性必须返回一个根植于Document节点的HTMLCollection，其过滤器仅匹配img元素。

embeds属性必须返回一个根植于Document节点的HTMLCollection，其过滤器仅匹配embed元素。

plugins属性必须返回与embeds属性相同的对象。

links属性必须返回一个根植于Document节点的HTMLCollection，其过滤器仅匹配拥有href属性的a元素和area元素。

forms属性必须返回一个根植于Document节点的HTMLCollection，其过滤器仅匹配form元素。

scripts属性必须返回一个根植于Document节点的HTMLCollection，其过滤器仅匹配script元素。

getElementsByName(name)方法以一个字符串name为参数，并且必须返回一个包含文档树结构中所有特定的HTML元素的活动的（live）NodeList，这些元素的name属性的值与name参数相等（区分大小写）。如果方法被Document对象使用相同的参数重复调用，则用户代理可以返回与之前调用返回值相同的对象。其他情况下，则必须返回一个新的NodeList对象。

getElementsByClassName(classNames)方法以一个由表示class的标记以空格分隔所组成的字符串作为参数。当调用该方法时，必须返回一个包含文档树结构中所有特定的元素的活动的（live）NodeList对象。这些元素的class被指定为参数值。class通过按空格分隔字符串（忽略重复）获得。如果参数中没有指定class标记，则方法必须返回一个空的NodeList。如果文档为怪癖模式，则对class的比较必须采用ASCII不分大小写方式进行，否则，必须采用区分大小写方式进行。如果方法被Document对象使用相同的参数重复调用，则用户代理可以返回与之前调用返回值相同的对象。其他情况下，则必须返回一个新的NodeList对象。

HTMLElement接口下的getElementsByClassName(classNames)方法必须返回一个活动的（live）NodeList，其中的节点为HTMLDocument的getElementsByClassName()方法使用相同参数所返回的节点，其中不包括调用当前方法的HTMLElement对象的子节点以外的所有节点。如果方法被一个HTMLElement对象使用相同的参数重复调用，则用户代理可以返回与之前调用返回值相同的对象。其他情况下，则必须返回一个新的NodeList对象。

HTML、SVG和MathML元素通过一个不含命名空间的名为class的属性定义了它们所在的class，该属性的值为使用空格分隔的这些元素所属的class的列表。其他规范可能同时允许元素使用命名空间来标记它们属于特殊的class。

<div id="example">
  <p id="p1" class="aaa bbb"/>
  <p id="p2" class="aaa ccc"/>
  <p id="p3" class="bbb ccc"/>
</div>

HTMLDocument接口支持命名属性。在任何时候，支持的属性名包括： Document中拥有name内容属性的applet、embed、form、iframe、img和fallback-free对象元素的name内容属性的值； Document中拥有id内容属性的applet和fallback-free对象元素的id内容属性的值； Document中同时拥有id和name内容属性的imgid内容属性的值；

当HTMLDocument通过一个名为name的属性检索进行索引，用户代理必须通过执行下列步骤获得返回值：

1. 设elements为Document中的名为name的已命名元素列表。
   注：根据定义，至少要有一个这样的元素。
2. 如果elements中仅包含一个元素，且该元素是一个iframe元素，则返回iframe元素说代表的嵌套浏览器上下文的WindowProxy对象，之后在此处结束算法。
3. 否则，如果elements中仅包含一个元素，则返回该元素，之后在此处结束算法。
4. 否则，返回一个植根于Document节点的HTMLCollection，其过滤器仅匹配名为name的已命名元素。

对于上述算法，名为name的已命名元素指的是：

1. 拥有name内容属性且其值为name的applet、embed、form、img或fallback-free对象元素。或
2. 拥有id内容属性且其值为name的applet或fallback-free对象元素。或
3. 拥有id和name内容属性且id属性值为name的img元素。

如果一个object元素没有object或embed的后裔，则其被称为fallback-free。

创建文档

XML文档可以通过脚本程序在DOMImplementation接口上使用createDocument()方法创建。

HTML文档可以使用createHTMLDocument()方法创建：

[Supplemental, NoInterfaceObject]
interface DOMHTMLImplementation {
  Document createHTMLDocument(in DOMString title);
};
DOMImplementation implements DOMHTMLImplementation;

当调用createHTMLDocument(title)方法时，必须执行下列步骤：

1. 设doc为一个新创建的Document对象。
2. 标记doc为一个HTML文档。
3. 创建一个DocumentType节点，该节点的name属性被设为“html”，其他DocumentType对象的具体属性根据各自情况被设为空字符串、null或空列表。向doc中追加新创建的节点。
4. 创建一个html元素，将其追加到doc之中。
5. 创建一个head元素，将其追加到上一步创建的html元素之中。
6. 创建一个title元素，将其追加到上一步创建的head元素之中。
7. 创建一个Text节点，将其data属性设为方法参数所给出的字符串（可能为空字符串），将其追加到上一步创建的title元素之中。
8. 创建一个body元素，将其追加到早前几步创建的html元素之中。
9. 返回doc。

加载XML文档

一个由DOMImplementation.createDocument()工厂方法创建的XML文档的Document对象，必须同时实现XMLDocumentLoader接口：

[Supplemental, NoInterfaceObject]
interface XMLDocumentLoader {
  boolean load(in DOMString url);
};

load(url)方法必须执行下列步骤：

1. 设document为调用方法的Document对象。
2. 相对于入口脚本（entry script）的基本URL（base URL）分析方法的第一个参数。如果不成功，抛出一个SYNTAX_ERR异常，之后在此处结束算法。否则，设url为分析所得的绝对URL。
3. 如果url的源与document的源不相同，则抛出一个SECURITY_ERR异常，之后在此处结束算法。
4. 在不触发任何突变实践的情况下，移除document的所有孩子结点。
5. 将document的当前文档准备设为“loading”。
6. 异步地执行下列步骤，并且从方法中返回true。
7. 设result为一个Document对象。
8. 设success为false。
9. 从document的源中提取（Fetch）url，并且设置同步标记（synchronous flag）和强制同源标记（force same-origin flag）。
10. 如果提取成功，并且资源的内容类型元数据（Content-Type metadata）为XML MIME类型，则执行下列分步骤：
    1. 创建一个与result文档关联的新的XML解析器。
    2. 通过这个解析器提取文档。
    3. 如果出现XML良构（well-formedness）或XML命名空间良构错误，则移除result中的所有子节点。否则设success为true。
11. 排队任务执行下列步骤：
    1. 设置document的当前文档准备为“complete”。
    2. 使用result的子节点（即使其没有子节点）替换所有document的子节点，触发与插入包含新的子节点的DocumentFragment时相同的突变事件。
    3. 触发document的一个名为load的简单事件。