<iframe>: Element ramki iframe

Element ramki Iframe HTML (<iframe>) reprezentuje zagnieżdżony browsing context (en-US) 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() (en-US).
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 (en-US).
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> (en-US) czy <base>; atrybut formtarget elementów <input> (en-US) lub <button> (en-US); 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 (en-US) nie zostanie wysłany.
  • no-referrer-when-downgrade (domyślny): Nagłówek Referer (en-US) nie zostanie wysłany do origin (en-US)ów bez TLS (en-US) (HTTPS (en-US)).
  • origin: Wysłany polecający zostanie ograniczony do originu strony odsyłającej: jej schematu, host (en-US)u, i port (en-US)u.
  • 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 (en-US), 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 (en-US).
  • 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> (en-US) 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 (en-US). Własność contentDocument (en-US) 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 (en-US).

Dostęp skryptu do treści ramki stanowi temat same-origin policy (en-US). 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() (en-US).

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 (en-US) oraz object-fit (en-US).

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

BCD tables only load in the browser