<iframe>

HTML内联框架元素 (<iframe>) 表示嵌套的browsing context。它能够将另一个HTML页面嵌入到当前页面中。

每个嵌入的浏览上下文(embedded browsing context)都有自己的会话历史记录(session history)DOM树。包含嵌入内容的浏览上下文称为父级浏览上下文。顶级浏览上下文(没有父级)通常是由 Window 对象表示的浏览器窗口。

页面上每个<iframe>都会需要包括内存在内的额外计算资源,这是因为每个浏览上下文都拥有完整的文档环境。虽然理论上来说你能够在代码中写出来无限多的<iframe>,但是你最好还是先看看这么做会不会导致某些性能问题。

属性

该元素包含全局属性

allow
用于为<iframe>指定其特征策略.
allowfullscreen
设置为true时,可以通过调用 <iframe>requestFullscreen() 方法激活全屏模式。
这是一个历史遗留属性,已经被重新定义为 allow="fullscreen"
allowpaymentrequest
设置为true时,跨域的 <iframe> 就可以调用 Payment Request API
这是一个历史遗留属性,已经被重新定义为 allow="payment".
csp
对嵌入的资源配置内容安全策略。 查看 HTMLIFrameElement.csp 获取详情。
height
以CSS像素格式HTML5,或像素格式HTML 4.01,或百分比格式指定frame的高度。默认值为150
importance
表示 <iframe> src 属性指定的资源的加载优先级。允许的值有:
auto (default)
不指定优先级。浏览器根据自身情况决定资源的加载顺序
high
资源的加载优先级较高
low
资源的加载优先级较低
name
用于定位嵌入的浏览上下文的名称。该名称可以用作 <a> 标签与 <form> 标签的 target 属性值,也可以用作 <input> 标签和 <button> 标签的 formtarget 属性值,还可以用作 window.open() 方法的 windowName 参数值。
referrerpolicy
表示在获取 iframe 资源时如何发送 referrer 首部:
  • no-referrer: 不发送 Referer 首部。
  • no-referrer-when-downgrade (default): 向不受 TLS (HTTPS) 保护的 origin 发送请求时,不发送 Referer 首部。
  • origin: referrer 首部中仅包含来源页面的源。换言之,仅包含来源页面的 scheme, host, 以及 port
  • origin-when-cross-origin: 发起跨域请求时,仅在 referrer 中包含来源页面的源。发起同源请求时,仍然会在 referrer 中包含来源页面在服务器上的路径信息。
  • same-origin: 对于 same origin (同源)请求,发送 referrer 首部,否则不发送。
  • strict-origin: 仅当被请求页面和来源页面具有相同的协议安全等级时才发送 referrer 首部(比如从采用 HTTPS 协议的页面请求另一个采用 HTTPS 协议的页面)。如果被请求页面的协议安全等级较低,则不会发送 referrer 首部(比如从采用 HTTPS 协议的页面请求采用 HTTP 协议的页面)。
  • strict-origin-when-cross-origin: 当发起同源请求时,在 referrer 首部中包含完整的 URL。当被请求页面与来源页面不同源但是有相同协议安全等级时(比如 HTTPS→HTTPS),在 referrer 首部中仅包含来源页面的源。当被请求页面的协议安全等级较低时(比如 HTTPS→HTTP),不发送 referrer 首部。
  • unsafe-url: 始终在 referrer 首部中包含源以及路径 (但不包括 fragment密码,或用户名)。这个值是不安全的, 因为这样做会暴露受 TLS 保护的资源的源和路径信息。
sandbox
该属性对呈现在 iframe 框架中的内容启用一些额外的限制条件。属性值可以为空字符串(这种情况下会启用所有限制),也可以是用空格分隔的一系列指定的字符串。有效的值有:
  • allow-downloads-without-user-activation : 允许在没有征求用户同意的情况下下载文件.
  • allow-forms: 允许嵌入的浏览上下文提交表单。如果没有使用该关键字,则无法提交表单。
  • allow-modals: 允许嵌入的浏览上下文打开模态窗口。
  • allow-orientation-lock: 允许嵌入的浏览上下文锁定屏幕方向(译者注:比如智能手机、平板电脑的水平朝向或垂直朝向)。
  • allow-pointer-lock: 允许嵌入的浏览上下文使用 Pointer Lock API.
  • allow-popups: 允许弹窗 (例如 window.open, target="_blank", showModalDialog)。如果没有使用该关键字,相应的功能将自动被禁用。
  • allow-popups-to-escape-sandbox:  允许沙箱化的文档打开新窗口,并且新窗口不会继承沙箱标记。例如,安全地沙箱化一个广告页面,而不会在广告链接到的新页面中启用相同的限制条件。
  • allow-presentation: 允许嵌入的浏览上下文开始一个 presentation session
  • allow-same-origin: 如果没有使用该关键字,嵌入的浏览上下文将被视为来自一个独立的源,这将使 same-origin policy 同源检查失败。
  • allow-scripts: 允许嵌入的浏览上下文运行脚本(但不能创建弹窗)。如果没有使用该关键字,就无法运行脚本。
  • allow-storage-access-by-user-activation : 允许嵌入的浏览上下文通过 Storage Access API 使用父级浏览上下文的存储功能。
  • allow-top-navigation: 允许嵌入的浏览上下文导航(加载)内容到顶级的浏览上下文。
  • allow-top-navigation-by-user-activation: 允许嵌入的浏览上下文在经过用户允许后导航(加载)内容到顶级的浏览上下文。

注意:

  • 当被嵌入的文档与主页面同源时,强烈建议不要同时使用 allow-scriptsallow-same-origin。如果同时使用,嵌入的文档就可以通过代码删除 sandbox 属性,如此,就安全性而言还不如不用sandbox
  • 如果攻击者可以在沙箱化的 iframe 之外展示内容,例如用户在新标签页中打开内联框架,那么沙箱化也就没有意义了。建议把这种内容放置到独立的专用域中,以减小可能的损失。
  • 沙箱属性(sandbox)在Internet Explorer 9及更早的版本上不被支持。
src
被嵌套的页面的 URL 地址。使用 about:blank 值可以嵌入一个遵从同源策略的空白页。在 Firefox (version 65及更高版本)、基于 Chromium 的浏览器、Safari/iOS 中使用代码移除 iframesrc 属性(例如通过 Element.removeAttribute() )会导致 about:blank 被载入 frame。
srcdoc HTML5 only
该属性是一段HTML代码,这些代码会被渲染到 iframe 中。如果浏览器不支持 srcdoc 属性,则会渲染 src 属性表示的内容。
width
以CSS像素格式HTML5,或以像素格式HTML 4.01,或以百分比格式指定的 frame 的宽度。默认值是300

不赞成使用的属性

下面这些属性已不赞成使用,并且可能不再被所有的浏览器支持。你应避免在新项目里面使用它们,也应尽量从旧项目中移除它们。

align 已废弃 HTML4.01, 已废弃 HTML5
此元素相对于周围元素的对齐方式。
frameborder 已废弃 HTML5
值为1(默认值)时,显示此框架的边框。值为0时移除边框。此属性已不赞成使用,请使用 CSS 属性 border 代替。
longdesc 已废弃 HTML5
表示框架内容的长描述的 URL。由于广泛的误用,该属性对于无图形界面的浏览器不起作用。
marginheight 已废弃 HTML5
这个属性定义了框架的内容距其上边框与下边框的距离,单位是像素。
marginwidth 已废弃 HTML5
这个属性定义了框架的内容距其左边框和右边框的距离,单位是像素。
scrolling 已废弃 HTML5
这个属性控制是否要在框架内显示滚动条,允许的值包括:
  • auto: 仅当框架的内容超出框架的范围时显示滚动条。
  • yes: 始终显示滚动条。
  • no: 从不显示滚动条。

非标准属性   

mozbrowser  

查看 bug 1318532 了解如何在 Firefox 的 WebExtensions 中使用此属性。

这个属性可以让 <iframe> 变得像顶级浏览器窗口,详情请参看 Browser API。这个属性只能WebExtensions 中使用。

脚本

内联的框架,就像 <frame> 元素一样,会被包含在 window.frames 伪数组(类数组的对象)中。

有了 DOM HTMLIFrameElement 对象,脚本可以通过 contentWindow 访问内联框架的 window 对象。 contentDocument 属性则引用了 <iframe> 内部的 document 元素,(等同于使用contentWindow.document),但IE8-不支持。

在框架内部,脚本可以通过 window.parent 引用父窗口对象。

脚本访问框架内容必须遵守同源策略,并且无法访问非同源的 window 对象的几乎所有属性。同源策略同样适用于子窗体访问父窗体的 window 对象。跨域通信可以通过 window.postMessage 来实现。

定位和缩放

作为一个可替换元素, 可以使用 object-positionobject-fit 来定位、对齐、缩放 <iframe> 元素内的文档。

示例

一个简单的 <iframe>

下面的例子中,我们创建了一个框架。当用户点击框架中的按钮时,浏览器会弹出一个提示框。

HTML

<iframe src="https://mdn-samples.mozilla.org/snippets/html/iframe-simple-contents.html" title="iframe example 1" width="400" height="300">
  <p>Your browser does not support iframes.</p>
</iframe>

Result

在新标签页中打开 <iframe> 里面的链接

下面的例子演示了在框架中展示谷歌地图。

HTML

<base target="_blank">
<iframe id="Example2"
    title="Example2"
    width="400"
    height="300"
    frameborder="0"
    scrolling="no"
    marginheight="0"
    marginwidth="0"
    src="https://maps.google.com/maps?f=q&amp;source=s_q&amp;hl=es-419&amp;geocode=&amp;q=buenos+aires&amp;sll=37.0625,-95.677068&amp;sspn=38.638819,80.859375&amp;t=h&amp;ie=UTF8&amp;hq=&amp;hnear=Buenos+Aires,+Argentina&amp;z=11&amp;ll=-34.603723,-58.381593&amp;output=embed">
</iframe>

<br>
<small>
  <a href="https://maps.google.com/maps?f=q&amp;source=embed&amp;hl=es-419&amp;geocode=&amp;q=buenos+aires&amp;sll=37.0625,-95.677068&amp;sspn=38.638819,80.859375&amp;t=h&amp;ie=UTF8&amp;hq=&amp;hnear=Buenos+Aires,+Argentina&amp;z=11&amp;ll=-34.603723,-58.381593" style="color:#0000FF;text-align:left"> See bigger map </a>
</small>

Result

无障碍环境

使用 iframetitle 属性来标识框架的主要内容,这样可以极大方便使用辅助技术(例如屏幕阅读器)浏览网页的人。框架的标题应该清楚地描述框架的内容,例如:

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

如果没有标题,他们就只能浏览每一个框架来获取需要的内容。这非常耗时间,也很容易让人迷惑,尤其是当页面中包含很多框架或者互动内容如音视频等的时候。

规范

规范 状态 说明
Referrer Policy
referrerpolicy attribute
Candidate Recommendation 新增属性: referrerpolicy
HTML Living Standard
<iframe>
Living Standard
HTML5
<iframe>
Recommendation
HTML 4.01 Specification
<iframe>
Recommendation
Screen Orientation API Working Draft Adds allow-orientation-lock to the sandbox attribute.
Presentation API
allow-presentation
Candidate Recommendation Adds allow-presentation to the sandbox attribute

浏览器兼容性

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
iframeChrome Full support 1Edge Full support YesFirefox Full support Yes
Notes
Full support Yes
Notes
Notes The resize CSS property doesn't have any effect on this element due to bug 680823.
IE Full support YesOpera Full support YesSafari Full support Yes
Notes
Full support Yes
Notes
Notes Safari has a bug that prevents iframes from loading if the iframe element was hidden when added to the page. iframeElement.src = iframeElement.src should cause it to load the iframe.
WebView Android Full support YesChrome Android Full support YesFirefox Android Full support Yes
Notes
Full support Yes
Notes
Notes The resize CSS property doesn't have any effect on this element due to bug 680823.
Opera Android Full support YesSafari iOS Full support Yes
Notes
Full support Yes
Notes
Notes Safari has a bug that prevents iframes from loading if the iframe element was hidden when added to the page. iframeElement.src = iframeElement.src should cause it to load the iframe.
Samsung Internet Android Full support Yes
align
Deprecated
Chrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
allow
Experimental
Chrome Full support 60Edge No support NoFirefox No support NoIE No support NoOpera Full support 47Safari Full support 11.1WebView Android Full support 60Chrome Android Full support 60Firefox Android No support NoOpera Android Full support 44Safari iOS Full support 11.3Samsung Internet Android No support No
allowfullscreenChrome Full support 27
Full support 27
Full support 17
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Edge Full support YesFirefox Full support 18
Full support 18
Full support 9
Prefixed
Prefixed Implemented with the vendor prefix: moz
IE Full support 11
Prefixed
Full support 11
Prefixed
Prefixed Implemented with the vendor prefix: ms
Opera Full support YesSafari Full support 7
Full support 7
Full support Yes
Prefixed
Prefixed Implemented with the vendor prefix: webkit
WebView Android Full support 37
Full support 37
Full support 37
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Chrome Android Full support 27
Full support 27
Full support 18
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Firefox Android Full support 18
Full support 18
Full support 9
Prefixed
Prefixed Implemented with the vendor prefix: moz
Opera Android Full support YesSafari iOS Full support 7
Full support 7
Full support Yes
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Samsung Internet Android Full support Yes
Full support Yes
Full support Yes
Prefixed
Prefixed Implemented with the vendor prefix: webkit
allowpaymentrequest
Experimental
Chrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
External protocol URLs blocked
Deprecated
Chrome ? Edge ? Firefox Full support 67IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Firefox Android Full support 67Opera Android ? Safari iOS ? Samsung Internet Android ?
frameborder
Deprecated
Chrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
heightChrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
longdesc
Deprecated
Chrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
marginheight
Deprecated
Chrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
marginwidth
Deprecated
Chrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
mozbrowser
Non-standard
Chrome No support NoEdge No support NoFirefox No support No
Notes
No support No
Notes
Notes See bug 1318532
Notes Available only to WebExtensions.
IE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support No
Notes
No support No
Notes
Notes See bug 1318532
Notes Available only to WebExtensions.
Opera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
nameChrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
referrerpolicyChrome Full support 51Edge No support NoFirefox Full support 50IE No support NoOpera Full support 38Safari Full support 11.1WebView Android Full support 51Chrome Android Full support 51Firefox Android Full support 50Opera Android Full support 41Safari iOS No support NoSamsung Internet Android Full support 7.2
sandboxChrome Full support 4Edge Full support YesFirefox Full support 17IE Full support 10Opera Full support 15Safari Full support 5WebView Android Full support YesChrome Android Full support YesFirefox Android Full support 17Opera Android ? Safari iOS Full support 4.2Samsung Internet Android Full support Yes
sandbox="allow-modals"Chrome ? Edge No support NoFirefox Full support 49IE No support NoOpera ? Safari ? WebView Android ? Chrome Android ? Firefox Android Full support 49Opera Android ? Safari iOS ? Samsung Internet Android ?
sandbox="allow-popups"Chrome Full support YesEdge Full support YesFirefox Full support 28IE ? Opera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesFirefox Android Full support 27Opera Android ? Safari iOS ? Samsung Internet Android Full support Yes
sandbox="allow-popups-to-escape-sandbox"Chrome Full support 46Edge No support NoFirefox Full support 49IE No support NoOpera Full support 32Safari ? WebView Android Full support 46Chrome Android Full support 46Firefox Android Full support 49Opera Android Full support 32Safari iOS ? Samsung Internet Android Full support 5.0
sandbox="allow-presentation"Chrome Full support 53Edge No support NoFirefox Full support 50IE No support NoOpera Full support 40Safari ? WebView Android No support NoChrome Android Full support 53Firefox Android Full support 50Opera Android Full support 41Safari iOS ? Samsung Internet Android Full support 6.0
sandbox="allow-storage-access-by-user-activation"
ExperimentalNon-standard
Chrome No support NoEdge No support NoFirefox Full support 65
Disabled
Full support 65
Disabled
Disabled From version 65: this feature is behind the dom.storage_access.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera No support NoSafari Full support 11.1
Notes
Full support 11.1
Notes
Notes Currently only available on macOS High Sierra 10.13.4 beta, and in Safari Technology Preview 47+.
WebView Android No support NoChrome Android No support NoFirefox Android Full support 65
Disabled
Full support 65
Disabled
Disabled From version 65: this feature is behind the dom.storage_access.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android No support NoSafari iOS Full support 11.1
Notes
Full support 11.1
Notes
Notes Currently only available on iOS 11.3 beta.
Samsung Internet Android ?
sandbox="allow-top-navigation-by-user-activation"Chrome Full support 58Edge No support NoFirefox No support NoIE No support NoOpera Full support 45Safari Full support 11.1
Notes
Full support 11.1
Notes
Notes Not initially available in 11.1, but added in sub-version 13605.1.33.1.2.
WebView Android Full support 58Chrome Android Full support 58Firefox Android No support NoOpera Android Full support 43Safari iOS ? Samsung Internet Android Full support 7.0
scrolling
Deprecated
Chrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
srcChrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
srcdocChrome Full support 20Edge No support NoFirefox Full support 25IE No support NoOpera Full support 15Safari Full support 6WebView Android Full support 37Chrome Android Full support 25Firefox Android Full support 25Opera Android ? Safari iOS ? Samsung Internet Android Full support Yes
widthChrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
Experimental. Expect behavior to change in the future.
Experimental. Expect behavior to change in the future.
Non-standard. Expect poor cross-browser support.
Non-standard. Expect poor cross-browser support.
Deprecated. Not for use in new websites.
Deprecated. Not for use in new websites.
See implementation notes.
See implementation notes.
User must explicitly enable this feature.
User must explicitly enable this feature.
Requires a vendor prefix or different name for use.
Requires a vendor prefix or different name for use.