Тег HTML <iframe>

Тег <iframe> (сокращение от inline frame — встроенный фрейм) встраивает другой HTML-документ внутрь текущей страницы. Это стандартный способ отображения стороннего контента: видеоплееров, карт, рекламы или изолированных виджетов. Встроенный документ загружается в отдельный контекст просмотра, независимый от основной страницы, однако они могут взаимодействовать через JavaScript при одинаковом происхождении (same origin).

На этой странице рассматриваются синтаксис <iframe>, его атрибуты, способы задания размеров и стилей фрейма, встроенная в браузер отложенная загрузка, а также два инструмента, к которым следует прибегать при встраивании контента, которым вы не полностью управляете: sandbox и allow.

Для встраивания не-HTML-ресурсов смотрите также теги <embed> и <frame>.

Синтаксис

Тег <iframe> является обычным HTML-элементом, которому требуется закрывающий тег. Всегда добавляйте атрибут title (см. раздел Доступность ниже).

Пример тега HTML `<iframe>`

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <iframe src="https://www.w3docs.com" title="W3docs homepage"></iframe>
  </body>
</html>

Попробуйте сами »

Для задания размеров iframe используйте атрибуты height и width или CSS. По умолчанию значения атрибутов задаются в пикселях, но также могут указываться в процентах.

Пример тега HTML `<iframe>` с атрибутами высоты и ширины

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <iframe src="https://www.w3docs.com" title="W3docs homepage" width="80%" height="300"></iframe>
  </body>
</html>

Попробуйте сами »

Современные браузеры не добавляют рамку к iframe по умолчанию. При необходимости вы можете использовать свойство CSS border для стилизации фрейма.

Пример тега HTML `<iframe>` со свойством CSS border

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <iframe src="https://www.w3docs.com" title="W3docs homepage" width="80%" height="300" style="border: none"></iframe>
  </body>
</html>

Попробуйте сами »

Встраивание HTML-кода через srcdoc

Вместо указания URL с помощью src можно передать всю разметку фрейма прямо в атрибут srcdoc. Это удобно для предварительного просмотра, изолированных фрагментов или сгенерированного HTML, когда у вас нет отдельного файла или URL. Если присутствуют оба атрибута, srcdoc имеет приоритет (а src используется как запасной вариант для браузеров, не поддерживающих srcdoc).

<iframe
  title="Inline greeting"
  srcdoc="<!DOCTYPE html><html><body><h1>Hello from srcdoc!</h1></body></html>">
</iframe>

Поскольку разметка находится в HTML-атрибуте, все буквальные двойные кавычки внутри неё должны записываться как ", а амперсанды — как &.

Отложенная загрузка внеэкранных iframe

Атрибут loading позволяет браузеру откладывать загрузку iframe до момента, когда тот вот-вот появится в области видимости. Нативная отложенная загрузка является устоявшимся веб-стандартом, поддерживаемым всеми современными браузерами примерно с 2020 года, — JavaScript-библиотека для этой типичной задачи больше не нужна.

Поддерживаемые значения:

lazy — откладывает загрузку до тех пор, пока iframe не окажется вблизи viewport. Рекомендуется для внеэкранных фреймов (видеоплееры, карты, рекламные блоки), не видимых при первой отрисовке.
eager — загружает ресурс немедленно, независимо от его положения. Это значение по умолчанию.

<iframe src="video-player.html" title="Promo video" loading="lazy"></iframe>

Откладывание загрузки внеэкранных iframe уменьшает начальный вес страницы, ускоряет первую загрузку и экономит трафик пользователя на контент, до которого он может так и не доскролить.

Ограничение контента с помощью атрибута sandbox

По умолчанию встроенная страница может выполнять скрипты, отправлять формы, открывать всплывающие окна, переходить по ссылкам на уровне верхней страницы и читать куки своего происхождения. При встраивании контента, которым вы не полностью управляете, это является угрозой безопасности. Атрибут sandbox применяет жёсткий набор ограничений, позволяя затем включить только те возможности, которые фрейму действительно необходимы, — перечислив их в виде токенов через пробел.

Пустой sandbox (то есть sandbox="") применяет все ограничения: никаких скриптов, форм, всплывающих окон, плагинов, а контент принудительно переводится в уникальное непрозрачное происхождение. Затем ограничения ослабляются поочерёдно:

Токен	Включает
`allow-forms`	Отправку форм.
`allow-same-origin`	Обработку контента как одного происхождения (чтобы он мог использовать собственные куки и хранилище).
`allow-scripts`	Выполнение JavaScript.
`allow-popups`	Открытие новых окон или вкладок (например, `window.open`, `target="_blank"`).
`allow-downloads`	Загрузку файлов.
`allow-modals`	Отображение модальных диалогов, таких как `alert()`, `confirm()` и `prompt()`.
`allow-top-navigation`	Навигацию в контексте просмотра верхнего уровня (родительской страницы).
`allow-pointer-lock`	Использование Pointer Lock API.

Используйте сочетание allow-scripts и allow-same-origin осторожно: одновременное предоставление обоих прав контенту из другого происхождения фактически позволяет ему снять собственную изоляцию — делайте это только для доверенного контента.

Пример изолированного `<iframe>`

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <iframe
      src="https://example.com/widget.html"
      title="Third-party widget"
      sandbox="allow-scripts allow-forms">
    </iframe>
  </body>
</html>

Здесь виджет может выполнять скрипты и отправлять формы, но не может переходить на родительскую страницу, открывать всплывающие окна или получать доступ к куки и хранилищу одного происхождения.

Предоставление возможностей браузера с помощью атрибута allow

В то время как sandbox управляет базовыми ограничениями контекста просмотра, атрибут allow устанавливает Permissions Policy для фрейма — он определяет, какие мощные функции браузера (камера, микрофон, геолокация, полноэкранный режим, автовоспроизведение и т.д.) может использовать встроенный документ. Большинство этих функций заблокированы в iframe с другим происхождением, если вы явно не разрешите их с помощью allow.

<iframe
  src="https://example.com/player.html"
  title="Video player"
  allow="fullscreen; camera 'none'">
</iframe>

Это предоставляет фрейму разрешение на переход в полноэкранный режим, явно запрещая доступ к камере. Вы можете ограничить функцию конкретными источниками, например: allow="geolocation 'self' https://maps.example.com".

Доступность

Каждый <iframe> должен иметь атрибут title, кратко описывающий назначение фрейма. Программы чтения с экрана объявляют заголовок, чтобы пользователи понимали, что представляет собой встроенный контент до входа в него; без заголовка фрейм объявляется лишь как безымянный «frame», что вводит в заблуждение.

<iframe src="map.html" title="Map showing our office location"></iframe>

Используйте краткий, уникальный заголовок для каждого iframe на странице (например, «Customer feedback survey», а не просто «iframe»).

Когда страница отказывается от встраивания

Встраивание не всегда проходит успешно: страница, на которую указывает src, может отказаться отображаться внутри фрейма. Сайты делают это для предотвращения кликджекинга (clickjacking), при котором злоумышленник накладывает скрытый фрейм поверх собственного интерфейса. Страница может отказаться от встраивания двумя способами:

Устаревший HTTP-заголовок ответа X-Frame-Options (DENY или SAMEORIGIN).
Современная директива Content-Security-Policy frame-ancestors, например Content-Security-Policy: frame-ancestors 'self'.

Если целевой сайт отправляет любой из этих заголовков, ваш iframe отобразит пустой фрейм или ошибку вместо контента — это ожидаемое поведение, а не ошибка в разметке. Многие крупные сайты (банки, социальные сети) блокируют встраивание в целях безопасности, именно поэтому их нельзя встроить напрямую.

Атрибуты

Атрибут	Значение	Описание
align	left right top bottom middle	Определяет выравнивание текста и его обтекание вокруг фрейма. Не поддерживается в HTML5.
allow	string	Задаёт политику, разрешающую или ограничивающую определённые функции в iframe.
allowfullscreen		Определяет, что фрейм можно открыть в полноэкранном режиме.
frameborder	1 0	Определяет, должна ли отображаться рамка вокруг iframe. Не поддерживается в HTML5.
height	pixels	Определяет высоту фрейма (по умолчанию 150px).
longdesc	URL	Определяет страницу с подробным описанием содержимого. Не поддерживается в HTML5.
marginheight	pixels	Определяет верхний и нижний отступы фрейма. Не поддерживается в HTML5.
marginwidth	pixels	Определяет левый и правый отступы фрейма. Не поддерживается в HTML5.
loading	eager lazy	Задаёт, загружается ли фрейм немедленно или откладывается до приближения к viewport.
name	text	Определяет имя фрейма (цель для ссылок и форм).
referrerpolicy	keyword	Задаёт, какая информация о реферере отправляется с запросом. Принимает ключевое слово, например `no-referrer`, `origin` или `strict-origin-when-cross-origin` — не URL.
sandbox	token list	Применяет дополнительные ограничения к содержимому фрейма. Пустое значение (`sandbox=""`) применяет все ограничения; добавьте токены через пробел, такие как `allow-scripts` или `allow-forms`, чтобы ослабить их. См. раздел sandbox.
scrolling	yes no auto	Определяет, должна ли отображаться полоса прокрутки. Не поддерживается в HTML5.
seamless	seamless	Указывает, что содержимое прикреплённого документа должно отображаться как часть родительского документа.
src	URL	Указывает адрес документа, содержимое которого будет загружено во фрейм.
srcdoc	HTML code	Хранит содержимое фрейма непосредственно в атрибуте, вместо загрузки отдельного URL.
title	text	Описывает содержимое фрейма для вспомогательных технологий. Должен присутствовать в каждом iframe.
width	pixels	Определяет ширину фрейма (по умолчанию 300px).

Тег <iframe> поддерживает глобальные атрибуты и атрибуты событий.

Связанные теги

Тег HTML <frame> — определяет отдельный фрейм внутри <frameset> (устаревшие наборы фреймов, упразднённые в HTML5).
Тег HTML <embed> — встраивает внешний контент, например плагин или медиаресурс.

Практика

Какой атрибут должен быть у каждого iframe, чтобы программы чтения с экрана могли сообщить о его назначении?

title: Описывает содержимое фрейма для вспомогательных технологий.name: Задаёт имя iframe.align: Устаревший атрибут HTML5, определявший положение фрейма слева или справа.src: Указывает URL документа для встраивания.

Синтаксис

Пример тега HTML <iframe>

Пример тега HTML <iframe> с атрибутами высоты и ширины

Пример тега HTML <iframe> со свойством CSS border

Встраивание HTML-кода через srcdoc

Отложенная загрузка внеэкранных iframe

Ограничение контента с помощью атрибута sandbox

Пример изолированного <iframe>

Предоставление возможностей браузера с помощью атрибута allow

Доступность

Когда страница отказывается от встраивания

Атрибуты

Связанные теги

Практика

Пример тега HTML `<iframe>`

Пример тега HTML `<iframe>` с атрибутами высоты и ширины

Пример тега HTML `<iframe>` со свойством CSS border

Пример изолированного `<iframe>`