HTML 导入

HTML 导入（或下文简称 imports）是 HTML 文档 [HTML]，它们被链接为外部资源，来源于另一个 HTML 文档。链接到 import 的文档称为 import referrer。对于任意给定的 import，其 import referrer ancestor 要么是它的 import referrer，要么是该 import referrer 的任何 import referrer ancestor。由于同一 import 可以从多个 import referrer 被引用，因此每个 import 都拥有一个或多个 import referrers 与 import referrer ancestors。

一个 import referrer 并非 import，即它不关联任何 import referrer，此类文档称为主文档。每个 import 与唯一的主文档关联：如果该 referrer 本身是主文档，则它就是该 import 的主文档。否则，该 import referrer 的主文档即为该 import 的主文档。

一个 URL 被称为 import location。

在每个 import referrer 中，import 以 Document [WHATWG-DOM] 的形式表现，称为 imported document。

问题 197: [imports]：导入与浏览上下文之间的关系应更清楚地说明 (bugzilla: 26682) html-imports needs-clarification

导入的文档并不存在浏览上下文。

与主文档关联的所有 import 组成该主文档的 import map。该映射以 import location 为键，import 为值进行存储。映射在开始时为空；在 import fetching algorithm 指定时会向映射添加新项。

为了跟踪已请求的 import，每个文档都有一个 import link list。每个条目由 link（即 link 元素）以及 location（URL）组成。条目还可以标记为分支。列表起始为空，条目按 import request 算法的规定加入。

每个 imported document 都有一个 import parent：如果文档 A 的 import link list 包含一个标记为分支的条目，其 location 指向文档 B，则 A 为 B 的 import parent。

每个 imported document 还拥有一个或多个 import ancestor：若文档 A 是文档 B 的 import parent，则 A 为 B 的 import ancestor。import ancestor 关系具传递性：如果 A 是 B 的 import parent，且 B 是 C 的 import parent，则 A 也同时是 C 的 import parent。

每个 imported document 还有一个或多个 import predecessor。若文档 A 的 URL 在文档 B 的 import parent 的 import link list 中位于文档 B 的 URL 之前，并且其对应的 link 被标记为分支，则 A 为 B 的 import predecessor。

文档 A 的 import ancestor predecessors 定义如下：若文档 B 为文档 C 的 import predecessor，且 C 为 A 的 import ancestor，则 B 为 A 的 import ancestor predecessor。

处于 import ancestor predecessors 或 import predecessors 中的 Document，或从文档 A 的 import link list 中标记为分支的条目链接而来，称为 A 的 import dependent。

import link list 与 import dependent 共同约束了导入中脚本的执行顺序。其目的是提供一个由每个 import 中的 link 元素顺序决定的确定性脚本执行顺序。每个节点的边按 import link list 的顺序排列。import predecessor 的选择也会考虑此顺序。

import link lists 的链接结构形成一个有向图。图中的每个节点对应一个文档，边对应一个 link。标记为分支的节点旨在形成该图的生成树。此树为脚本执行提供确定的顺序。

在图 1 中，

文档 A 拥有一个 import link list，其中包含指向 B 的链接以及指向 C 的另一个链接。
文档 D 有一对 import ancestors，分别是 A 与 B。
由于 B 是 D 的 import ancestor，因此指向 B 的 D 列表项未被标记为分支。
即使文档 D 同时被文档 B 与 C 链接，它的 import parent 仍为 B，因为 B 对 D 的 link 被标记为分支。
看 E
- E 没有任何 import predecessor。来自 C 指向 D 的链接未标记为分支，且指向 G 的链接也未位于指向 E 的链接之前。
- E 的 import ancestors 为 A 与 C。
- E 的 import ancestor predecessor 为 B，因为 C 的 import predecessor 为 B，而 A 没有 import predecessor。
- E 的 import link list 包含一个标记为分支的 H。
- 因此 E 的 import dependents 为 B（一个 import ancestor predecessor）以及 H（属于 import link list 的条目）。
看 G
- G 的 import predecessor 为 E。
- G 的 import ancestor predecessor 与 E 的相同，亦即 B。
- G 的 import link list 为空。
- 因此 G 的 import dependents 为 B（一个 import ancestor predecessor）以及 E（一个 import predecessor）。

import referrer 与 import parent 的区别在于：import referrer 反映节点树的状态，而 import parent 则由本文件所述算法构建。

为了在 HTML 中声明 import，向 HTML link types 中添加了新的链接类型。

关键词 import 可与 link 元素一起使用。此关键词会创建一个指向 import 的外部资源链接。

使用 import 关键字的资源默认类型为 text/html。

link 元素可以拥有 async 属性。async 属性是布尔属性。

获取资源的适当时机是当外部资源链接被创建或其元素被插入文档时，以两者较晚者为准。

无论 media 属性是否匹配环境，link 都会获取并应用 import。

示例 1

以下文档有一个 import，位于 /imports/heart.html

<!DOCTYPE html>
<html lang="en-US">
    <head>
        <title>Human Being</title>
        <link rel="import" href="/imports/heart.html">
    </head>
    <body>
        <p>What is a body without a heart?</p>
    </body>
</html>

WebIDLpartial interface HTMLLinkElement {
    readonly attribute Document? import;
};

在获取时，import 属性必须返回 null，如果

link 并未表示一个 import
该 link 元素不在 Document 中

否则，属性必须返回对应 imported document，该文档由 import，并由该 link 元素表示。

每次都应返回同一对象。

示例 2

下面展示了如何访问在前面的示例中提到的导入文档。

var link = document.querySelector('link[rel=import]');
var heart = link.import;
// Access DOM of the document in /imports/heart.html
var pulse = heart.querySelector('div.pulse');

在 Document（HTML 解析器或 XML 解析器）的上下文中出现的 import，如果满足以下条件，则被视为阻塞脚本的 import：该元素由该 Document 的解析器创建，且该元素为类型为 import 的 link，且该 link 未被标记为 async，且 import 尚未完全加载，并且在事件循环最近一次到达步骤 1 时，该元素正在该 Document 中，且用户代理尚未放弃该 import。用户代理可以在任何时候放弃一个 import。

注

在 import 加载完毕之前放弃它，即使之后它仍会加载，这意味着脚本可能会在信息不完整的情况下运行。例如，如果一个 import 注册了自定义元素，而脚本依赖该元素的可用性，则当用户代理过早放弃时，脚本会发现该元素不可用。实现者必须在脚本使用错误信息的可能性与因等待慢速网络请求而产生的性能影响之间取得平衡。

如果 Document 中存在阻塞脚本的 import，则该文档拥有阻塞脚本的 import。如果文档的 import dependent 中不存在此类 import，则该文档没有阻塞脚本的 import。

注

“拥有阻塞脚本的 import” 状态会在每次已有 import 完全加载或新的 import 加载启动时改变。HTML 解析器会在这些时机相应地解除阻塞。

将以下步骤作为定义的第一步

如果 Document 是 import，则抛出 InvalidStateError 异常。

将以下步骤作为定义的第一步

如果 Document 是 import，则抛出 InvalidStateError 异常。

将以下步骤作为定义的第一步

如果 Document 是 import，则抛出 InvalidStateError 异常。

在向 import link list 添加 link 后，需对 master document 运行 update marking 算法，等价于执行以下步骤。

输入：: DOCUMENT，即 Document

如果 DOCUMENT 是 master document，则取消标记 branch 状态的所有 links，以及与 DOCUMENT 关联的每个 imported document。
令 LIST 为 DOCUMENT 的 import link list。
对 LIST 中的每个 ITEM ……
1. 令 LOCATION 为 ITEM 的 location。
2. 令 IMPORT 为 URL 与 LOCATION 相同的 import。
3. 如果不存在另一个 link，其 location 与 LOCATION 相同且被标记为 branch，则将 ITEM 标记为 branch。
4. 如果 ITEM 已标记为 branch 且 IMPORT 不为 null，则调用 update marking 算法并传入 IMPORT。

当用户代理尝试获取已链接的 import 时，必须同时运行 import request 算法，等价于执行以下步骤。

输入：: LINK，创建指向 import 的 link 元素。; LOCATION，所链接资源的 URL。

如果 LINK 的 async 属性为 true，则将 LINK 标记为 async。
令 DOCUMENT 为 LINK 所在的文档。
令 LIST 为 DOCUMENT 的 import link list。
令 ITEM 为 LINK 与 LOCATION 的组合。
1. 将 ITEM 添加到 LIST 的末尾。
2. 使用 master document 调用 update marking 算法。

所有从 master document 或其 import map 中的 import，必须使用下面描述的 import fetching algorithm 进行获取，而非 HTML 所规定的获取已链接资源方法。

import fetching 算法必须等价于执行以下步骤。

输入：: LINK，一个创建指向 import 的 link 元素。; LOCATION，import location。
输出：: IMPORT，对应的 imported document。

如果 LOCATION 已存在于 import map 中
1. 令 IMPORT 为对应的 imported document，并停止。
获取资源 [Fetch] 从 LOCATION，请求的来源设置为主文档的主文档的来源，模式设为 CORS，凭据模式设为 same-origin。
1. 如果获取的响应类型为 error 或响应包含名称为 Content-Disposition 的头部
  - 将 LOCATION 与 null 加入导入映射并停止。
2. 令 IMPORT 为一个新的Document，其文档地址为 LOCATION
3. 令 PARSER 为一个新的HTML 解析器，并与 IMPORT 关联
4. 将 LOCATION 与 IMPORT 加入导入映射。
5. 对于在获取期间由网络任务源放置到任务队列的每个任务
  1. 用获取的字节填充 PARSER 的输入字节流
  2. 令 PARSER 以 utf-8 [WHATWG-ENCODING] 作为已知确定编码处理输入字节流
6. 当不再有可用字节时
  1. 将任务排入队列，来源为网络任务源，使 PARSER 处理隐含的 EOF 字符

注

所有已加载的导入以及正在加载的导入均位于导入链接列表中，因此列表中任何导入所链接的导入也将使用导入获取算法进行加载，LOCATION 为该导入的导入位置。

如果算法完成时 IMPORT 不为 null，则该加载尝试 MUST 被视为成功；否则视为失败。

每个未被标记为 async 的延迟文档的 load 事件的导入。

注

link 元素在加载成功时触发一个名为load的简单事件。若加载失败，则触发一个名为error的简单事件。

由于导入会延迟 load 事件，Document 在其所有已链接导入的加载尝试完成之前并非完全加载。

内容安全策略 [CSP3] MUST 通过script-src指令限制导入加载。

每个导入 MUST 受其主文档的内容安全策略约束。例如，如果向导入发送了内容安全头字段，用户代理 MUST 强制执行主文档的策略于被导入的文档。

导入的解析行为被定义为对HTML 解析的一组更改。

在准备脚本算法的第 15 步中，修改以 如果元素没有 src 属性 开头的条件的最后部分，使其读取

...以及创建 Document 的HTML 解析器或XML 解析器的script 元素有阻止脚本执行的样式表或有阻止脚本执行的导入

在12.2.5.4.1 “initial” 插入模式章节的 DOCTYPE 部分，修改文本 if the document is not an iframe srcdoc document... 为

if the document is not an iframe src document nor an import...

在“text” 插入模式中，条件 An end tag whose name is "script" 的子条件 Otherwise 中，将第 3 步修改为

如果解析器的Document 有阻止脚本的样式表或有阻止脚本的导入或该脚本的“ready to be parser‑executed” 标志未被设置：旋转事件循环，直至解析器的Document 没有阻止脚本的样式表且没有阻止脚本的导入且该脚本的“ready to be parser‑executed” 标志被设置。

修改在准备 script 元素后运行的步骤第 3 步，使其读取

旋转事件循环，直至解析器的Document 没有阻止脚本的样式表且没有阻止脚本的导入且pending parsing‑blocking script 的“ready to be parser‑executed” 标志被设置。

style 元素的内容以及link 元素的外部资源在导入中MUST 被视为样式处理模型 [CSS2] 的输入来源，适用于主文档。

与主文档关联的一组导入形成一个导入链接树，即树形结构。依据导入链接树形成算法，使用null 作为 PARENT，主文档作为 TREE，并将其所有导入作为 POOL，即可定义导入链接树。

输入：: PARENT，文档树节点; CURRENT，文档; POOL，文档列表
输出：: TREE，文档树

令 TREE 为树节点。
令 TREE 的值为 CURRENT
令 TREE 的父节点为 PARENT。
将 TREE 的子节点列表设为空。
遍历 CURRENT 中的每个 LINK（即导入的 link 元素），按文档顺序
1. 令 IMPORT 为 LINK 所指的导入。
2. 若 IMPORT 不在 POOL 中，跳到下一个。
3. 从 POOL 中移除 LINK。
4. 以 TREE 作为 PARENT、IMPORT 作为 CURRENT、POOL 仍为 POOL，调用导入链接树形成算法，令结果为 CHILD。
5. 将 CHILD 追加到 TREE 的子节点列表中。
stop.

注

导入链接树算法使用深度优先遍历定义导入的顺序。此导入链接树不同于导入链接列表形成的结构。前者基于每个导入的文档树，后者则通过导入加载过程构建，且不受文档树变动的影响。

来自不同文档的声明的出现顺序 [CSS-CASCADE-3] 由导入链接树决定。若两条声明所属的节点文档不同，则比较它们在导入链接树中的树序，后者获胜。

本规范将custom element order（自定义元素顺序）重新定义为[CUSTOM-ELEMENTS]的自定义元素顺序与导入树顺序之和，其中导入树顺序会被缩放，使其最低值始终大于[CUSTOM-ELEMENTS]的自定义元素顺序可能的最高值。

给定自定义元素在导入链接树中的导入树顺序由树序决定，前提是该导入链接树已通过将每个导入的link 替换为其被导入文档的内容后进行扁平化。

最高稳定顺序是指在第一次遇到的导入中，自定义元素顺序之前的那个值（依据树序），且该导入尚未完全加载。如果不存在这样的元素，则最高稳定顺序为扁平化导入链接树中最高的自定义元素顺序。在处理基元素队列时，用户代理应只调用至最高稳定顺序（含）之前的回调。

注

由于导入是异步加载的，我们需要把已排序的元素队列拆分为两部分：一部分是所有导入已经加载完毕、状态已稳定的部分，另一部分是仍在加载、实际排序尚未确定的部分。例如，假设你有如下文档结构

index.html

<link rel="import" href="import.html">
...
<me-second></me-second>
...

import.html

<me-first></me-first>

在扁平化的导入链接树中，自定义元素的顺序为 me-first（1），me-second（2）。然而，解析器很可能会先发现 me-second，因为后者不需要加载 import.html。当网络栈完成工作时，最高稳定顺序仍停留在起始位置。一旦 import.html 准备就绪，顺序会直接跳到 me-second（2）。

David Hyatt 开发了 XBL 1.0，而 Ian Hickson 与其共同编写了 XBL 2.0。这些文档为行为附件问题提供了大量洞见，并深刻影响了本规范。

Alex Russell 及其深谋远虑的构想在行为附件以及其在 Web 上的实际应用方面掀起了新一轮热潮。

Dominic Cooney 与 Roland Steiner 不懈努力，在 Web 平台范围内界定了问题的边界，为本文件奠定了坚实的基础。

编辑者还想感谢 Alex Komoroske、Angelina Fabbro、Anne van Kesteren、Boris Zbarsky、Brian Kardell、Daniel Buchner、Edward O'Connor、Eric Bidelman、Erik Arvidsson、Elliott Sprehn、Gabor Krizsanits、Hayato Ito、James Simonsen、Jonas Sicking、Ken Shirriff、Neel Goyal、Olli Pettay、Rafael Weinstein、Scott Miles、Steve Orvell、Tab Atkins、William Chan 与 William Chen 对本规范的评论与贡献。

此名单过于简短，仍有大量工作待完成。请通过审阅并提交错误报告来贡献力量——并别忘了请编辑者把你的名字加入本节。

[CSP3]: Content Security Policy Level 3. Mike West; Antonio Sartori. W3C. 2023 年 5 月 3 日. W3C Working Draft. URL: https://w3org.cn/TR/CSP3/
[CSS-CASCADE-3]: CSS Cascading and Inheritance Level 3. Elika Etemad; Tab Atkins Jr.. W3C. 2021 年 2 月 11 日. W3C Recommendation. URL: https://w3org.cn/TR/css-cascade-3/
[CSS2]: Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. Bert Bos; Tantek Çelik; Ian Hickson; Håkon Wium Lie. W3C. 7 June 2011. W3C Recommendation. URL: https://w3org.cn/TR/CSS21/
[CUSTOM-ELEMENTS]: Custom Elements. Domenic Denicola. W3C. 2018 年 5 月 3 日. W3C Working Group Note. URL: https://w3org.cn/TR/custom-elements/
[Fetch]: 获取 (Fetch) 标准. Anne van Kesteren. WHATWG. 活标准. URL: https://fetch.spec.whatwg.org/
[HTML]: HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.whatwg.cn/multipage/
[RFC2119]: Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. 1997年3月. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC8174]: RFC 2119 关键词中大小写的歧义. B. Leiba. IETF. 2017年5月. 最佳当前实践. URL: https://www.rfc-editor.org/rfc/rfc8174
[WHATWG-DOM]: DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[WHATWG-ENCODING]: 编码标准. Anne van Kesteren. WHATWG. 活标准. URL: https://encoding.spec.whatwg.org/

摘要

本文档状态

1. 一致性

2. 术语

2.1 导入依赖者

3. 链接类型 “`import`”

4. 对 `HTMLLinkElement` 接口的扩展

5. 对 `Document` 接口的扩展

5.1 对 `document.open()` 方法的补充

5.2 对 `document.write()` 方法的补充

5.3 对 `document.close()` 方法的补充

6. 加载导入

6.1 更新分支

6.2 请求导入

6.3 获取导入

6.4 导入与内容安全策略

7. 解析导入

7.1 对 Prepare A Script 算法的补充

7.2 对树构建算法的补充

7.3 对解析 XHTML 文档的补充

8. 导入中的脚本

8.1 对脚本启用条件的补充

8.2 对 `document.currentScript` 的补充

9. 使用导入的样式处理

9.1 导入链接树

9.2 出现顺序与导入

10. 导入中的事件

10.1 对事件处理程序的补充

11. 自定义元素处理

A. 致谢

B. 参考资料

B.1 规范性参考资料

HTML 导入

摘要

本文档状态

1. 一致性

2. 术语

2.1 导入依赖者

3. 链接类型 “import”

4. 对 HTMLLinkElement 接口的扩展

5. 对 Document 接口的扩展

5.1 对 document.open() 方法的补充

5.2 对 document.write() 方法的补充

5.3 对 document.close() 方法的补充

6. 加载导入

6.1 更新分支

6.2 请求导入

6.3 获取导入

6.4 导入与内容安全策略

7. 解析导入

7.1 对 Prepare A Script 算法的补充

7.2 对树构建算法的补充

7.3 对解析 XHTML 文档的补充

8. 导入中的脚本

8.1 对脚本启用条件的补充

8.2 对 document.currentScript 的补充

9. 使用导入的样式处理

9.1 导入链接树

9.2 出现顺序与导入

10. 导入中的事件

10.1 对事件处理程序的补充

11. 自定义元素处理

A. 致谢

B. 参考资料

B.1 规范性参考资料

3. 链接类型 “`import`”

4. 对 `HTMLLinkElement` 接口的扩展

5. 对 `Document` 接口的扩展

5.1 对 `document.open()` 方法的补充

5.2 对 `document.write()` 方法的补充

5.3 对 `document.close()` 方法的补充

8.2 对 `document.currentScript` 的补充