<iframe>: Element ramki iframe

Element ramki Iframe HTML (<iframe>) reprezentuje zagnieżdżony browsing context poprzez osadzanie innej strony HTML w aktualnej.

Każdy osadzony, przeglądarkowy kontekst posiada własną historię sesji i interfejs document. Kontekst przeglądarkowy, który umożliwia osadzanie innych stron nazywany jest przeglądarkowym kontekstem-rodzicem (parent browsing context). Najwyższy kontekst przeglądarki — nieposiadający rodzica — to przeważnie okno przeglądarki reprezentowane przez objekt Window.

Ponieważ każdy kontekt przeglądarkowy jest kompletnym środowiskiem dokumentu, każdy <iframe> na stronie wymaga zwiększenia pamięci i innych zasobów komputera. Teoretycznie możesz używać tyle <iframe>ów, ile sobie zamarzysz - sprawdź jednak, czy nie występują problemy z wydajnością.

Kategorie kontentu Treści płynne (flow content), treści frazujące (phrasing content), treści osadzone, treści interaktywne, treści namacalne (palpable content).
Dozwolone treści Brak.
Pominięcie tagu None, both the starting and ending tag are mandatory.
Dozwoleni rodzice Każdy element, który akceptuje treści osadzone.
Dozwolone role ARIA application, document, img
Interfejs DOM HTMLIFrameElement

Atrybuty

Ten element zawiera atrybuty globalne.

allow
Określa reguły funkcji dla <iframe>.
allowfullscreen
Ustawiony na true, jeśli <iframe>może aktywować tryb na pełen ekran poprzez wywołanie metody requestFullscreen().
Ten atrybut jest uznawany za przestarzały i przedefiniowany na allow="fullscreen".
allowpaymentrequest
Ustawiony na true, jeśli cross-originowy <iframe> powinien być dopuszczony do wywoływania Żądania Płatności (Payment Request) API.
Ten atrybut jest uznawany za przestarzały i przedefiniowany na allow="payment".
csp
Content Security Policy wymuszone dla zasobów osadzonych. Po więcej informacji sprawdź HTMLIFrameElement.csp.
height
Wysokość ramki w pikselach CSS. Domyślna wartość to 150.
importance
Priorytet pobierania źródła w <iframe>'owym atrybucie src. Dopuszczone wartości:
auto (domyślna)
Bez preferencji. Przeglądarka używa własnych heurytystyk do decydowania o pierwszeństwie zasobu.
high
Zasób powinien zostać pobrany przed innymi zasobami stron o niższym priorytecie.
low
Zasób powinien zostać pobrany po innych zasobach stron o wyższym priorytecie.
loading
Wskazuje, jak przeglądarka powinna ładować iframe:
  • eager: Załaduj iframe niezwłocznie, niezależnie czy jest poza widocznym oknem podglądu (jest to wartość domyślna).
  • lazy: Wstrzymaj ładowanie iframe póki nie osiągnie obliczonej odległości od okna podglądu, zgodnie z definicją przeglądarki.
name
Docelowa nazwa dla osadzonego kontektu przeglądarkowego. Może być używana w atrybucie target elementów <a>, <form> czy <base>; atrybut formtarget elementów <input> lub <button>; czy parametr windowName w metodzie window.open().
referrerpolicy
Wskazuje, którego polecającego wysłać podczas przechwytywania zasobów ramki:
  • no-referrer: Nagłówek Referer nie zostanie wysłany.
  • no-referrer-when-downgrade (domyślny): Nagłówek Referer nie zostanie wysłany do originów bez TLS (HTTPS).
  • origin: Wysłany polecający zostanie ograniczony do originu strony odsyłającej: jej schematu, hostu, i portu.
  • origin-when-cross-origin: Polecający wysłany do innych originów zostanie ograniczony do schematu, hostu i portu. Nawigacje o tym samym originie będą nadal zawierać ścieżkę.
  • same-origin: Polecający zostanie wysłany przy same origin, ale żądania cross-origin nie będą zawierać informacji polecającego.
  • strict-origin: Wyśle origin dokumentu jako polecający tylko, gdy poziom bezpieczeństwa protokołu jest ten sam (HTTPS→HTTPS), nie wyśle do miejsca docelowego, jeśli jest mniej bezpieczne (HTTPS→HTTP).
  • strict-origin-when-cross-origin: Wyśle pełen URL w przypadku żądania same-origin, wyśle origin tylko, jeśli poziom bezpieczeństwa protokołu jest ten sam (HTTPS→HTTPS) i nie wyśle nagłówka, jeśli miejsce docelowe jest mniej bezpieczne (HTTPS→HTTP).
  • unsafe-url: Polecający będzie zawierać origin oraz ścieżkę (ale nie fragmentu, hasła czy nazwy użytkownika). Ta wartość nie jest bezpieczna, ponieważ pozwala na wyciek originów i ścieżek z zasobów chronionych TLS do originów niebezpiecznych.
sandbox
Stosuje dodatkowe restrykcje wobec treści ramce. Wartość atrybutu może pozostać pusta (obowiązywać będą wszystkie restrykcje) lub tokeny odseprowane spacją, aby wymusić określone restrykcje:
  • allow-downloads-without-user-activation : Zezwala na pobieranie bez zatwierdzenie przez użytkownika.
  • allow-forms: Zezwala zasobom na zatwierdzanie formularzy. Jeśli niniejsze słowo kluczowe nie zostaje użyte, zatwierdzanie formularzy jest zablokowane.
  • allow-modals: Pozwala zasobom na otwieranie okienek modalnych.
  • allow-orientation-lock: Pozwala zasobom na zablokowanie orientacji wyświetlacza.
  • allow-pointer-lock: Pozwala zasobom na używanie Pointer Lock API.
  • allow-popups: Pozwala na wyskakujące okienka/otwieranie kart (jak np. window.open(), target="_blank" czy showModalDialog()). Jeśli niniejsze słowo kluczowe nie zostaje użyte, popupy nie zostaną otwarte.
  • allow-popups-to-escape-sandbox: Pozwala dokumentowi w piaskownicy (sandbox) na otwieranie nowych okien bez dziedziczenia przez nie sandboxingu. Dzięki temu możliwe jest np. sandboxowanie reklamy bez wymuszania tej samej restrykcji na stronie, do której prowadzi link z tej reklamy.
  • allow-presentation: Pozwala zasobom uruchomić sesję prezentacji.
  • allow-same-origin: Jeśli ten token nie jest użyty, zasób jest traktowany jako pochodzący ze specjalnego źródła, które nie spełnia wymogów same-origin policy.
  • allow-scripts: Pozwala zasobom na uruchomienie skryptów (ale nie na tworzenie wyskakujących okienek).
  • allow-storage-access-by-user-activation : Pozwala zasobom na żądanie dostępu do pamięci masowej rodzica poprzez Storage Access API.
  • allow-top-navigation: Pozwala zasobom na nawigację kontekstu najwyższego poziomu przeglądarki (_top).
  • allow-top-navigation-by-user-activation: Pozwala zasobom na nawigację kontekstu najwyższego poziomu przeglądarki, ale jedynie gdy akcja zainicjowana jest przez gest użytkownika.
Notka o sandboxingu:
  • Jeśli dokument osadzony jest tego samego pochodzenia, jak strona osadzająca mocno odradza się używania allow-scripts i allow-same-origin, ponieważ pozwala to osadzonemu dokumentowi na usunięcie atrybutu sandbox, sprawiając tym samym, że jest on tak samo niezabezpieczony, jak dokument nie używający w ogóle atrybutu sandbox.
  • Sandboxing jest bezużyteczny, jeśli atakujący może wyświetlać zawartość poza sandboxowanym iframe — np. jeśli przeglądarka otwiera ramkę na nowej karcie. Tego typu treść musi zatem być dostarczana z oddzielnego źródła, aby ograniczyć zasięg potencjalnych szkód.
  • Atrybut sandbox nie jest wspierany w Internet Explorer 9 i wcześniejszych wersjach.
src
URL strony do osadzenia. Użyj wartości about:blank do osadzenia pustej strony, co jest zgodne z polityką same-origin. Wiedz, że programowo usuwanie atrybutu src <iframe>'u (np. poprzez Element.removeAttribute()) powoduje załadowanie about:blank w ramce w Firefoxie (from version 65), przeglądarkach na Chromium i Safari/iOS.
srcdoc
Osadzenie treści HTML poprzed nadpisanie atrybutu src. Jeśli przeglądarka nie wspiera atrybutu srcdoc, odwoła się do URL z atrybutu src.
width
Szerokość ramki w pikselach CSS. Domyślna wartość to 300.

Nieużywane atrybuty

Poniższe atrybuty są przestarzałe i mogą nie być już dłużej wspierane przez przeglądarki użytkowników. Nie powinno się ich używać przy tworzeniu nowych treści oraz powinno się możliwie usuwać z już istniejących treści.

align Wycofywany HTML4.01, Przestarzały HTML5
Wyrównanie elementu z uwzględnieniem kontekstu.
frameborder Przestarzały HTML5
Wartość 1 (domyślna) rysuje krawędź wokół tej ramki. Wartość 0 usuwa krawędź wokół tej ramki, ale zamiast tego rozwiązania do kontroli krawędzi <iframe> powinno się używać własności CSS border.
longdesc Przestarzały HTML5
URL długiego opisu zawartości ramki. Z powodu częstego nadużywania nie jest przydatny w przypadku przeglądarek niewizualnych.
marginheight Przestarzały HTML5
Rozmiar obszaru mierzony w pikselach pomiędzy zawartością ramki oraz jej górną i dolną krawędzią.
marginwidth Przestarzały HTML5
Rozmiar obszaru mierzony w pikselach pomiędzy zawartością ramki oraz jej lewą i prawą krawędzią.
scrolling Przestarzały HTML5
Wskazuje, kiedy przeglądarka powinna zapewnić pasek przewijania dla ramki:
  • auto: Tylko, jeśli zawartość ramki jest większa niż jej wymiary.
  • yes: Zawsze pokazuj pasek przewijania.
  • no: Nigdy nie pokazuj paska przewijania.

Atrybuty niestandardowe

mozbrowser
Sprawdź podatności błąd 1318532 WebExtensions w Firefox.
Sprawia, że <iframe> zachowuje się jak okienko najwyższego poziomu przeglądarki. Sprawdź Browser API by dowiedzieć się więcej informacji.
Dostępne tylko dla WebExtensions.

Skrypty

Ramki, jak elementy <frame> znajdują się w pseudo-tablicy window.frames.

Poprzez obiekt DOM HTMLIFrameElement, skrypty zyskują dostęp do obiektu window zasobu w ramce poprzez własność contentWindow. Własność contentDocument odnosi się do document wewnątrz <iframe>, podobnie jak contentWindow.document.

Z wnętrzna ramki skrypt może uzyskać odsyłacz do jej okna-rodzica poprzez window.parent.

Dostęp skryptu do treści ramki stanowi temat same-origin policy. Skrypty nie mogą uzyskiwać dostępu do większości własności w innych obiektach window, jeśli skrypt został załadowany z innego źródła, w tym skrypty wewnątrz ramki mające dostęp do rodzica ramki. Komunikacja cross-origin może być osiągnięta poprzez użycie Window.postMessage().

Pozycjonowanie i skalowanie

Jako element zastąpiony, pozycjonowanie, wyrównywanie i skalowanie osadzonego dokumentu wewnątrz okna elementu <iframe> może być określane poprzez właściwości object-position oraz object-fit.

Przykłady

Prosty <iframe>

<iframe> w akcji. Po utworzeniu ramki, kiedy użytkownik klika na przycisk jego tytuł jest wyświetlany w alercie.

HTML

<iframe src="https://mdn-samples.mozilla.org/snippets/html/iframe-simple-contents.html" title="iframe Example 1" width="400" height="300"></iframe>

Rezultat

Otwórz link w <iframe> w innej karcie

W niniejszym przykładzie mapa Google jest wyświetlana w ramce;

HTML

<iframe id="Example2"
    title="iframe Example 2"
    width="400" height="300"
    style="border:none"
    src="https://maps.google.com/maps?f=q&source=s_q&q=buenos+aires&sll=37.0625,-95.677068&sspn=38.638819,80.859375&t=h&hnear=Buenos+Aires,+Argentina&z=11&ll=-34.603723,-58.381593&output=embed">
</iframe>

Rezultat

Obawy dot. dostępności

Osoby poruszające się poprzez technologię wspierającą, jak czytniki ekranowe mogą używać atrybutu title na iframe'ie do oznaczania jego treści. Wartość tytułu powinna w zwięzły sposób opisywać osadzoną treść:

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

Jeśli tytuł nie został określony, wspomniane osoby mogą wchodzić wewnątrz iframe, żeby dowiedzieć się czym dokładniej jest osadzona zawartość. Tego typu zmiana kontekstu może prowadzić do nieporozumień i niepotrzebnie zabierać czas, szczególnie w przypadku stron o wielu <iframe>'ach i/lub jeśli treść osadzona zawiera interaktywne zasoby, jak video czy audio.

Specyfikacje

Specyfikacja Status Komentarz
Referrer Policy
The definition of 'referrerpolicy attribute' in that specification.
Candidate Recommendation Dodano atrybut referrerpolicy.
HTML Living Standard
The definition of '<iframe>' in that specification.
Living Standard
HTML5
The definition of '<iframe>' in that specification.
Recommendation
HTML 4.01 Specification
The definition of '<iframe>' in that specification.
Recommendation
Screen Orientation API Working Draft Dodaje allow-orientation-lock do atrybutu sandbox.
Presentation API
The definition of 'allow-presentation' in that specification.
Candidate Recommendation Dodaje allow-presentation do atrybutu sandbox

Zgodność z przeglądarkami

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
iframeChrome Full support 1Edge Full support YesFirefox Full support Yes
Notes
Full support Yes
Notes
Notes The resize CSS property doesn't have any effect on this element due to bug 680823.
IE Full support YesOpera Full support YesSafari Full support Yes
Notes
Full support Yes
Notes
Notes Safari has a bug that prevents iframes from loading if the iframe element was hidden when added to the page. iframeElement.src = iframeElement.src should cause it to load the iframe.
WebView Android Full support YesChrome Android Full support YesFirefox Android Full support Yes
Notes
Full support Yes
Notes
Notes The resize CSS property doesn't have any effect on this element due to bug 680823.
Opera Android Full support YesSafari iOS Full support Yes
Notes
Full support Yes
Notes
Notes Safari has a bug that prevents iframes from loading if the iframe element was hidden when added to the page. iframeElement.src = iframeElement.src should cause it to load the iframe.
Samsung Internet Android Full support Yes
align
Deprecated
Chrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
allow
Experimental
Chrome Full support 60Edge No support NoFirefox No support NoIE No support NoOpera Full support 47Safari Full support 11.1WebView Android Full support 60Chrome Android Full support 60Firefox Android No support NoOpera Android Full support 44Safari iOS Full support 11.3Samsung Internet Android Full support 8.0
allowfullscreenChrome Full support 27
Full support 27
Full support 17
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Edge Full support YesFirefox Full support 18
Full support 18
Full support 9
Prefixed
Prefixed Implemented with the vendor prefix: moz
IE Full support 11
Prefixed
Full support 11
Prefixed
Prefixed Implemented with the vendor prefix: ms
Opera Full support YesSafari Full support 7
Full support 7
Full support Yes
Prefixed
Prefixed Implemented with the vendor prefix: webkit
WebView Android Full support 37
Full support 37
Full support 37
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Chrome Android Full support 27
Full support 27
Full support 18
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Firefox Android Full support 18
Full support 18
Full support 9
Prefixed
Prefixed Implemented with the vendor prefix: moz
Opera Android Full support YesSafari iOS Full support 7
Full support 7
Full support Yes
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Samsung Internet Android Full support 1.5
Full support 1.5
Full support 1.0
Prefixed
Prefixed Implemented with the vendor prefix: webkit
allowpaymentrequest
Experimental
Chrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
External protocol URLs blocked
Deprecated
Chrome ? Edge ? Firefox Full support 67IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Firefox Android Full support 67Opera Android ? Safari iOS ? Samsung Internet Android ?
frameborder
Deprecated
Chrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
heightChrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
longdesc
Deprecated
Chrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
marginheight
Deprecated
Chrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
marginwidth
Deprecated
Chrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
mozbrowser
Non-standard
Chrome No support NoEdge No support NoFirefox No support No
Notes
No support No
Notes
Notes See bug 1318532
Notes Available only to WebExtensions.
IE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support No
Notes
No support No
Notes
Notes See bug 1318532
Notes Available only to WebExtensions.
Opera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
nameChrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
referrerpolicyChrome Full support 51Edge No support NoFirefox Full support 50IE No support NoOpera Full support 38Safari Full support 11.1WebView Android Full support 51Chrome Android Full support 51Firefox Android Full support 50Opera Android Full support 41Safari iOS No support NoSamsung Internet Android Full support 7.2
sandboxChrome Full support 4Edge Full support YesFirefox Full support 17IE Full support 10Opera Full support 15Safari Full support 5WebView Android Full support YesChrome Android Full support YesFirefox Android Full support 17Opera Android ? Safari iOS Full support 4.2Samsung Internet Android Full support Yes
sandbox="allow-modals"Chrome ? Edge No support NoFirefox Full support 49IE No support NoOpera ? Safari ? WebView Android ? Chrome Android ? Firefox Android Full support 49Opera Android ? Safari iOS ? Samsung Internet Android ?
sandbox="allow-popups"Chrome Full support YesEdge Full support YesFirefox Full support 28IE ? Opera Full support YesSafari ? WebView Android Full support YesChrome Android Full support YesFirefox Android Full support 27Opera Android ? Safari iOS ? Samsung Internet Android Full support Yes
sandbox="allow-popups-to-escape-sandbox"Chrome Full support 46Edge No support NoFirefox Full support 49IE No support NoOpera Full support 32Safari ? WebView Android Full support 46Chrome Android Full support 46Firefox Android Full support 49Opera Android Full support 32Safari iOS ? Samsung Internet Android Full support 5.0
sandbox="allow-presentation"Chrome Full support 53Edge No support NoFirefox Full support 50IE No support NoOpera Full support 40Safari ? WebView Android No support NoChrome Android Full support 53Firefox Android Full support 50Opera Android Full support 41Safari iOS ? Samsung Internet Android Full support 6.0
sandbox="allow-storage-access-by-user-activation"
ExperimentalNon-standard
Chrome No support NoEdge No support NoFirefox Full support 65
Disabled
Full support 65
Disabled
Disabled From version 65: this feature is behind the dom.storage_access.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera No support NoSafari Full support 11.1WebView Android No support NoChrome Android No support NoFirefox Android Full support 65
Disabled
Full support 65
Disabled
Disabled From version 65: this feature is behind the dom.storage_access.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android No support NoSafari iOS Full support 11.3Samsung Internet Android No support No
sandbox="allow-top-navigation-by-user-activation"Chrome Full support 58Edge No support NoFirefox No support NoIE No support NoOpera Full support 45Safari Full support 11.1
Notes
Full support 11.1
Notes
Notes Not initially available in 11.1, but added in sub-version 13605.1.33.1.2.
WebView Android Full support 58Chrome Android Full support 58Firefox Android No support NoOpera Android Full support 43Safari iOS ? Samsung Internet Android Full support 7.0
scrolling
Deprecated
Chrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
srcChrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
srcdocChrome Full support 20Edge No support NoFirefox Full support 25IE No support NoOpera Full support 15Safari Full support 6WebView Android Full support 37Chrome Android Full support 25Firefox Android Full support 25Opera Android ? Safari iOS ? Samsung Internet Android Full support 1.5
widthChrome Full support 1Edge Full support YesFirefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
Experimental. Expect behavior to change in the future.
Experimental. Expect behavior to change in the future.
Non-standard. Expect poor cross-browser support.
Non-standard. Expect poor cross-browser support.
Deprecated. Not for use in new websites.
Deprecated. Not for use in new websites.
See implementation notes.
See implementation notes.
User must explicitly enable this feature.
User must explicitly enable this feature.
Requires a vendor prefix or different name for use.
Requires a vendor prefix or different name for use.