<iframe>: Елемент супутнього фрейму

Елемент HTML <iframe> (супутній фрейм) представляє вкладений навігаційний контекст, вбудовуючи іншу сторінку HTML в поточну.

Спробуйте його в дії

Кожен вбудований навігаційний контекст має власний документ і дозволяє переходи за URL. Переходи кожного вбудованого навігаційного контексту лінеаризуються в історію сесії навігаційного контексту найвищого рівня. Навігаційний контекст, що вбудовує інші контекст, зветься батьківським навігаційним контекстом. Навігаційний контекст найвищого рівня – той, що не має батьківського – зазвичай є вікном браузера, представленим об'єктом Window.

[!WARNING] Через те, що кожен навігаційний контекст є повноцінним середовищем документа, кожен <iframe> на сторінці потребує додаткових пам'яті та інших обчислювальних ресурсів. Хоч теоретично можна використовувати скільки завгодно <iframe>, слід слідкувати за проблемами швидкодії.

Атрибути

Цей елемент приймає глобальні атрибути.

• allow

  • : Задає політику дозволів для <iframe>. Політика визначає те, які можливості доступні <iframe> (наприклад, доступ до мікрофона, камери, батареї, поширення в Інтернеті тощо), залежно від походження запиту.

    Дивіться приклади в супутніх фреймах на сторінці Permissions-Policy.

    [!NOTE] Політика дозволів, задана атрибутом allow, реалізовує додаткові обмеження, поверх політики, заданої в заголовку Permissions-Policy. Перша не замінює другу.

• allowfullscreen

  • : Слід надати цьому атрибутові значення true, якщо <iframe> може активувати повноекранний режим, викликавши метод requestFullscreen().

    [!NOTE] Цей атрибут вважається застарілим, він був перевизначений як allow="fullscreen".

• allowpaymentrequest

  • : Слід надати цьому атрибутові значення true, якщо <iframe> до іншого походження треба дозволити викликати API запитів платежів.

    [!NOTE] Цей атрибут вважається застарілим, він був перевизначений як allow="payment".

• browsingtopics

  • : Булів атрибут, котрий, якщо присутній, задає те, що вибрані теми для поточного користувача мають бути надіслані разом із запитом на джерело цього <iframe>. Дивіться подробиці у Використанні API тем.

• credentialless

  • : Можна задати true, аби зробити <iframe> безправним, тобто його вміст буде завантажений у новий, ефемерний контекст. Він не матиме доступу до мережі, реп'яшків та сховища даних, пов'язаних з його походженням. Такий фрейм використовуватиме новий контекст, локальний щодо часу життя документа верхнього рівня. Зате правила вбудовування Cross-Origin-Embedder-Policy (COEP) можуть не застосовуватися, тож документи, для яких задано COEP, можуть вбудовувати сторонні документи, для яких COEP не задано. Подробиці – на сторінці безправного IFrame

• csp

  • : Політика захисту вмісту, нав'язана вбудованому ресурсу. Дивіться HTMLIFrameElement.csp для отримання подробиць.

• height

  • : Висота фрейму в пікселях CSS. Усталене значення – 150.

• loading

  • : Вказує, коли браузер повинен завантажувати супутній фрейм:

    eager

    Завантажувати супутній фрейм негайно, при завантаженні сторінки (усталене значення).

    lazy

    Відкласти завантаження супутнього фрейму до часу, коли він досягне обчисленої відстані від візуальної області перегляду, як задано браузером. Це задумано для того, щоб уникнути використання мережевої пропускної здатності та місця в пам'яті на отримання фрейму, поки браузеру не стане зрозуміло, що це необхідно. Це покращує ефективність і вартість в більшості типових випадків використання, а саме – шляхом зменшення часу початкового завантаження сторінки.

    [!NOTE] Завантаження відкладається лише за умови того, що JavaScript увімкнено. Така поведінка – захист від стеження.

• name

  • : Ім'я вбудованого навігаційного контексту, на котре можна цілитися. Може використовуватися в атрибуті target елементів <a>, <form> і <base>; атрибуті formtarget елементів <input> і <button>; параметрі windowName метода window.open().

• 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", Window.showModalDialog()). Якщо це ключове слово не застосовано, то спроба використати цю функціональність тихо зазнає невдачі.

    allow-popups-to-escape-sandbox

    Дозволяє огородженому документові відкрити новий навігаційний контекст без накладання на нього позначок огородження. Це дозволяє, наприклад, сторонньому рекламному оголошенню бути безпечно огородженим, не накладаючи такі самі обмеження на сторінки, на котрі воно посилається. Якщо ця позначка не додана, то сторінка переспрямування, спливне вікно чи нова вкладка підпадатиме під ті самі обмеження огородження, що й вихідний <iframe>.

    allow-presentation

    Дозволяє батьківській сторінці контролювати те, чи може супутній фрейм починати сеанс презентації.

    allow-same-origin

    Якщо ця позначка не застосована, то ресурс вважається таким, що має особливе походження, котре ніколи не відповідає політиці того самого походження (потенційно запобігаючи доступові до сховища даних і реп'яшків і певних API JavaScript).

    allow-scripts

    Дозволяє сторінці запускати сценарії (але не створювати спливні вікна). Якщо це ключове слово не вжито, то така операція – не дозволена.

    allow-storage-access-by-user-activation

    Дозволяє документові, завантаженому в <iframe>, використовувати API доступу до сховища, щоб запитувати доступ до нерозділених реп'яшків.

    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 – наприклад, якщо переглядач відкриє фрейм у новій вкладці. Такий вміст повинен також надаватися з окремого походження, щоб обмежити потенційну шкоду.

    [!NOTE] При переспрямуванні користувача, відкритті спливного вікна чи нової вкладки зі вбудованої в <iframe> з атрибутом sandbox сторінки, новий навігаційний контекст підпадає під такі ж обмеження sandbox. Це може створювати проблеми: наприклад, якщо сторінка, вбудована в <iframe>, на якому не задано атрибут sandbox="allow-forms" або sandbox="allow-popups-to-escape-sandbox", відкриває новий сайт в окремій вкладці, то подання форми в цьому новому навігаційному контексті не спрацьовуватиме, без сповіщення про це користувача.

• src

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

  [!NOTE] Сторінка about:blank використовує URL документа, що вбудовується, як свій базовий URL, коли розв'язуються відносні URL, наприклад, якірні посилання.

• srcdoc

  • : Супутній HTML для вбудовування, що відкидає атрибут src. Його вміст повинен відповідати синтаксису цілого документа URL, що складається з директиви doctype, тегів <html>, <body> тощо, хоч і більшість з цих тегів можна пропустити, залишивши лише вміст тіла. Такий документ матиме адресу about:srcdoc. Якщо браузер не підтримує атрибут srcdoc, то звернеться до URL в атрибуті src.

    [!NOTE] Сторінка about:srcdoc використовує URL документа, що вбудовується, як свій базовий 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 через властивість contentWindow сценарії можуть доступатися до об'єкта window вбудованого ресурсу. Властивість contentDocument вказує на document всередині <iframe>, так само як contentWindow.document.

Зсередини фрейму сценарій може отримати посилання на батьківське вікно за допомогою window.parent.

Доступ сценарію до вмісту фрейму є предметом політики того самого походження. Сценарії не можуть доступатися до більшості властивостей інших об'єктів window, якщо сценарій був завантажений з іншого походження, включно з доступом сценаріїв всередині фрейму до батьківського вікна фрейму. Спілкування між ресурсами з різних походжень можна досягнути за допомогою Window.postMessage().

Розташування й масштабування

Оскільки <iframe> є заміщеним елементом, то він дає змогу підлаштовувати позицію вбудованого в ньому документа в його рамці за допомогою властивості object-position.

[!NOTE] Властивість object-fit не діє на елементи <iframe>.

Логіка подій error і load

Події error і load, запущені на елементах <iframe>, можуть використовуватися для вивчення простору URL серверів HTTP локальної мережі. У зв'язку з цим, з міркувань безпеки, користувацькі агенти не запускають подію error на елементах <iframe>, а подія load завжди запускається, навіть якщо вміст <iframe> не вийшло завантажити.

Доступність

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

<iframe
  title="Сторінка Вікіпедії про авокадо"
  src="https://uk.wikipedia.org/wiki/%D0%90%D0%B2%D0%BE%D0%BA%D0%B0%D0%B4%D0%BE"></iframe>

Без цього title їм доведеться перейти до <iframe>, щоб з'ясувати, який вміст вбудовано. Така зміна контексту може спантеличувати й забирати час, особливо для сторінок з багатьма <iframe> чи коли вбудований інтерактивний вміст, як то відео чи аудіо.

Приклади

Простий <iframe>

Цей приклад вбудовує сторінку https://example.org в супутній фрейм. Це поширений випадок для використання супутніх фреймів: вбудовування вмісту з іншого сайту. Наприклад, як у самому живому зразку нижче, так і в прикладі "спробуйте його в дії" нагорі, <iframe> вбудовує вміст з іншого сайту WebDoky.

HTML

<iframe
  src="https://example.org"
  title="Приклад iframe 1"
  width="400"
  height="300">
</iframe>

Результат

Вбудовування в <iframe> вихідного коду

Цей приклад безпосередньо візуалізує вихідний код у супутньому фреймі. Якщо поєднати з атрибутом sandbox, то це можна використовувати як техніку для запобігання ін'єкціям сценаріїв під час виведення вмісту, створеного користувачами.

Зверніть увагу на те, що за використання srcdoc будь-які відносні URL у вбудованому вмісті розв'язуються відносно URL вбудованої сторінки. Якщо потрібно використати якірні посилання, що вказують на місця у вбудованому вмісті, необхідно явно задати about:srcdoc як базовий URL.

HTML

<article>
  <footer>Дев'ять хвилин тому <i>jc</i> написав:</footer>
  <iframe
    sandbox
    srcdoc="<p>Є два способи використання елемента <code>iframe</code>:</p>
<ol>
<li><a href=&quot;about:srcdoc#embed_another&quot;>Для вбудовування вмісту з іншої сторінки</a></li>
<li><a href=&quot;about:srcdoc#embed_user&quot;>Для вбудовування вмісту, створеного користувачами</a></li>
</ol>
<h2 id=&quot;embed_another&quot;>Вбудовування вмісту з іншої сторінки</h2>
<p>Скористайтеся атрибутом <code>src</code>, щоб задати URL сторінки для вбудування:</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;>Вбудовування вмісту, створеного користувачами</h2>
Скористайтеся атрибутом <code>srcdoc</code>, щоб задати вміст для вбудовування. Цей допис сам є прикладом цього!
"
    width="500"
    height="250"
></iframe>
</article>

Ось як записувати при використанні srcdoc послідовності екранування:

• По-перше, випишіть HTML, екрануючи все, що екранувалося б у звичайному документі HTML (наприклад, <, >, & тощо).
• < і < в атрибуті srcdoc представляють один і той же символ. Тому, щоб зробити таку послідовність справжньою послідовністю екранування в документі HTML, замініть усі амперсанди (&) на &. Наприклад, < стане <, а & – &.
• Замініть подвійні лапки (") на ", щоб не дати атрибуту srcdoc зарано завершитися (якщо замість подвійних лапок використовувати ', то слід замінити ' на '). Цей крок відбувається після попереднього, тож ", що з'являється на цьому кроці, не стане ".

Результат

Технічний підсумок

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

Сумісність із браузерами

Дивіться також

• CSP – frame-ancestors
• Приватність, дозволи та захист інформації