<iframe> Элемент встроенного фрейма HTML

Элемент <iframe> HTML представляет собой вложенный контекст просмотра, встраивая другую HTML-страницу в текущую.

Попробуйте

<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> (например, доступ к микрофону, камере, аккумулятору, функции web-share и т. д.) в зависимости от источника запроса.

Примеры см. в разделе iframe темы Permissions-Policy.

Примечание: Политика разрешений, заданная атрибутом allow, вводит дополнительное ограничение поверх политики, заданной заголовком Permissions-Policy. Она не заменяет его.

allowfullscreen

Задайте значение true, если <iframe> может активировать полноэкранный режим вызовом метода requestFullscreen().

Примечание: Этот атрибут считается устаревшим и переопределен как allow="fullscreen *".

allowpaymentrequest

Задайте значение true, если межсайтовому <iframe> разрешено вызывать API запросов на оплату.

Примечание: Этот атрибут считается устаревшим и переопределен как allow="payment *".

browsingtopics

Логический атрибут, который, если он указан, определяет, что выбранные для текущего пользователя темы должны отправляться вместе с запросом источника <iframe>. Подробнее см. в разделе Использование API Topics.

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. Это мера защиты от отслеживания: если бы пользовательский агент поддерживал отложенную загрузку при отключенных сценариях, сайт все равно мог бы отслеживать примерное положение прокрутки пользователя на протяжении сеанса, стратегически размещая iframe в разметке страницы, чтобы сервер мог отслеживать количество запрошенных iframe и время их запроса.

name

Имя встроенного контекста просмотра, по которому на него можно ссылаться. Его можно использовать в атрибуте target элементов <a>, <form> или <base>; в атрибуте formtarget элементов <input> или <button>; либо в параметре windowName метода window.open(). Кроме того, это имя становится свойством объектов Window и Document, содержащим ссылку на встроенное окно или сам элемент.

privateToken

Содержит строковое представление объекта параметров, описывающего операцию с токеном приватного состояния; этот объект имеет ту же структуру, что и свойство privateToken словаря RequestInit. IFrame с этим атрибутом могут запускать такие операции, как выпуск или погашение токенов, при загрузке встроенного содержимого.

referrerpolicy

Указывает, какой источник перехода отправлять при загрузке ресурса фрейма:

no-referrer

Заголовок Referer отправляться не будет.

no-referrer-when-downgrade

Заголовок Referer не будет отправляться к источникам без TLS (HTTPS).

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

Разрешает скачивать файлы через элемент <a> или <area> с атрибутом download, а также посредством перехода, который приводит к скачиванию файла. Это работает независимо от того, нажал ли пользователь ссылку или код JS инициировал действие без участия пользователя.

allow-forms

Разрешает странице отправлять формы. Если это ключевое слово не используется, форма отображается как обычно, но её отправка не запускает проверку введённых данных, не отправляет данные на веб-сервер и не закрывает диалоговое окно.

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, а также к некоторым API JavaScript).

Примечание: Если задан allow-same-origin, родительский документ с тем же источником всё ещё может получать доступ к DOM iframe и взаимодействовать с ним, даже если allow-scripts не задан. Токен allow-scripts управляет только выполнением скриптов во встроенном контексте просмотра и не влияет на доступ родительского документа к DOM.

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, например, если пользователь открывает фрейм в новой вкладке. Такое содержимое также следует размещать на отдельном источнике, чтобы ограничить возможный ущерб.

Примечание: При перенаправлении пользователя, открытии всплывающего окна или новой вкладки со встроенной страницы внутри <iframe> с атрибутом sandbox на новый контекст просмотра распространяются те же ограничения sandbox. Это может вызвать проблемы: например, если страница, встроенная в <iframe> без атрибута sandbox="allow-forms" или sandbox="allow-popups-to-escape-sandbox", открывает новый сайт в отдельной вкладке, отправка формы в этом новом контексте просмотра будет молча завершаться неудачей.

src

URL страницы для встраивания. Используйте значение about:blank, чтобы встроить пустую страницу, соответствующую политике одного источника. Также обратите внимание: программное удаление атрибута src у <iframe> (например, с помощью Element.removeAttribute()) приводит к загрузке about:blank во фрейме в Firefox (начиная с версии 65), браузерах на основе Chromium и Safari/iOS.

Примечание: При разрешении относительных URL, например ссылок-якорей, страница about:blank использует URL встраивающего документа в качестве базового URL.

srcdoc

Встраиваемый HTML-код, переопределяющий атрибут src. Его содержимое должно соответствовать синтаксису полного HTML-документа, включая директиву doctype, теги <html> и <body> и т. д., хотя большинство из них можно опустить, оставив только содержимое body. Местоположением этого документа будет about:srcdoc. Если браузер не поддерживает атрибут srcdoc, он использует URL из атрибута src.

Примечание: При разрешении относительных URL, например ссылок-якорей, страница about:srcdoc использует URL встраивающего документа в качестве базового URL.

width

Ширина фрейма в CSS-пикселях. Значение по умолчанию — 300.

Устаревшие атрибуты

Эти атрибуты устарели и могут больше не поддерживаться некоторыми пользовательскими агентами. Не используйте их в новом содержимом и постарайтесь удалить из существующего.

align

Выравнивание этого элемента относительно окружающего контекста.

frameborder

Значение 1 (по умолчанию) добавляет рамку вокруг этого фрейма. Значение 0 убирает рамку, однако для управления рамками <iframe> следует использовать свойство CSS border.

longdesc

URL подробного описания содержимого фрейма. Из-за широкого распространения неправильного использования этот атрибут бесполезен для невизуальных браузеров.

marginheight

Расстояние в пикселях между содержимым фрейма и его верхней и нижней границами.

marginwidth

Расстояние в пикселях между содержимым фрейма и его левой и правой границами.

scrolling

Указывает, когда браузер должен отображать полосу прокрутки для фрейма:

auto

Только если содержимое фрейма больше его размеров.

yes

Всегда отображать полосу прокрутки.

no

Никогда не отображать полосу прокрутки.

Скрипты

Встроенные фреймы, как и элементы <frame>, включаются в псевдомассив window.frames.

С помощью объекта DOM HTMLIFrameElement скрипты могут получать доступ к объекту window встроенного ресурса через свойство contentWindow. Свойство contentDocument ссылается на document внутри <iframe>, как и 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

События error и load, срабатывающие для <iframe>, можно использовать для проверки пространства URL HTTP-серверов локальной сети. Поэтому в целях безопасности пользовательские агенты не вызывают событие ошибки для <iframe>, а событие загрузки срабатывает всегда, даже если содержимое <iframe> не удалось загрузить.

Доступность

Люди, использующие вспомогательные технологии, например программы чтения с экрана, могут использовать атрибут title у элемента <iframe>, чтобы дать название его содержимому. Значение title должно кратко описывать встроенное содержимое:

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

Без этого заголовка им приходится переходить внутрь элемента <iframe>, чтобы определить, что представляет собой его встроенное содержимое. Такая смена контекста может сбивать с толку и отнимать много времени, особенно на страницах с несколькими элементами <iframe> и/или если во встроенном содержимом есть интерактивные элементы, например видео или аудио.

Примеры

Простой элемент <iframe>

В этом примере страница https://example.org встраивается в iframe. Это распространённый сценарий использования iframe: встраивание содержимого с другого сайта. Например, сам интерактивный пример и пример попробуйте вверху — это встроенные элементы <iframe> с содержимым с другого сайта MDN.

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>

Вот как записывать escape-последовательности при использовании srcdoc:

• Сначала запишите HTML-код, экранируя все символы, которые вы экранировали бы в обычном HTML-документе (например, <, >, & и т. д.).
• < и < обозначают один и тот же символ в атрибуте srcdoc. Поэтому, чтобы это стало настоящей escape-последовательностью в HTML-документе, замените все амперсанды (&) на &. Например, < превращается в <, а & — в &.
• Замените все двойные кавычки (") на ", чтобы атрибут srcdoc не завершился преждевременно (если вместо этого вы используете ', замените ' на '). Этот шаг выполняется после предыдущего, поэтому ", добавленные на этом шаге, не превращаются в ".

Результат

Техническая сводка

Спецификации

Совместимость с браузерами

См. также

• CSP: frame-ancestors
• Конфиденциальность, разрешения и информационная безопасность