<iframe>：内联框架元素

试一试

<iframe
  id="inlineFrameExample"
  title="Inline Frame Example"
  width="300"
  height="200"
  src="https://www.openstreetmap.org/export/embed.html?bbox=-0.004017949104309083%2C51.47612752641776%2C0.00030577182769775396%2C51.478569861898606&amp;layer=mapnik">
</iframe>

iframe {
  border: 1px solid black;
  width: 100%; /* takes precedence over the width set with the HTML width attribute */
}

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

属性

此元素包含全局属性。

allow

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

有关示例，请参见Permissions-Policy主题中的iframe。

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

allowfullscreen

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

注意：此属性被认为是遗留属性，并重新定义为allow="fullscreen"。

allowpaymentrequest 已废弃 非标准

如果允许跨源<iframe>调用Payment Request API，则设置为true。

注意：此属性被认为是遗留属性，并重新定义为allow="payment"。

browsingtopics 实验性 非标准

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

credentialless 实验性

设置为true可使<iframe>无凭证，这意味着其内容将在新的、临时上下文中加载。它无法访问与其源关联的网络、cookie 和存储数据。它使用一个新上下文，该上下文在顶层文档生命周期内是本地的。作为回报，可以取消Cross-Origin-Embedder-Policy（COEP）嵌入规则，因此设置了 COEP 的文档可以嵌入未设置 COEP 的第三方文档。有关更多详细信息，请参见IFrame 无凭证。

csp 实验性

针对嵌入资源强制执行的内容安全策略。有关详细信息，请参阅HTMLIFrameElement.csp。

height

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

loading

指示浏览器何时加载 iframe

eager

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

lazy

延迟加载 iframe，直到它达到与视觉视口的计算距离（由浏览器定义）。目的是避免使用获取框架所需的网络和存储带宽，直到浏览器合理地确定需要它为止。这在大多数典型用例中改善了性能和成本，特别是通过减少初始页面加载时间。

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

name

嵌入式浏览上下文的可寻址名称。这可以在<a>、<form>或<base>元素的target属性中，<input>或<button>元素的formtarget属性中，或window.open()方法的windowName参数中使用。此外，该名称成为Window和Document对象的属性，其中包含对嵌入式窗口或元素本身的引用。

referrerpolicy

指示在获取框架资源时要发送哪个引用者

no-referrer

不会发送Referer头。

no-referrer-when-downgrade

不会向没有TLS (HTTPS) 的来源发送Referer头。

origin

发送的引用者将仅限于引用页面的来源：其方案、主机和端口。

origin-when-cross-origin

发送给其他源的引用者将仅限于方案、主机和端口。同一源的导航仍将包含路径。

same-origin

将为同源发送引用者，但跨源请求将不包含引用者信息。

strict-origin

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

strict-origin-when-cross-origin (默认)

当执行同源请求时发送完整 URL，当协议安全级别保持不变 (HTTPS→HTTPS) 时仅发送来源，并且不向安全性较低的目标 (HTTPS→HTTP) 发送任何头。

unsafe-url

引用者将包含来源和路径（但不包含片段、密码或用户名）。此值不安全，因为它会将 TLS 保护资源的来源和路径泄露给不安全的来源。

sandbox

控制应用于嵌入在<iframe>中的内容的限制。属性的值可以是空以应用所有限制，或以空格分隔的令牌以取消特定限制

allow-downloads

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

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"创建）。如果未使用此关键字，此类功能将静默失败。

allow-popups-to-escape-sandbox

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

allow-presentation

允许嵌入者控制 iframe 是否可以开始演示会话。

allow-same-origin

如果未使用此令牌，则资源将被视为来自一个特殊来源，该来源始终无法通过同源策略（可能会阻止访问数据存储/Cookie和某些 JavaScript API）。

allow-scripts

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

allow-storage-access-by-user-activation 实验性

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

allow-top-navigation

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

allow-top-navigation-by-user-activation

让资源导航顶层浏览上下文，但仅限于用户手势发起。

allow-top-navigation-to-custom-protocols

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

备注

• 当嵌入文档与嵌入页面同源时，强烈不建议同时使用allow-scripts和allow-same-origin，因为这会使嵌入文档删除sandbox属性——使其安全性不比完全不使用sandbox属性更高。
• 如果攻击者可以在沙盒iframe外部显示内容（例如，如果查看器在新选项卡中打开框架），沙盒就毫无用处。此类内容也应从单独的来源提供，以限制潜在的损害。

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

src

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

注意：about:blank页面在解析任何相对 URL（例如锚链接）时，使用嵌入文档的 URL 作为其基本 URL。

srcdoc

要嵌入的内联 HTML，覆盖src属性。其内容应遵循完整 HTML 文档的语法，其中包括文档类型声明、<html>、<body>标签等，尽管其中大部分可以省略，只留下正文内容。此文档的location将是about:srcdoc。如果浏览器不支持srcdoc属性，它将回退到src属性中的 URL。

注意：about:srcdoc页面在解析任何相对 URL（例如锚链接）时，使用嵌入文档的 URL 作为其基本 URL。

width

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

已弃用属性

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

align 已弃用

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

frameborder 已废弃

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

longdesc 已废弃

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

marginheight 已废弃

框架内容与其顶部和底部边框之间的像素间距。

marginwidth 已废弃

框架内容与其左右边框之间的像素间距。

scrolling 已废弃

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

auto

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

是

始终显示滚动条。

否

从不显示滚动条。

脚本

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

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

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

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

跨源框架中的顶级导航

在同源框架中运行的脚本可以访问Window.top属性，并设置window.top.location以将顶级页面重定向到新位置。此行为称为“顶级导航”。

只有当框架具有粘性激活时，跨源框架才允许使用top重定向顶级页面。如果顶级导航被阻止，浏览器可能会提示用户允许重定向或在开发者控制台中报告错误（或两者）。浏览器的此限制称为框架破坏干预。这意味着跨源框架无法立即重定向顶级页面——用户必须之前与框架交互或授予重定向权限。

沙盒框架会阻止所有顶级导航，除非sandbox属性值设置为allow-top-navigation或allow-top-navigation-by-user-activation。请注意，顶级导航权限是继承的，因此嵌套框架只有在其父框架也允许的情况下才能执行顶级导航。

定位和缩放

作为替换元素，<iframe>允许使用object-position属性调整嵌入文档在其框中的位置。

error 和 load 事件行为

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

无障碍

使用辅助技术（如屏幕阅读器）浏览的用户可以使用<iframe>上的title属性来标记其内容。标题的值应简洁地描述嵌入内容

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

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

示例

一个基本的 <iframe>

此示例在 iframe 中嵌入了https://example.org的页面。这是 iframe 的常见用例：嵌入来自其他网站的内容。例如，实时示例本身以及顶部的尝试一下示例都是来自另一个 MDN 网站的<iframe>嵌入内容。

HTML

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

结果

在 <iframe> 中嵌入源代码

此示例直接在 iframe 中渲染源代码。当显示用户生成的内容时，结合sandbox属性，这可以用作防止脚本注入的技术。

请注意，当使用srcdoc时，嵌入内容中的任何相对 URL 都将相对于嵌入页面的 URL 进行解析。如果您想使用指向嵌入内容中位置的锚链接，则需要明确指定about:srcdoc作为基本 URL。

HTML

<article>
  <footer>Nine minutes ago, <i>jc</i> wrote:</footer>
  <iframe
    sandbox
    srcdoc="<p>There are two ways to use the <code>iframe</code> element:</p>
<ol>
<li><a href=&quot;about:srcdoc#embed_another&quot;>To embed content from another page</a></li>
<li><a href=&quot;about:srcdoc#embed_user&quot;>To embed user-generated content</a></li>
</ol>
<h2 id=&quot;embed_another&quot;>Embedding content from another page</h2>
<p>Use the <code>src</code> attribute to specify the URL of the page to embed:</p>
<pre><code>&amp;lt;iframe src=&quot;https://example.org&quot;&amp;gt;&amp;lt;/iframe&amp;gt;</code></pre>
<h2 id=&quot;embed_user&quot;>Embedding user-generated content</h2>
<p>Use the <code>srcdoc</code> attribute to specify the content to embed. This post is already an example!</p>
"
    width="500"
    height="250"
></iframe>
</article>

以下是使用srcdoc时如何编写转义序列

• 首先，编写 HTML，转义任何您将在普通 HTML 文档中转义的内容（例如<、>、&等）。
• < 和 < 在 srcdoc 属性中表示完全相同的字符。因此，要使其在 HTML 文档中成为实际的转义序列，请将所有和号（&）替换为 &。例如，< 变为 <，& 变为 &。
• 将所有双引号 (") 替换为"，以防止srcdoc属性过早终止（如果您使用'，则应将'替换为'）。此步骤发生在上一​​步之后，因此在此步骤中生成的"不会变成"。

结果

技术摘要

规范

浏览器兼容性

另见

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