<iframe>: The Inline Frame element

每个嵌入式浏览上下文都有自己的 document 并允许 URL 导航。每个嵌入式浏览上下文的导航都线性化为最顶层浏览上下文的 会话历史记录。嵌入其他浏览上下文的浏览上下文称为父浏览上下文。最顶层的浏览上下文（没有父级的浏览上下文）通常是浏览器窗口，由 Window 对象表示。

¥Each embedded browsing context has its own document and allows URL navigations. The navigations of each embedded browsing context are linearized into the session history of the topmost browsing context. The browsing context that embeds the others is called the parent browsing context. The topmost browsing context — the one with no parent — is usually the browser window, represented by the Window object.

警告：由于每个浏览上下文都是一个完整的文档环境，因此页面中的每个 <iframe> 都需要增加内存和其他计算资源。虽然理论上你可以使用任意数量的 <iframe>，但请检查性能问题。

¥Warning: Because each browsing context is a complete document environment, every <iframe> in a page requires increased memory and other computing resources. While theoretically you can use as many <iframe>s as you like, check for performance problems.

¥Attributes

该元素包括 全局属性。

¥This element includes the global attributes.

allow

指定 权限策略 为 <iframe>。该策略根据请求的来源定义 <iframe> 可以使用哪些功能（例如，访问麦克风、摄像头、电池、网络共享等）。

有关示例，请参阅 Permissions-Policy 主题中的 iframes。

注意：allow 属性指定的权限策略在 Permissions-Policy 标头中指定的策略之上实现了进一步的限制。它不会取代它。

¥Note: A Permissions Policy specified by the allow attribute implements a further restriction on top of the policy specified in the Permissions-Policy header. It doesn't replace it.

allowfullscreen

如果 <iframe> 可以通过调用 requestFullscreen() 方法激活全屏模式，则设置为 true。

注意：该属性被视为旧属性并重新定义为 allow="fullscreen"。

¥Note: This attribute is considered a legacy attribute and redefined as allow="fullscreen".

allowpaymentrequest Deprecated Non-standard

如果应允许跨源 <iframe> 调用 付款请求 API，则设置为 true。

注意：该属性被视为旧属性并重新定义为 allow="payment"。

¥Note: This attribute is considered a legacy attribute and redefined as allow="payment".

browsingtopics Experimental Non-standard

一个布尔属性，如果存在，则指定当前用户选定的主题应与 <iframe> 源的请求一起发送。详细信息请参见 使用主题 API。

credentialless Experimental

设置为 true 可使 <iframe> 无凭据，这意味着其内容将加载到新的临时上下文中。它无权访问与其来源相关的网络、cookie 和存储数据。它使用顶层文档生命周期本地的新上下文。作为返回，可以取消 Cross-Origin-Embedder-Policy (COEP) 嵌入规则，因此设置了 COEP 的文档可以嵌入没有设置 COEP 的第三方文档。详细信息请参见 IFrame 无凭据。

csp Experimental

为嵌入资源强制执行 内容安全政策。详情请参见 HTMLIFrameElement.csp。

height

框架的高度（以 CSS 像素为单位）。默认为 150。

loading

指示浏览器何时加载 iframe：

eager

页面加载时立即加载 iframe（这是默认值）。

lazy

推迟 iframe 的加载，直到达到浏览器定义的距 visual viewport 的计算距离。目的是避免使用获取帧所需的网络和存储带宽，直到浏览器相当确定需要它。这提高了大多数典型用例中的性能和成本，特别是通过减少初始页面加载时间。

注意：仅当启用 JavaScript 时才会延迟加载。这是一项反跟踪措施。

¥Note: Loading is only deferred when JavaScript is enabled. This is an anti-tracking measure.

name

嵌入式浏览上下文的可定位名称。这可以用在 <a>、<form> 或 <base> 元素的 target 属性中；<input> 或 <button> 元素的 formtarget 属性；或 window.open() 方法中的 windowName 参数。

referrerpolicy

指示获取帧资源时要发送哪个 referrer：

no-referrer

Referer 标头将不会被发送。

no-referrer-when-downgrade

如果没有 TLS (HTTPS)，Referer 标头将不会发送到 origin。

origin

发送的引荐来源网址将仅限于引荐页面的来源：它是 scheme、host 和 port。

origin-when-cross-origin

发送到其他来源的引用将受到方案、主机和端口的限制。同一原点的导航仍将包含该路径。

same-origin

将发送 same origin 的引荐来源网址，但跨源请求将不包含引荐来源网址信息。

strict-origin

仅当协议安全级别保持不变 (HTTPS→HTTPS) 时才将文档的来源作为引用站点发送，但不要将其发送到安全性较低的目的地 (HTTPS→HTTP)。

strict-origin-when-cross-origin（默认）

执行同源请求时发送完整 URL，仅在协议安全级别保持相同时发送源（HTTPS→HTTPS），并且不向安全性较低的目的地发送标头（HTTPS→HTTP）。

unsafe-url

引荐来源网址将包括来源和路径（但不包括 fragment、password 或 username）。此值不安全，因为它会将受 TLS 保护的资源的来源和路径泄漏到不安全的来源。

sandbox

控制应用于 <iframe> 中嵌入内容的限制。该属性的值可以为空以应用所有限制，也可以为空格分隔的标记以解除特定限制：

allow-downloads

允许通过具有 download 属性的 <a> 或 <area> 元素以及通过导致文件下载的导航来下载文件。无论用户是否单击了链接，还是 JS 代码在没有用户交互的情况下启动了它，这都有效。

allow-downloads-without-user-activation Experimental

无需用户手势即可进行下载。

allow-forms

允许页面提交表单。如果不使用该关键字，表单将正常显示，但提交表单不会触发输入验证、向 Web 服务器发送数据或关闭对话框。

allow-modals

允许页面通过 Window.alert()、Window.confirm()、Window.print() 和 Window.prompt() 打开模态窗口，而无论该关键字如何，都允许打开 <dialog>。它还允许页面接收 BeforeUnloadEvent 事件。

allow-orientation-lock

让资源 锁定屏幕方向。

allow-pointer-lock

允许页面使用 指针锁 API。

allow-popups

允许弹出窗口（例如 Window.open()、target="_blank"、Window.showModalDialog()）。如果不使用此关键字，该功能将默默地失败。

allow-popups-to-escape-sandbox

允许沙盒文档打开新的浏览上下文，而无需在其上强制使用沙盒标志。例如，这将允许安全地对第三方广告进行沙箱处理，而不会对广告链接到的页面施加相同的限制。如果不包含此标志，则重定向页面、弹出窗口或新选项卡将受到与原始 <iframe> 相同的沙箱限制。

allow-presentation

允许嵌入者控制 iframe 是否可以启动 演讲会。

allow-same-origin

如果不使用此令牌，则该资源将被视为来自始终无法通过 same-origin policy 的特殊来源（可能会阻止访问 数据存储/cookies 和某些 JavaScript API）。

allow-scripts

允许页面运行脚本（但不创建弹出窗口）。如果不使用该关键字，则不允许该操作。

allow-storage-access-by-user-activation Experimental

允许 <iframe> 中加载的文档使用 Storage Access API 请求访问未分区的 cookie。

allow-top-navigation

让资源在顶层浏览上下文（名为 _top 的浏览上下文）中导航。

allow-top-navigation-by-user-activation

允许资源在顶层浏览上下文中导航，但前提是由用户手势启动。

allow-top-navigation-to-custom-protocols

允许导航至浏览器内置的非 http 协议或 通过网站注册。此功能也可通过 allow-popups 或 allow-top-navigation 关键字激活。

注意：

¥Note:

• 当嵌入文档与嵌入页面具有相同来源时，强烈建议不要同时使用 allow-scripts 和 allow-same-origin，因为这会让嵌入文档删除 sandbox 属性 - 使其并不比根本不使用 sandbox 属性更安全。
• 如果攻击者可以在沙盒 iframe 之外显示内容，例如查看者在新选项卡中打开框架，则沙盒就没用了。此类内容也应从单独的来源提供，以限制潜在的损害。

注意：当重定向用户、打开弹出窗口或从具有 sandbox 属性的 <iframe> 内的嵌入页面打开新选项卡时，新的浏览上下文受到相同的 sandbox 限制。这可能会产生问题 - 例如，如果嵌入 <iframe> 中且没有设置 sandbox="allow-forms" 或 sandbox="allow-popups-to-escape-sandbox" 属性的页面在单独的选项卡中打开一个新站点，则该新浏览上下文中的表单提交将默默失败。

¥Note: When redirecting the user, opening a popup window, or opening a new tab from an embedded page within an <iframe> with the sandbox attribute, the new browsing context is subject to the same sandbox restrictions. This can create issues — for example, if a page embedded within an <iframe> without a sandbox="allow-forms" or sandbox="allow-popups-to-escape-sandbox" attribute set on it opens a new site in a separate tab, form submission in that new browsing context will silently fail.

src

要嵌入的页面的 URL。使用值 about:blank 嵌入符合 同源策略 的空页面。另请注意，以编程方式删除 <iframe> 的 src 属性（例如通过 Element.removeAttribute()）会导致 about:blank 在 Firefox（从版本 65 开始）、基于 Chromium 的浏览器和 Safari/iOS 的框架中加载。

srcdoc

要嵌入的内联 HTML，覆盖 src 属性。如果浏览器不支持 srcdoc 属性，它将回退到 src 属性中的 URL。

width

框架的宽度（以 CSS 像素为单位）。默认为 300。

¥Deprecated attributes

这些属性已被弃用，并且可能不再受所有用户代理的支持。你不应在新内容中使用它们，并尝试从现有内容中删除它们。

¥These attributes are deprecated and may no longer be supported by all user agents. You should not use them in new content, and try to remove them from existing content.

align Deprecated

该元素相对于周围上下文的对齐方式。

frameborder Deprecated

值 1（默认值）在此框架周围绘制边框。值 0 会删除该框架周围的边框，但你应该使用 CSS 属性 border 来控制 <iframe> 边框。

longdesc Deprecated

框架内容的详细描述的 URL。由于广泛的误用，这对于非可视浏览器没有帮助。

marginheight Deprecated

框架内容与其顶部和底部边框之间的空间量（以像素为单位）。

marginwidth Deprecated

框架内容与其左右边框之间的空间量（以像素为单位）。

scrolling Deprecated

指示浏览器何时应为框架提供滚动条：

auto

仅当框架的内容大于其尺寸时。

yes

始终显示滚动条。

no

永远不要显示滚动条。

¥Scripting

内联框架与 <frame> 元素一样，包含在 window.frames 伪数组中。

¥Inline frames, like <frame> elements, are included in the window.frames pseudo-array.

使用 DOM HTMLIFrameElement 对象，脚本可以通过 contentWindow 属性访问框架资源的 window 对象。contentDocument 属性指的是 <iframe> 中的 document，与 contentWindow.document 相同。

¥With the DOM HTMLIFrameElement object, scripts can access the window object of the framed resource via the contentWindow property. The contentDocument property refers to the document inside the <iframe>, same as contentWindow.document.

从框架内部，脚本可以使用 window.parent 获取对其父窗口的引用。

¥From the inside of a frame, a script can get a reference to its parent window with window.parent.

脚本对框架内容的访问受 同源策略。如果脚本是从不同的源加载的，则脚本无法访问其他 window 对象中的大多数属性，包括访问框架父级的框架内的脚本。使用 Window.postMessage() 可以实现跨域通信。

¥Script access to a frame's content is subject to the same-origin policy. Scripts cannot access most properties in other window objects if the script was loaded from a different origin, including scripts inside a frame accessing the frame's parent. Cross-origin communication can be achieved using Window.postMessage().

¥Positioning and scaling

作为 被替换的元素，可以使用 object-position 和 object-fit 属性调整 <iframe> 元素框中嵌入文档的位置、对齐方式和缩放比例。

¥As a replaced element, the position, alignment, and scaling of the embedded document within the <iframe> element's box, can be adjusted with the object-position and object-fit properties.

¥error and load event behavior

在 <iframe> 上触发的 error 和 load 事件可用于探测本地网络 HTTP 服务器的 URL 空间。因此，作为安全预防措施，用户代理不会在 <iframe> 上触发 error 事件，并且即使 <iframe> 内容加载失败，也始终会触发 load 事件。

¥The error and load events fired on <iframe>s could be used to probe the URL space of the local network's HTTP servers. Therefore, as a security precaution user agents do not fire the error event on <iframe>s, and the load event is always triggered even if the <iframe> content fails to load.

¥Examples

¥A simple <iframe>

此示例将 https://example.org 处的页面嵌入 iframe 中。

¥This example embeds the page at https://example.org in an iframe.

HTML

<iframe
  src="https://example.org"
  title="iframe Example 1"
  width="400"
  height="300">
</iframe>

结果

¥Result

¥Accessibility concerns

使用屏幕阅读器等辅助技术进行导航的用户可以使用 <iframe> 上的 title 属性 来标记其内容。标题的值应该简洁地描述嵌入的内容：

¥People navigating with assistive technology such as a screen reader can use the title attribute on an <iframe> to label its content. The title's value should concisely describe the embedded content:

<iframe
  title="Wikipedia page for Avocados"
  src="https://en.wikipedia.org/wiki/Avocado"></iframe>

如果没有此标题，他们必须导航到 <iframe> 以确定其嵌入内容是什么。这种上下文转换可能会令人困惑且耗时，特别是对于具有多个 <iframe> 的页面和/或如果嵌入包含视频或音频等交互式内容。

¥Without this title, they have to navigate into the <iframe> to determine what its embedded content is. This context shift can be confusing and time-consuming, especially for pages with multiple <iframe>s and/or if embeds contain interactive content like video or audio.

¥Technical summary

¥See also

• CSP:frame-ancestors
• 隐私、权限和信息安全