1. 7.10 Browsing the web
      1. 7.10.1 Navigating across documents
      2. 7.10.2 HTML 文件的页面加载处理模型
      3. 7.10.3 XML 文件的页面加载处理模型
      4. 7.10.4 文本文件的页面加载处理模型
      5. 7.10.5 multipart/x-mixed-replace 资源的媒体的页面加载处理模型
      6. 7.10.6 媒体的页面加载处理模型
      7. 7.10.7 使用插件的内容的页面加载处理模型
      8. 7.10.8 没有 DOM 的内联内容的页面加载处理模型
      9. 7.10.9 Navigating to a fragment
      10. 7.10.10 History traversal
        1. 7.10.10.1 Persisted history entry state
        2. 7.10.10.2 The PopStateEvent interface
        3. 7.10.10.3 The HashChangeEvent interface
        4. 7.10.10.4 The PageTransitionEvent interface
      11. 7.10.11 Loading documents
      12. 7.10.12 Unloading documents
        1. 7.10.12.1 The BeforeUnloadEvent interface
      13. 7.10.13 Aborting a document load
      14. 7.10.14 The `X-Frame-Options` header

7.10 Browsing the web

Certain actions cause the browsing context to navigate to a new resource. A user agent may provide various ways for the user to explicitly cause a browsing context to navigate, in addition to those defined in this specification.

For example, following a hyperlink, form submission, and the window.open() and location.assign() methods can all cause a browsing context to navigate.

A resource has a URL, but that might not be the only information necessary to identify it. For example, a form submission that uses HTTP POST would also have the HTTP method and payload. Similarly, an iframe srcdoc document needs to know the data it is to use.

Much of the navigation process is concerned with determining how to create a new Document, which ultimately happens in the create and initialize a Document object algorithm. The parameters to this algorithm are tracked via a navigation params struct, which has the following items:

request
null or a request that started the navigation
response
a response that ultimately was navigated to (potentially a network error)
origin
an origin to use for the new Document
final sandboxing flag set
a sandboxing flag set to impose on the new Document
cross-origin opener policy
a cross-origin opener policy to use for the new Document
reserved environment
null or an environment reserved for the new Document
browsing context
the browsing context to be navigated (but see below)
browsing context switch needed
a boolean indicating whether or not the navigation should conclude by discarding the given browsing context and creating a new one
history handling
a history handling behavior

Once a navigation params struct is created, this standard does not mutate any of its items. They are only passed onward to other algorithms.

After Document creation, the session history gets updated. A history handling behavior is used to track the desired type of session history update throughout the navigation process. It is one of the following:

"default"
A regular navigation which adds a new entry to the session history.
"entry update"
A navigation to an existing session history entry to recreate that entry's document, which was previously discarded.
"reload"
A navigation intended to reload the current page and replace the current session history entry.
"replace"
A non-reload navigation that will replace the current session history entry.

Navigation always involves source browsing context, which is the browsing context which was responsible for starting the navigation.

As explained in issue #1130 the use of a browsing context as source might not be the correct architecture.

To navigate a browsing context browsingContext to a resource resource, with an optional boolean exceptionsEnabled (default false), an optional history handling behavior historyHandling (default "default"), and an optional string navigationType (default "other"):

  1. If resource is a URL, then set resource to a new request whose url is resource.

  2. If resource is a request and historyHandling is "reload", then set resource's reload-navigation flag.

  3. If there is a preexisting attempt to navigate browsingContext, and the source browsing context is the same as browsingContext, and that attempt is currently running the unload a document algorithm, then return without affecting the preexisting attempt to navigate browsingContext.

  4. If the prompt to unload algorithm is being run for the active document of browsingContext, then return without affecting the prompt to unload algorithm.

  5. Let activeDocumentNavigationOrigin be the origin of the active document of browsingContext.

  6. Let incumbentNavigationOrigin be the origin of the incumbent settings object, or if no script was involved, the origin of the node document of the element that initiated the navigation.

  7. Cancel any preexisting but not yet mature attempt to navigate browsingContext, including canceling any instances of the fetch algorithm started by those attempts. If one of those attempts has already created and initialized a new Document object, abort that Document also. (Navigation attempts that have matured already have session history entries, and are therefore handled during the update the session history with the new page algorithm, later.)

  8. Prompt to unload the active document of browsingContext. If the user refused to allow the document to be unloaded, then return.

    If this instance of the navigation algorithm gets canceled while this step is running, the prompt to unload algorithm must nonetheless be run to completion.

  9. Abort the active document of browsingContext.

  10. If browsingContext is a child browsing context, then put it in the delaying load events mode.

    The user agent must take this child browsing context out of the delaying load events mode when this navigation algorithm later matures, or when it terminates (whether due to having run all the steps, or being canceled, or being aborted), whichever happens first.

  11. Let sandboxFlags be the result of determining the creation sandboxing flags given browsingContext and browsingContext's container.

  12. Return to whatever algorithm invoked the navigation steps and continue running these steps in parallel.

  13. This is the step that attempts to obtain resource, if necessary. Jump to the first appropriate substep:

    If resource is a response
    1. Assert: browsingContext is not a top-level browsing context.

    2. Let finalSandboxFlags be the union of browsingContext's sandboxing flags and resource's forced sandboxing flag set.

    3. Let responseOrigin be the result of determining the origin given browsingContext, resource's url, finalSandboxFlags, incumbentNavigationOrigin, and activeDocumentNavigationOrigin.

    4. Let navigationParams be a new navigation params whose request is null, response is resource, origin is responseOrigin, final sandboxing flag set is finalSandboxFlags, cross-origin opener policy is "unsafe-none", reserved environment is null, browsing context is browsingContext, browsing context switch needed is false, and history handling is historyHandling.

    5. Run process a navigate response with navigationType, the source browsing context, and navigationParams.

    If resource is a request whose url's scheme is "javascript"

    Queue a global task on the DOM manipulation task source given browsingContext's active window to run these steps:

    1. Let response be the result of executing a javascript: URL request given resource, the source browsing context, and browsingContext.

    2. Let finalSandboxFlags be the union of browsingContext's sandboxing flags and response's forced sandboxing flag set.

    3. Let navigationParams be a new navigation params whose request is resource, response is response, origin is activeDocumentNavigationOrigin, final sandboxing flag set is finalSandboxFlags, cross-origin opener policy is browsingContext's active document's cross-origin opener policy, reserved environment is null, browsing context is browsingContext, browsing context switch needed is false, and history handling is historyHandling.

    4. Run process a navigate response with navigationType, the source browsing context, and navigationParams.

    So for example a javascript: URL in an href attribute of an a element would only be evaluated when the link was followed, while such a URL in the src attribute of an iframe element would be evaluated in the context of the iframe's nested browsing context when the iframe is being set up. Once evaluated, its return value (if it was a string) would replace that browsing context's active document, thus also changing the corresponding Window object.

    If resource is to be fetched using `GET`, and there are relevant application caches that are identified by a URL with the same origin as the URL in question, and that have this URL as one of their entries, excluding entries marked as foreign, and whose mode is fast, and the user agent is not in a mode where it will avoid using application caches

    Fetch resource from the most appropriate application cache of those that match.

    For example, imagine an HTML page with an associated application cache displaying an image and a form, where the image is also used by several other application caches. If the user right-clicks on the image and chooses "View Image", then the user agent could decide to show the image from any of those caches, but it is likely that the most useful cache for the user would be the one that was used for the aforementioned HTML page. On the other hand, if the user submits the form, and the form does a POST submission, then the user agent will not use an application cache at all; the submission will be made to the network.

    This still needs to be integrated with the Fetch standard. [FETCH]

    If resource is a request whose url's scheme is a fetch scheme

    Run process a navigate fetch given resource, the source browsing context, browsingContext, navigationType, sandboxFlags, incumbentNavigationOrigin, activeDocumentNavigationOrigin, and historyHandling.

    Otherwise, resource is a request whose url's scheme is neither "javascript" nor a fetch scheme

    Run process a navigate URL scheme given resource's url and browsingContext.

To process a navigate fetch, given a request request, two browsing contexts sourceBrowsingContext and browsingContext, a string navigationType, a sandboxing flag set sandboxFlags, two origins incumbentNavigationOrigin and activeDocumentNavigationOrigin, and a history handling behavior historyHandling:

  1. Let response be null.

  2. Set request's client to sourceBrowsingContext's active document's relevant settings object, destination to "document", mode to "navigate", credentials mode to "include", use-URL-credentials flag, redirect mode to "manual", and replaces client id to browsingContext's active document's relevant settings object's id.

  3. If browsingContext's container is non-null:

    1. If the browsingContext's container has a browsing context scope origin, then set request's origin to that browsing context scope origin.

    2. Set request's destination to browsingContext's container's local name.

  4. Let reservedEnvironment be null.

  5. Let responseOrigin be null.

  6. Let coopEnforcementResult be a new cross-origin opener policy enforcement result whose needs a browsing context group switch is false, origin is browsingContext's active document's origin, and cross-origin opener policy is browsingContext's active document's cross-origin opener policy.

  7. Let finalSandboxFlags be an empty sandboxing flag set.

  8. Let responseCOOP be "unsafe-none".

  9. While true:

    1. Let currentURL be response's location URL, if response is not null, and request's current URL otherwise.

    2. If reservedEnvironment is not null and currentURL's origin is not the same as reservedEnvironment's creation URL's origin, then:

      1. Run the environment discarding steps for reservedEnvironment.

      2. Set reservedEnvironment to null.

    3. If reservedEnvironment is null, then:

      1. Let topLevelCreationURL be currentURL.

      2. Let topLevelOrigin be null.

      3. If browsingContext is not a top-level browsing context, then:

        1. Let parentEnvironment be browsingContext's container's relevant settings object.

        2. Set topLevelCreationURL to parentEnvironment's top-level creation URL and topLevelOrigin to parentEnvironment's top-level origin.

      4. Set reservedEnvironment to a new environment whose id is a unique opaque string, target browsing context is browsingContext, creation URL is currentURL, top-level creation URL is topLevelCreationURL, and top-level origin is topLevelOrigin.

        The created environment's active service worker is set in the Handle Fetch algorithm during the fetch if the request URL matches a service worker registration. [SW]

    4. Set request's reserved client to reservedEnvironment.

    5. If the result of Should navigation request of type be blocked by Content Security Policy? given request and navigationType is "Blocked", then set response to a network error and break. [CSP]

    6. Otherwise:

      1. If response is null, fetch request.

      2. Otherwise, perform HTTP-redirect fetch using request and response.

      3. Wait for the task on the networking task source to process response and set response to the result.

      4. Set finalSandboxFlags to the union of browsingContext's sandboxing flags and response's forced sandboxing flag set.

      5. Set responseOrigin to the result of determining the origin given browsingContext, request's url, finalSandboxFlags, incumbentNavigationOrigin, and activeDocumentNavigationOrigin.

      6. If browsingContext is a top-level browsing context, then:

        1. Set responseCOOP to the result of obtaining a cross-origin opener policy given response and reservedEnvironment.

        2. If sandboxFlags is not empty and responseCOOP is not "unsafe-none", then set response to an appropriate network error and break.

          This results in a network error as one cannot simultaneously provide a clean slate to a response using cross-origin opener policy and sandbox the result of navigating to that response.

        3. Set coopEnforcementResult to the result of enforcing the response's cross-origin opener policy given browsingContext, responseOrigin, responseCOOP, and coopEnforcementResult.

      7. If response is not a network error, browsingContext is a child browsing context, and the result of performing a cross-origin resource policy check with browsingContext's container document's origin, browsingContext's container document's relevant settings object, request's destination, response, and true is blocked, then set response to a network error and break.

        Here we're running the cross-origin resource policy check against the parent browsing context rather than sourceBrowsingContext. This is because we care about the same-originness of the embedded content against the parent context, not the navigation source.

      8. If response does not have a location URL or the location URL is not a URL whose scheme is an HTTP(S) scheme, then break.

        Navigation handles redirects manually as navigation is the only place in the web platform that cares for redirects to mailto: URLs and such.

  10. If response has a location URL that is failure, then set response to a network error.

  11. Otherwise, if response has a location URL that is a URL whose scheme is "blob", "file", "filesystem", or "javascript", then set response to a network error.

  12. Otherwise, if response has a location URL that is a URL whose scheme is a fetch scheme, then run process a navigate fetch with a new request whose url is response's location URL, sourceBrowsingContext, browsingContext, navigationType, sandboxFlags, incumbentNavigationOrigin, activeDocumentNavigationOrigin, and historyHandling, and return.

  13. Otherwise, if response has a location URL that is a URL, run the process a navigate URL scheme given response's location URL and browsingContext, and return.

  14. Fallback in prefer-online mode: If response was not fetched from an application cache, and was to be fetched using `GET`, and there are relevant application caches that are identified by a URL with the same origin as the URL in question, and that have this URL as one of their entries, excluding entries marked as foreign, and whose mode is prefer-online, and the user didn't cancel the navigation attempt during the earlier step, and response is either a network error or its status is not an ok status, then:

    Let candidate be the response identified by the URL in question from the most appropriate application cache of those that match.

    If candidate is not marked as foreign, then the user agent must discard the failed load and instead continue along these steps using candidate as response. The user agent may indicate to the user that the original page load failed, and that the page used was a previously cached response.

  15. Fallback for fallback entries: If response was not fetched from an application cache, and was to be fetched using `GET`, and its URL matches the fallback namespace of one or more relevant application caches, and the most appropriate application cache of those that match does not have an entry in its online safelist that has the same origin as response's URL and that is a prefix match for response's URL, and the user didn't cancel the navigation attempt during the earlier step, and response is either a network error or its status is not an ok status, then:

    Let candidate be the fallback response specified for the fallback namespace in question. If multiple application caches match, the user agent must use the fallback of the most appropriate application cache of those that match.

    If candidate is not marked as foreign, then the user agent must discard the failed load and instead continue along these steps using candidate as response. The document's URL, if appropriate, will still be the originally requested URL, not the fallback URL, but the user agent may indicate to the user that the original page load failed, that the page used was a fallback response, and what the URL of the fallback response actually is.

  16. Let navigationParams be a new navigation params whose request is request, response is response, origin is responseOrigin, final sandboxing flag set is finalSandboxFlags, cross-origin opener policy is responseCOOP, reserved environment is reservedEnvironment, browsing context is browsingContext, browsing context switch needed is coopEnforcementResult's needs a browsing context group switch, and history handling is historyHandling.

  17. Run process a navigate response with navigationType, the source browsing context, and navigationParams.

To process a navigate response, given a string navigationType, a browsing context source, and a navigation params navigationParams:

  1. Let response be navigationParams's response.

  2. Let browsingContext be navigationParams's browsing context.

  3. Let failure be false.

  4. If response is a network error, then set failure to true.

    Otherwise, if the result of Should navigation response to navigation request of type in target be blocked by Content Security Policy? given navigationParams's request, response, navigationType, and browsingContext is "Blocked", then set failure to true. [CSP]

    Otherwise, if the result of checking a navigation response's adherence to its embedder policy given response and browsingContext is false, then set failure to true.

    Otherwise, if the result of checking a navigation response's adherence to `X-Frame-Options` given response, browsingContext, and navigationParams's origin is false, then set failure to true.

  5. If failure is true, then:

    1. Display the inline content with an appropriate error shown to the user given browsingContext.

    2. Run the environment discarding steps for navigationParams's reserved environment.

    3. Return.

    This is where the network errors defined and propagated by Fetch, such as DNS or TLS errors, end up being displayed to users. [FETCH]

  6. If response's status is 204 or 205, then return.

  7. If response has a `Content-Disposition` header specifying the attachment disposition type, then:

    1. If the result of running the allowed to download given source and browsingContext is true, then handle response as a download.

    2. Return.

  8. Let type be the computed type of response.

  9. If the user agent has been configured to process resources of the given type using some mechanism other than rendering the content in a browsing context, then skip this step. Otherwise, if the type is one of the following types, jump to the appropriate entry in the following list, and process response as described there:

    an HTML MIME type
    Follow the steps given in the HTML document section providing navigationParams. Once the steps have completed, return.
    an XML MIME type that is not an explicitly supported XML MIME type
    Follow the steps given in the XML document section providing navigationParams and type. Once the steps have completed, return.
    a JavaScript MIME type
    a JSON MIME type that is not an explicitly supported JSON MIME type
    "text/cache-manifest"
    "text/css"
    "text/plain"
    "text/vtt"
    Follow the steps given in the plain text file section providing navigationParams and type. Once the steps have completed, return.
    "multipart/x-mixed-replace"
    Follow the steps given in the multipart/x-mixed-replace section providing navigationParams. Once the steps have completed, return.
    A supported image, video, or audio type
    Follow the steps given in the media section providing navigationParams and type. Once the steps have completed, return.
    A type that will use an external application to render the content in browsingContext
    Follow the steps given in the plugin section providing navigationParams and type. Once the steps have completed, return.

    An explicitly supported XML MIME type is an XML MIME type for which the user agent is configured to use an external application to render the content (either a plugin rendering directly in browsingContext, or a separate application), or one for which the user agent has dedicated processing rules (e.g., a web browser with a built-in Atom feed viewer would be said to explicitly support the application/atom+xml MIME type), or one for which the user agent has a dedicated handler.

    An explicitly supported JSON MIME type is a JSON MIME type for which the user agent is configured to use an external application to render the content (either a plugin rendering directly in browsingContext, or a separate application), or one for which the user agent has dedicated processing rules, or one for which the user agent has a dedicated handler.

  10. Otherwise, the document's type is such that the resource will not affect browsingContext, e.g., because the resource is to be handed to an external application or because it is an unknown type that will be processed as a download. Process the resource appropriately.

To process a navigate URL scheme, given a URL url and browsing context browsingContext, run these steps:

  1. If url is to be handled using a mechanism that does not affect browsingContext, e.g., because url's scheme is handled externally, then proceed with that mechanism instead.

  2. Otherwise, url is to be handled by displaying some sort of inline content, e.g., an error message because the specified scheme is not one of the supported protocols, or an inline prompt to allow the user to select a registered handler for the given scheme. Display the inline content given browsingContext.

    In the case of a registered handler being used, navigate will be invoked with a new URL.

When a resource is handled by passing its URL or data to an external software package separate from the user agent (e.g. handing a mailto: URL to a mail client, or a Word document to a word processor), user agents should attempt to mitigate the risk that this is an attempt to exploit the target software, e.g. by prompting the user to confirm that the source browsing context's active document's origin is to be allowed to invoke the specified software. In particular, if the navigate algorithm was invoked when source browsing context's active window does not have transient activation, the user agent should not invoke the external software package without prior user confirmation.

For example, there could be a vulnerability in the target software's URL handler which a hostile page would attempt to exploit by tricking a user into clicking a link.

To execute a javascript: URL request, given a request request and two browsing contexts source and browsingContext, run these steps:

  1. Let response be a response whose status is 204.

  2. If both of the following are true:

    then:

    1. Let urlString be the result of running the URL serializer on request's url.

    2. Let encodedScriptSource be the result of removing the leading "javascript:" from urlString.

    3. Let scriptSource be the UTF-8 decoding of the percent-decoding of encodedScriptSource.

    4. Append browsingContext's active document's URL to request's URL list.

    5. Let settings be browsingContext's active document's relevant settings object.

    6. Let baseURL be settings's API base URL.

    7. Let script be the result of creating a classic script given scriptSource, settings, baseURL, and the default classic script fetch options.

    8. Let evaluationStatus be the result of running the classic script script.

    9. Let result be undefined if evaluationStatus is an abrupt completion or evaluationStatus.[[Value]] is empty, or evaluationStatus.[[Value]] otherwise.

    10. If Type(result) is String, then set response to a response whose header list consists of `Content-Type`/`text/html` and `Referrer-Policy`/settings's referrer policy, and whose body is result.

      The exact conversion between the string result and the bytes that comprise a response body is not yet specified, pending further investigation into user agent behavior. See issue #1129.

  3. Return response.

In addition to the specific issues linked above, javascript: URLs have a dedicated label on the issue tracker documenting various problems with their specification.


Some of the sections below, to which the above algorithm defers in certain cases, use the following steps to create and initialize a Document object, given a type type, content type contentType, and navigation params navigationParams:

  1. Let browsingContext be navigationParams's browsing context.

  2. If navigationParams's browsing context switch needed is true, then set browsingContext to the result of the obtain a browsing context to use for a navigation response algorithm, given browsingContext, navigationParams's final sandboxing flag set, and navigationParams's cross-origin opener policy.

  3. Let permissionsPolicy be the result of creating a permissions policy from a response given browsingContext, navigationParams's origin, and navigationParams's response. [PERMISSIONSPOLICY]

    The creating a permissions policy from a response algorithm makes use of the passed origin. If document.domain has been used for browsingContext's container document, then its origin cannot be same origin-domain with the passed origin, because these steps run before the document is created, so it cannot itself yet have used document.domain. Note that this means that Permissions Policy checks are less permissive compared to doing a same origin check instead.

    See below for some examples of this in action.

  4. Let creationURL be navigationParams's response's URL.

  5. If navigationParams's request is non-null, then set creationURL to navigationParams's request's current URL.

  6. If browsingContext's only entry in its session history is the initial about:blank Document that was added when that browsing context was created, and navigationParams's history handling is "replace", and that Document's origin is same origin-domain with navigationParams's origin, then do nothing.

  7. Otherwise:

    1. Let oiHeader be the result of getting a structured field value given `Origin-Isolation` and "item" from response's header list.

    2. Let requestsOI be true if oiHeader is not null and oiHeader[0] is the boolean true; otherwise false.

    3. If reservedEnvironment is a non-secure context, then set requestsOI to false.

    4. Let agent be the result of obtaining a similar-origin window agent given navigationParams's origin, browsingContext's group, and requestsOI.

    5. Let realm execution context be the result of creating a new JavaScript realm given agent and the following customizations:

      • For the global object, create a new Window object.

      • For the global this binding, use browsingContext's WindowProxy object.

    6. Let topLevelCreationURL be creationURL.

    7. Let topLevelOrigin be navigationParams's origin.

    8. If browsingContext is not a top-level browsing context, then:

      1. Let parentEnvironment be browsingContext's container's relevant settings object.

      2. Set topLevelCreationURL to parentEnvironment's top-level creation URL.

      3. Set topLevelOrigin to parentEnvironment's top-level origin.

    9. Set up a window environment settings object with realm execution context, navigationParams's reserved environment, topLevelCreationURL, and topLevelOrigin.

  8. Let document be a new Document, whose type is type, content type is contentType, origin is navigationParams's origin, permissions policy is permissionsPolicy, active sandboxing flag set is navigationParams's final sandboxing flag set, and cross-origin opener policy is navigationParams's cross-origin opener policy.

  9. Set document's URL to creationURL.

  10. Set document's referrer policy to the result of parsing the `Referrer-Policy` header of navigationParams's response. [REFERRERPOLICY]

  11. Set document's embedder policy to the result of obtaining an embedder policy from navigationParams's response.

  12. Initialize a Document's CSP list given document, navigationParams's response, and navigationParams's request. [CSP]

  13. If navigationParams's request is non-null, then:

    1. Set document's referrer to the empty string.

    2. Let referrer be navigationParams's request's referrer.

    3. If referrer is a URL record, then set document's referrer to the serialization of referrer.

      Per Fetch, referrer will be either a URL record or "no-referrer" at this point.

  14. If navigationParams's response has a `Refresh` header, then:

    1. Let value be the isomorphic decoding of the value of the header.

    2. Run the shared declarative refresh steps with document and value.

    We do not currently have a spec for how to handle multiple `Refresh` headers. This is tracked as issue #2900.

  15. Return document.

In this example, the child document is not allowed to use PaymentRequest, despite being same origin-domain at the time the child document tries to use it. At the time the child document is initialized, only the parent document has set document.domain, and the child document has not.

<!-- https://foo.example.com/a.html -->
<!doctype html>
<script>
document.domain = 'example.com';
</script>
<iframe src=b.html></iframe>
<!-- https://bar.example.com/b.html -->
<!doctype html>
<script>
document.domain = 'example.com'; // This happens after the document is initialized
new PaymentRequest(…); // Not allowed to use
</script>

In this example, the child document is allowed to use PaymentRequest, despite not being same origin-domain at the time the child document tries to use it. At the time the child document is initialized, none of the documents have set document.domain yet so same origin-domain falls back to a normal same origin check.

<!-- https://example.com/a.html -->
<!doctype html>
<iframe src=b.html></iframe>
<!-- The child document is now initialized, before the script below is run. -->
<script>
document.domain = 'example.com';
</script>
<!-- https://example.com/b.html -->
<!doctype html>
<script>
new PaymentRequest(…); // Allowed to use
</script>

Some of the sections below, to which the above algorithm defers in certain cases, require the user agent to update the session history with the new page, given some navigation params navigationParams. When a user agent is required to do this, it must queue a global task on the networking task source, given the relevant global object of the Document object of the current entry (not the new one), to run the following steps:

  1. Let newDocument be navigationParams's browsing context's active document.

  2. Unload the document of the current entry.

    If this instance of the navigation algorithm is canceled while this step is running the unload a document algorithm, then the unload a document algorithm must be allowed to run to completion, but this instance of the navigation algorithm must not run beyond this step. (In particular, for instance, the cancelation of this algorithm does not abort any event dispatch or script execution occurring as part of unloading the document or its descendants.)

  3. If navigationParams's history handling is "reload" or "entry update"
    1. Replace the document of the current entry, and any other entries that reference the same document as that entry, with newDocument.

    2. Traverse the history to the current entry.

    If the navigation was initiated with a URL that equals newDocument's URL
    1. Replace the current entry with a new session history entry whose URL is newDocument's URL and document is newDocument.

    2. Traverse the history to the current entry.

    Otherwise
    1. Remove all the entries in the session history after the current entry. If the current entry is the last entry in the session history, then no entries are removed.

      This doesn't necessarily have to affect the user agent's user interface.

    2. Append a new session history entry to the session history, whose URL is newDocument's URL and document is newDocument.

    3. Traverse the history to the new entry, with historyHandling set to navigationParams's history handling.

  4. The navigation algorithm has now matured.

  5. Try to scroll to the fragment for newDocument.

To try to scroll to the fragment for a Document document, perform the following steps in parallel:

  1. Wait for an implementation-defined amount of time. (This is intended to allow the user agent to optimize the user experience in the face of performance concerns.)

  2. Queue a global task on the networking task source given document's relevant global object to run these steps:

    1. If document has no parser, or its parser has stopped parsing, or the user agent has reason to believe the user is no longer interested in scrolling to the fragment, then abort these steps.

    2. Scroll to the fragment given in document's URL. If this does not find an indicated part of the document, then try to scroll to the fragment for document.

7.10.2 HTML 文件的页面加载处理模型

给定 导航参数 加载 HTML 文档 时, 用户代理必须在 网络任务源 入队一个任务

  1. document 为给定 "html","text/html" 和 navigationParams 创建和初始化 Document 对象 的结果。

  2. 创建一个 HTML 解析器 并把它关联到 document。 获取过程中 网络任务源任务队列 里加入的所有 任务 都必须把获取到的字节填充到解析器的 输入字节流 里,让 HTML 解析器 对输入流执行适当的处理。

    tokenizer输入字节流 转化为能用的字符。 这个过程部分依赖于资源的 Content-Type 元数据 里的字符编码信息; 计算得到的类型不用作这一用途。

当没有字节可以处理时,用户代理必须在 网络任务源 里, 用新创建的 Document相关全局对象 入队一个全局任务,让解析器处理隐含的 EOF 字符,最终让 load 事件触发。

创建 Document 对象后,但在任何脚本执行前, 当然也在解析器 停止 之前,用户代理必须给定 navigationParams用新的页面更新会话历史

在 HTML 解析中,会发生 应用缓存选择

7.10.3 XML 文件的页面加载处理模型

给定 导航参数 navigationParams 和字符串 type, 要显示内联 XML 文件时,用户代理必须遵循 XMLNamespaces in XML, XML Media Types, DOM 和其他相关规范, 使用 "xml",typenavigationParams 创建和初始化 Document 对象。也必须创建一个对应的 XML 解析器[XML] [XMLNS] [RFC7303] [DOM]

编写这篇文档时,XML 规范社区其实还没有真正说明 XML 和 DOM 如何交互。

必须使用实际的 HTTP 头部和其他元数据(而不是本标准中算法修改后的),根据上述规范来确定字符编码。 一旦建立了字符编码,必须把 文档的字符编码 设置为这个编码。

如果根据上述 XML 解析的 文档元素 是一个 有着manifest 属性值为非空字符串的 html 元素, 那么当该元素 插入到文档时, 用户代理必须相对于那个元素的 节点文档 解析 那个属性的值,如果解析成功,必须在 结果 URL 记录 上应用 URL 序列化算法, 期间设置 排除 fragment 标志, 来获得 manifest URL,然后以 manifest URL 为清单 URL 执行 应用缓存选择算法,传入新创建的 Document。 否则如果该属性不存在,值为空字符串,或值解析失败,则在 文档元素 插入 到文档中时,用户代理必须不参考清单,并传入 Document 来执行 应用缓存选择算法

由于 manifest 属性的解析只发生 在解析 文档元素 时,任何在 文档元素 之前的处理指令中引用的 URL (例如<?xml-stylesheet?> PI)将会从网络获取,不会被缓存。

然后用代理必须用新创建的 DocumentnavigationParams更新会话历史为新页面。 用户代理必须在任何脚本执行之前更新会话历史,可能在文档完成解析之前(所以才能实现 增量渲染)。

解析过程中的错误消息(例如 XML 命名空间良构性错误)可以通过修改 Document 来内联地报告。

7.10.4 文本文件的页面加载处理模型

给定 导航参数 navigationParams 和字符串 type 加载纯文本文档时, 用户代理必须在 网络任务源入队一个任务

  1. document 为给定 "html",typenavigationParams 创建和初始化 Document 对象 的结果。

  2. 创建一个 HTML 解析器 并把它关联到 document。 假装 tokenizer 输出了标签名为"pre" 的开始标签,紧接着一个 U+000A LINE FEED (LF) 字符, 然后把 HTML 解析器 的 tokenizer 切换到 PLAINTEXT 状态。 获取过程中 网络任务源任务队列 里加入的所有 任务 都必须把获取到的字节填充到解析器的 输入字节流 里,让 HTML 解析器 对输入流执行适当的处理。

如何将纯文本文档的字节转换为真正字符的规则, 以及真正渲染文字给用户的规则,定义在该资源 计算得到的 MIME 类型 (即 type)的规范中。

文档的字符编码 必须设置为解码文档时用的字符编码。

在创建 Document 对象时,用户代理必须不参考清单,并传入新创建的 Document 来执行 应用缓存选择算法

当没有字节可以处理时,用户代理必须在 网络任务源 里, 用新创建的 Document相关全局对象 入队一个全局任务,让解析器处理隐含的 EOF 字符,最终让 load 事件触发。

在创建 Document 对象后,页面完全结束加载之前, 用户代理必须给定 navigationParams用新的页面更新会话历史

用户代理可能会添加内容到 Documenthead 元素, 例如链接一个样式表,提供一个脚本,或者给文档一个 title

特别是如果用户代理支持 RFC 3676 的 Format=Flowed 特性,就需要应用额外的样式来使文字正确折行,以及处理引用特性。 这可以通过使用 CSS 扩展来完成。

7.10.5 multipart/x-mixed-replace 资源的媒体的页面加载处理模型

浏览上下文 加载一个 multipart/x-mixed-replace 类型的资源时, 用户代理必须使用 multipart 类型的规则解析资源。 [RFC2046]

该算法传入了 导航参数,但还不清楚如何使用。

对资源中的每个 body part,用户代理必须执行 处理导航响应算法, 执行时要使用新的 body 部分和同样的 浏览上下文, 如果同一资源中的上一个 body 部分产生了 创建和初始化 Document 对象, 就把 历史处理 设为 "replace", 否则使用跟最初调用这部分的 导航 时同样的配置。

为使得算法处理这些 body part 的表现与处理独立的资源一致, 在碰到边界时用户代理必须表现地就像没有更多字节一样。

因此, load 事件(以及 unload 事件)会为每个载入的 body part 触发。

7.10.6 媒体的页面加载处理模型

给定 导航参数 navigationParams 和字符串 type, 加载图片、视频或音频资源时用户代理应该:

  1. document 为给定 "html",typenavigationParams 创建和初始化 Document 对象 的结果。

  2. 加一个 html 元素到 document

  3. 加一个 head 元素到 html 元素。

  4. 加一个 body 元素到 html 元素。

  5. 为媒体加一个 host element(见下文)到 body 元素。

  6. host element 元素的适当属性(见下文)设为图片、视频或音频资源的地址。

要为媒体创建的 host element 元素由下表中每行的第二个单元格给出, 同行的第一个单元格是媒体的描述。 要设置的属性是同行的第三个单元格。

媒体类型 媒体元素 适当的属性
Image img src
Video video src
Audio audio src

然后,用户代理必须表现地像已经 停止解析 一样。

在创建 Document 对象时,用户代理必须不参考清单,并传入新创建的 Document 来执行 应用缓存选择算法

在创建 Document 对象后,页面完全结束加载之前, 用户代理必须用 navigationParams 更新会话历史到新页面

用户代理可能会添加内容到 Documenthead 元素, 或者添加属性到 host element 元素,例如链接一个样式表, 提供一个脚本,给文档一个 title,或者让媒体 自动播放

7.10.7 使用插件的内容的页面加载处理模型

给定 导航参数 navigationParams 和字符串 type, 加载一个需要渲染外部资源的资源时用户代理应该:

  1. document 为给定 "html",typenavigationParams 创建和初始化 Document 对象 的结果。

  2. document 标记为 插件文档

  3. 加一个 html 元素到 document

  4. 加一个 head 元素到 html 元素。

  5. 加一个 body 元素到 html 元素。

  6. 加一个 embed 元素到 body 元素。

  7. 设置 embed 元素的 src 属性为资源地址。

插件文档 这个术语用于 Content Security Policy 作为确保 iframe 不能被用于逃脱 plugin-types 指令机制的一部分。 [CSP]

然后,用户代理必须表现地像已经 停止解析 一样。

在创建 Document 对象时,用户代理必须不参考清单,并传入新创建的 Document 来执行 应用缓存选择算法

在创建 Document 对象后,页面完全结束加载之前, 用户代理必须给定 navigationParams用新的页面更新会话历史

用户代理可能会添加内容到 Documenthead 元素, 或者添加属性到 embed 元素,例如链接一个样式表或者给文档一个 title

如果 Document激活沙盒标识沙盒插件浏览上下文标识 处于已设置状态, 如果相关 插件 不够 安全 的话, 合成的 embed 元素将会 渲染内容失败

7.10.8 没有 DOM 的内联内容的页面加载处理模型

给定 浏览上下文 browsingContext, 用户代理显示内联的用户代理页面时应该:

  1. navigationParams 为新的 导航参数,其 request 为 null,response 为 null,origin 为新的 不透明源final sandboxing flag set 为空集合,跨域 opener 策略 为 "unsafe-none",保留环境 为 null,浏览上下文browsingContext需要切换浏览上下文 为 false。

    下一步调用的算法无法处理空的 响应。可能我们需要构造一个。

  2. document 为给定 "html","text/html" 和 navigationParams 创建和初始化 Document 对象 的结果。

  3. 或者把 document 关联到不使用正常 Document 渲染规则的自定义的渲染, 或者把 document 改成用户代理想要渲染的内容。

一旦页面已经建立,用户代理必须表现地像已经 停止解析 一样。

在创建 Document 对象时,用户代理必须不参考清单,并传入新创建的 Document 来执行 应用缓存选择算法

在创建 Document 对象后,页面结束完全建立之前, 用户代理必须给定 navigationParams用新的页面更新会话历史

7.10.9 Navigating to a fragment

To navigate to a fragment given a browsing context browsingContext, a URL url, and a history handling behavior historyHandling:

  1. If historyHandling is not "replace", then remove all the entries in browsingContext's session history after the current entry. (If the current entry is the last entry in the session history, then no entries are removed.)

    This doesn't necessarily have to affect the user agent's user interface.

  2. Remove any tasks queued by the history traversal task source that are associated with any Document objects in browsingContext's top-level browsing context's document family.

  3. Append a new session history entry to the session history whose URL is url, document is the current entry's document, and scroll restoration mode is the current entry's scroll restoration mode.

  4. Traverse the history to the new entry, with historyHandling set to historyHandling and with nonBlockingEvents set to true. This will scroll to the fragment given in what is now the document's URL.

If the scrolling fails because the relevant ID has not yet been parsed, then the original navigation algorithm will take care of the scrolling instead, as the last few steps of its update the session history with the new page algorithm.


When the user agent is required to scroll to the fragment and the indicated part of the document, if any, is being rendered, the user agent must either change the scrolling position of the document using the following algorithm, or perform some other action such that the indicated part of the document is brought to the user's attention. If there is no indicated part, or if the indicated part is not being rendered, then the user agent must do nothing. The aforementioned algorithm is as follows:

  1. If there is no indicated part of the document, set the Document's target element to null.

  2. If the indicated part of the document is the top of the document, then:

    1. Set the Document's target element to null.

    2. Scroll to the beginning of the document for the Document. [CSSOMVIEW]

  3. Otherwise:

    1. Let target be element that is the indicated part of the document.

    2. Set the Document's target element to target.

    3. Scroll target into view, with behavior set to "auto", block set to "start", and inline set to "nearest". [CSSOMVIEW]

    4. Run the focusing steps for target, with the Document's viewport as the fallback target.

    5. Move the sequential focus navigation starting point to target.

The indicated part of the document is the one that the fragment, if any, identifies. The semantics of the fragment in terms of mapping it to a node is defined by the specification that defines the MIME type used by the Document (for example, the processing of fragments for XML MIME types is the responsibility of RFC7303). [RFC7303]

There is also a target element for each Document, which is used in defining the :target pseudo-class and is updated by the above algorithm. It is initially null.

For HTML documents (and HTML MIME types), the following processing model must be followed to determine what the indicated part of the document is.

  1. Let fragment be the document's URL's fragment.

  2. If fragment is the empty string, then the indicated part of the document is the top of the document; return.

  3. If find a potential indicated element with fragment returns non-null, then the return value is the indicated part of the document; return.

  4. Let fragmentBytes be the result of percent-decoding fragment.

  5. Let decodedFragment be the result of running UTF-8 decode without BOM on fragmentBytes.

  6. If find a potential indicated element with decodedFragment returns non-null, then the return value is the indicated part of the document; return.

  7. If decodedFragment is an ASCII case-insensitive match for the string top, then the indicated part of the document is the top of the document; return.

  8. There is no indicated part of the document.

To find a potential indicated element given a string fragment, run these steps:

  1. If there is an element in the document tree that has an ID equal to fragment, then return the first such element in tree order.

  2. If there is an a element in the document tree that has a name attribute whose value is equal to fragment, then return the first such element in tree order.

  3. Return null.

7.10.10 History traversal

To traverse the history to a session history entry entry, with an optional history handling behavior historyHandling (default "default"), an optional boolean nonBlockingEvents (default false), and an optional boolean explicitHistoryNavigation (default false):

This algorithm is not just invoked when explicitly going back or forwards in the session history — it is also invoked in other situations, for example when navigating a browsing context, as part of updating the session history with the new page.

  1. If entry's document is null, then:

    1. Let request be a new request whose url is entry's URL.

    2. If explicitHistoryNavigation is true, then set request's history-navigation flag.

    3. Assert: historyHandling is not "replace".

    4. Navigate the browsing context to request with historyHandling set to "entry update". The navigation must be done using the same source browsing context as was used the first time entry was created.

      The "navigate" algorithm reinvokes this "traverse" algorithm to complete the traversal, at which point entry's document is non-null.

      If the resource was obtained using a non-idempotent action, for example a POST form submission, or if the resource is no longer available, for example because the computer is now offline and the page wasn't cached, navigating to it again might not be possible. In this case, the navigation will result in a different page than previously; for example, it might be an error message explaining the problem or offering to resubmit the form.

    5. Return.

  2. If the current entry's title is null, then set its title to the value returned by the document.title IDL attribute.

  3. Save persisted state to the current entry.

  4. Let newDocument be entry's document.

  5. If newDocument is different than the current entry's document, then:

    1. Remove any tasks queued by the history traversal task source that are associated with any Document objects in the top-level browsing context's document family.

    2. If newDocument's origin is not same origin with the current entry's document's origin, then:

      1. Let entriesToUpdate be all entries in the session history whose document's origin is same origin as the active document and that are contiguous with the current entry.

      2. For each entryToUpdate of entriesToUpdate, set entryToUpdate's browsing context name to the current browsing context name.

      3. If the browsing context is a top-level browsing context, but not an auxiliary browsing context, then set the browsing context's name to the empty string.

    3. Set the active document of the browsing context to newDocument.

    4. If entry's browsing context name is not null, then:

      1. Set the browsing context's name to entry's browsing context name.

      2. Let entriesToUpdate be all entries in the session history whose document's origin is same origin as the new active document and that are contiguous with entry.

      3. For each entryToUpdate of entriesToUpdate, set entryToUpdate's browsing context name to null.

    5. If newDocument has any form controls whose autofill field name is "off", invoke the reset algorithm of each of those elements.

    6. If newDocument's current document readiness "complete", then queue a global task on the DOM manipulation task source given newDocument's relevant global object to run the following steps:

      1. If newDocument's page showing flag is true, then abort these steps.

      2. Set newDocument's page showing flag to true.

      3. Run any session history document visibility change steps for newDocument that are defined by other applicable specifications.

        This is specifically intended for use by Page Visibility. [PAGEVIS]

      4. Fire an event named pageshow at newDocument's relevant global object, using PageTransitionEvent, with the persisted attribute initialized to true, and legacy target override flag set.

  6. Set newDocument's URL to entry's URL.

  7. Let hashChanged be false, and let oldURL and newURL be null.

  8. If entry's URL's fragment is not identical to the current entry's URL's fragment, and entry's document equals the current entry's document, then set hashChanged to true, set oldURL to the current entry's URL, and set newURL to entry's URL.

  9. If historyHandling is "replace", then remove the entry immediately before entry in the session history.

  10. If entry's persisted user state is null, and its URL's fragment is non-null, then scroll to the fragment.

  11. Set the current entry to entry.

  12. Let targetRealm be the current Realm Record.

  13. Let state be null.

  14. If entry's serialized state is not null, then set state to StructuredDeserialize(entry's serialized state, targetRealm). If this throws an exception, catch it and ignore the exception.

  15. Set newDocument's History object's state to state.

  16. Let stateChanged be true if newDocument has a latest entry, and that entry is not entry; otherwise let it be false.

  17. Set newDocument's latest entry to entry.

  18. If nonBlockingEvents is false, then run the following steps immediately. Otherwise, queue a global task on the DOM manipulation task source given newDocument's relevant global object to run the following steps instead.

    1. If stateChanged is true, then fire an event named popstate at newDocument's relevant global object, using PopStateEvent, with the state attribute initialized to state.

    2. Restore persisted state from entry.

    3. If hashChanged is true, then fire an event named hashchange at the browsing context's active window, using HashChangeEvent, with the oldURL attribute initialized to oldURL and the newURL attribute initialized to newURL.

7.10.10.1 Persisted history entry state

To save persisted state to a session history entry entry:

  1. Set the scroll position data of entry to contain the scroll positions for all of entry's document's restorable scrollable regions.

  2. Optionally, update entry's persisted user state to reflect any state that the user agent wishes to persist, such as the values of form fields.

To restore persisted state from a session history entry entry:

  1. If entry's scroll restoration mode is "auto", then the user agent may use entry's scroll position data to restore the scroll positions of entry's document's restorable scrollable regions.

    The user agent not restoring scroll positions does not imply that scroll positions will be left at any particular value (e.g., (0,0)). The actual scroll position depends on the navigation type and the user agent's particular caching strategy. So web applications cannot assume any particular scroll position but rather are urged to set it to what they want it to be.

  2. Optionally, update other aspects of entry's document and its rendering, for instance values of form fields, that the user agent had previously recorded in entry's persisted user state.

    This can even include updating the dir attribute of textarea elements or input elements whose type attribute is in either the Text state or the Search state, if the persisted state includes the directionality of user input in such controls.


The restorable scrollable regions of a Document document are document's viewport, and all of document's scrollable regions excepting any child browsing contexts of document.

Child browsing context scroll restoration is handled by the history entry for those browsing contexts' Documents.

7.10.10.2 The PopStateEvent interface

PopStateEvent

Support in all current engines.

Firefox4+SafariYesChrome4+
OperaYesEdge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android4+Safari iOSYesChrome Android18+WebView Android37+Samsung Internet1.0+Opera AndroidYes
[Exposed=Window]
interface PopStateEvent : Event {
  constructor(DOMString type, optional PopStateEventInit eventInitDict = {});

  readonly attribute any state;
};

dictionary PopStateEventInit : EventInit {
  any state = null;
};
event . state

Returns a copy of the information that was provided to pushState() or replaceState().

The state attribute must return the value it was initialized to. It represents the context information for the event, or null, if the state represented is the initial state of the Document.

7.10.10.3 The HashChangeEvent interface

HashChangeEvent

Support in all current engines.

Firefox3.6+Safari5+Chrome5+
Opera10.6+Edge79+
Edge (Legacy)12+Internet Explorer8+
Firefox Android4+Safari iOS5+Chrome AndroidYesWebView Android37+Samsung InternetYesOpera Android11+
[Exposed=Window]
interface HashChangeEvent : Event {
  constructor(DOMString type, optional HashChangeEventInit eventInitDict = {});

  readonly attribute USVString oldURL;
  readonly attribute USVString newURL;
};

dictionary HashChangeEventInit : EventInit {
  USVString oldURL = "";
  USVString newURL = "";
};
event . oldURL

HashChangeEvent/oldURL

Support in all current engines.

Firefox6+SafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+Internet ExplorerNo
Firefox AndroidYesSafari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes

Returns the URL of the session history entry that was previously current.

event . newURL

HashChangeEvent/newURL

Support in all current engines.

Firefox6+SafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+Internet ExplorerNo
Firefox AndroidYesSafari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes

Returns the URL of the session history entry that is now current.

The oldURL attribute must return the value it was initialized to. It represents context information for the event, specifically the URL of the session history entry that was traversed from.

The newURL attribute must return the value it was initialized to. It represents context information for the event, specifically the URL of the session history entry that was traversed to.

7.10.10.4 The PageTransitionEvent interface

PageTransitionEvent

Support in all current engines.

FirefoxYesSafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+Internet Explorer11
Firefox AndroidYesSafari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes
[Exposed=Window]
interface PageTransitionEvent : Event {
  constructor(DOMString type, optional PageTransitionEventInit eventInitDict = {});

  readonly attribute boolean persisted;
};

dictionary PageTransitionEventInit : EventInit {
  boolean persisted = false;
};
event . persisted

PageTransitionEvent/persisted

Support in all current engines.

FirefoxYesSafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+Internet Explorer11
Firefox AndroidYesSafari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes

For the pageshow event, returns false if the page is newly being loaded (and the load event will fire). Otherwise, returns true.

For the pagehide event, returns false if the page is going away for the last time. Otherwise, returns true, meaning that (if nothing conspires to make the page unsalvageable) the page might be reused if the user navigates back to this page.

Things that can cause the page to be unsalvageable include:

The persisted attribute must return the value it was initialized to. It represents the context information for the event.

7.10.11 Loading documents

A Document has a completely loaded time (a time or null), which is initially null.

A Document is considered completely loaded if its completely loaded time is non-null.

To completely finish loading a Document document:

  1. Assert: document's browsing context is non-null.

  2. Set document's completely loaded time to the current time.

  3. Let container be document's browsing context's container.

  4. If container is an iframe element, then queue an element task on the DOM manipulation task source given container to run the iframe load event steps given container.

  5. Otherwise, if container is non-null, then queue an element task on the DOM manipulation task source given container to fire an event named load at container.

7.10.12 Unloading documents

A Document has a salvageable state, which must initially be true, and a page showing flag, which must initially be false. The page showing flag is used to ensure that scripts receive pageshow and pagehide events in a consistent manner (e.g. that they never receive two pagehide events in a row without an intervening pageshow, or vice versa).

Event loops have a termination nesting level counter, which must initially be 0.

To prompt to unload, given a Document object document and optionally a recursiveFlag, run these steps:

  1. Increase the event loop's termination nesting level by 1.

  2. Increase the document's ignore-opens-during-unload counter by 1.

  3. Let event be the result of creating an event using BeforeUnloadEvent.

  4. Initialize event's type attribute to beforeunload and its cancelable attribute true.

  5. Dispatch: Dispatch event at document's relevant global object.

  6. Decrease the event loop's termination nesting level by 1.

  7. If document's active sandboxing flag set does not have its sandboxed modals flag set, and the returnValue attribute of the event object is not the empty string, or if the event was canceled, then the user agent may ask the user to confirm that they wish to unload the document.

    The message shown to the user is not customizable, but instead determined by the user agent. In particular, the actual value of the returnValue attribute is ignored.

    The user agent is encouraged to avoid asking the user for confirmation if it judges that doing so would be annoying, deceptive, or pointless. A simple heuristic might be that if the user has not interacted with the document, the user agent would not ask for confirmation before unloading it.

    If the user agent asks the user for confirmation, it must pause while waiting for the user's response.

    If the user did not confirm the page navigation, then the user agent refused to allow the document to be unloaded.

  8. If the recursiveFlag is not set, then:

    1. Let descendants be the list of the descendant browsing contexts of document.

    2. For each browsingContext in descendants:

      1. Prompt to unload browsingContext's active document with the recursiveFlag set.

      2. If the user refused to allow the document to be unloaded, then the user implicitly also refused to allow document to be unloaded; break.

  9. Decrease the document's ignore-opens-during-unload counter by 1.

To unload a Document document, optionally given a recursiveFlag:

  1. Increase the event loop's termination nesting level by one.

  2. Increase document's ignore-opens-during-unload counter by one.

  3. If document's page showing flag is false, then jump to the step labeled unload event below (i.e. skip firing the pagehide event and don't rerun the unloading document visibility change steps).

  4. Set document's page showing flag to false.

  5. If the user agent does not intend to keep document alive in a session history entry (such that it can be reused later on history traversal), set document's salvageable state to false.

  6. Fire an event named pagehide at document's relevant global object, using PageTransitionEvent, with the persisted attribute initialized to true if document's salvageable state is true, and false otherwise, and legacy target override flag set.

  7. Run any unloading document visibility change steps for document that are defined by other applicable specifications.

    This is specifically intended for use by Page Visibility. [PAGEVIS]

  8. Unload event: If document's salvageable state is false, then fire an event named unload at document's relevant global object, with legacy target override flag set.

  9. Decrease the event loop's termination nesting level by one.

  10. Run any unloading document cleanup steps for document that are defined by this specification and other applicable specifications.

  11. If the recursiveFlag is not set, then:

    1. Let descendants be the list of the descendant browsing contexts of document.

    2. For each browsingContext in descendants:

      1. Unload the active document of browsingContext with the recursiveFlag set.

      2. If the salvageable state of the active document of browsingContext is false, then set the salvageable state of document to false also.

    3. If document's salvageable state is false, then discarddocument.

  12. Decrease document's ignore-opens-during-unload counter by one.

This specification defines the following unloading document cleanup steps. Other specifications can define more. Given a Document document:

  1. Let window be document's relevant global object.

  2. For each WebSocket object webSocket whose relevant global object is window, make disappear webSocket.

    If this affected any WebSocket objects, then set document's salvageable state to false.

  3. If document's salvageable state is false, then:

    1. For each EventSource object eventSource whose relevant global object is equal to window, forcibly close eventSource.

    2. Empty window's list of active timers.

7.10.12.1 The BeforeUnloadEvent interface

BeforeUnloadEvent

Support in all current engines.

Firefox1.5+SafariYesChrome30+
Opera17+Edge79+
Edge (Legacy)12+Internet ExplorerYes
Firefox Android4+Safari iOSYesChrome Android30+WebView Android37+Samsung Internet3.0+Opera Android18+
[Exposed=Window]
interface BeforeUnloadEvent : Event {
  attribute DOMString returnValue;
};

There are no BeforeUnloadEvent-specific initialization methods.

The BeforeUnloadEvent interface is a legacy interface which allows prompting to unload to be controlled not only by canceling the event, but by setting the returnValue attribute to a value besides the empty string. Authors should use the preventDefault() method, or other means of canceling events, instead of using returnValue.

The returnValue attribute controls the process of prompting to unload. When the event is created, the attribute must be set to the empty string. On getting, it must return the last value it was set to. On setting, the attribute must be set to the new value.

This attribute is a DOMString only for historical reasons. Any value besides the empty string will be treated as a request to ask the user for confirmation.

7.10.13 Aborting a document load

To abort a Document document:

  1. Abort the active documents of every child browsing context. If this results in any of those Document objects having their salvageable state set to false, then set document's salvageable state to false also.

  2. Cancel any instances of the fetch algorithm in the context of document, discarding any tasks queued for them, and discarding any further data received from the network for them. If this resulted in any instances of the fetch algorithm being canceled or any queued tasks or any network data getting discarded, then set document's salvageable state to false.

  3. If document has an active parser, then:

    1. Set document's active parser was aborted to true.

    2. Abort that parser.

    3. Set document's salvageable state to false.

User agents may allow users to explicitly invoke the abort a document algorithm for a Document. If the user does so, then, if that Document is an active document, the user agent should queue a task to fire an event named abort at that Document object's relevant global object before invoking the abort algorithm.

To stop document loading given a Document object document, run these steps:

  1. If document is not an active document, then return.

  2. Let browsingContext be document's browsing context.

  3. If there is an existing attempt to navigate browsingContext and that attempt is not currently running the unload a document algorithm, then cancel that navigation.

  4. Abort document.

7.10.14 The `X-Frame-Options` header

The `X-Frame-Options` HTTP response header is a legacy way of controlling whether and how a Document may be loaded inside of a child browsing context. It is obsoleted by the frame-ancestors CSP directive, which provides more granular control over the same situations. It was originally defined in HTTP Header Field X-Frame-Options, but the definition and processing model here supersedes that document. [CSP] [RFC7034]

In particular, HTTP Header Field X-Frame-Options specified an `ALLOW-FROM` variant of the header, but that is not to be implemented.

Per the below processing model, if both a CSP frame-ancestors directive and an `X-Frame-Options` header are used in the same response, then `X-Frame-Options` is ignored.

For web developers and conformance checkers, its value ABNF is:

X-Frame-Options = "DENY" / "SAMEORIGIN"

To check a navigation response's adherence to `X-Frame-Options`, given a response response, a browsing context browsingContext, and an origin destinationOrigin:

  1. If browsingContext is not a child browsing context, then return true.

  2. For each policy of response's CSP list:

    1. If policy's disposition is not "enforce", then continue.

    2. If policy's directive set contains a frame-ancestors directive, then return true.

  3. Let rawXFrameOptions be the result of getting, decoding, and splitting `X-Frame-Options` from response's header list.

  4. Let xFrameOptions be a new set.

  5. For each value of rawXFrameOptions, append value, converted to ASCII lowercase, to xFrameOptions.

  6. If xFrameOptions's size is greater than 1, and xFrameOptions contains any of "deny", "allowall", or "sameorigin", then return false.

    The intention here is to block any attempts at applying `X-Frame-Options` which were trying to do something valid, but appear confused.

    This is the only impact of the legacy `ALLOWALL` value on the processing model.

  7. If xFrameOptions's size is greater than 1, then return true.

    This means it contains multiple invalid values, which we treat the same way as if the header was omitted entirely.

  8. If xFrameOptions[0] is "deny", then return false.

  9. If xFrameOptions[0] is "sameorigin", then:

    1. Let containerDocument be browsingContext's container document.

    2. While containerDocument is not null:

      1. If containerDocument's origin is not same origin with destinationOrigin, then return false.

      2. Let containerBC be containerDocument's browsing context.

      3. Set containerDocument to containerBC's container document, if containerBC is non-null; otherwise, null.

  10. Return true.

    If we've reached this point then we have a lone invalid value (which could potentially be one the legacy `ALLOWALL` or `ALLOW-FROM` forms). These are treated as if the header were omitted entirely.


The following table illustrates the processing of various values for the header, including non-conformant ones:

`X-Frame-Options`ValidResult
`DENY`embedding disallowed
`SAMEORIGIN`same-origin embedding allowed
`INVALID`embedding allowed
`ALLOWALL`embedding allowed
`ALLOW-FROM=https://example.com/`embedding allowed (from anywhere)

The following table illustrates how various non-conformant cases involving multiple values are processed:

`X-Frame-Options`Result
`SAMEORIGIN, SAMEORIGIN`same-origin embedding allowed
`SAMEORIGIN, DENY`embedding disallowed
`SAMEORIGIN,`embedding disallowed
`SAMEORIGIN, ALLOWALL`embedding disallowed
`SAMEORIGIN, INVALID`embedding disallowed
`ALLOWALL, INVALID`embedding disallowed
`ALLOWALL,`embedding disallowed
`INVALID, INVALID`embedding allowed

The same results are obtained whether the values are delivered in a single header whose value is comma-delimited, or in multiple headers.