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

{{HTMLSidebar}}

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

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

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

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

Атрибути

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

allow

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

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

allowfullscreen

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

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

allowpaymentrequest

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

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

credentialless

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

csp

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

height

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

loading

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

• eager: Завантажувати супутній фрейм негайно, незалежно від того, чи лежить він поза видимою областю перегляду (усталене значення).
• lazy: Відкласти завантаження супутнього фрейму до часу, коли він досягне обчисленої відстані від області перегляду, як задано браузером.

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

Накладає на вміст фрейму додаткові обмеження. Значення атрибута може бути або порожнім, щоб застосувати всі обмеження, або розділеними пробілами позначками для зняття певних обмежень:

• allow-downloads: Дозволяє стягнення файлів за допомогою елементів <a> та <area> з атрибутом download, а також переходу, що приводить до стягування файлу. Це працює незалежно від того, чи клацнув користувач посилання, чи це запустив код на JS, без дій користувача.

• allow-downloads-without-user-activation : Дозволяє завантаженням відбуватися без рухів з боку користувача.

• 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: Дозволяє огородженому документові відкривати нові вікна без накладання на них позначок огородження. Це дозволяє, наприклад, сторонньому рекламному оголошенню бути безпечно огородженим, не накладаючи такі самі обмеження на сторінки, на котрі воно посилається.

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

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

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

• allow-storage-access-by-user-activation : Дає ресурсові запитувати доступ до можливостей сховища батьківського контексту за допомогою API доступу до сховища.

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

src

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

srcdoc

Супутній HTML для вбудовування, що відкидає атрибут src. Якщо браузер не підтримує атрибут srcdoc, то скористається URL в атрибуті src.

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 та object-fit.

Приклади

Простий <iframe>

Цей приклад вбудовує сторінку https://example.org в супутній фрейм.

HTML

<iframe
  src="https://example.org"
  title="Приклад iframe 1"
  width="400"
  height="300">
</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> чи коли вбудований інтерактивний вміст, як то відео чи аудіо.

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

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

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

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

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