Dokumentacja HTML z przykładami: Znacznik iframe

Q: Dlaczego mój iframe pokazuje, że strona odmówiła połączenia?

Strona wysyła nagłówek X-Frame-Options lub Content-Security-Policy: frame-ancestors, który zabrania innym stronom osadzania jej w ramce. Wiele stron robi tak, żeby zapobiec clickjackingowi. Nie da się tego obejść z twojej strony; użyj oficjalnego adresu do osadzania, jeśli strona go ma.

Q: Jak usunąć ramkę z iframe?

Ustaw border: 0 w CSS. Stary atrybut frameborder="0" jest przestarzały, choć wiele kopiowanych kodów do osadzania nadal go zawiera.

Q: Jak zrobić responsywny iframe?

Nadaj mu width: 100% i aspect-ratio w CSS, na przykład aspect-ratio: 16 / 9 dla wideo, i pomiń stałą wysokość. Iframe skaluje się wtedy razem z kontenerem i zachowuje proporcje.

Q: Do czego służy atrybut sandbox w iframe?

Pusty atrybut sandbox blokuje w ramce skrypty, wysyłanie formularzy, wyskakujące okna i nie tylko, a jej treść traktuje jako pochodzącą z unikalnego źródła. Potem zezwalasz tylko na to, czego potrzebuje osadzona treść, słowami kluczowymi takimi jak allow-scripts czy allow-forms.

Jak używać iframe

<iframe> wyświetla inną stronę wewnątrz twojej. Podaj adres strony w src, opisujący ją title i rozmiar:

<iframe src="https://example.com/" title="Example site" width="600" height="400"></iframe>

Ramka wczytuje stronę jako osobny dokument, z własnymi stylami i skryptami. Przykłady na tej stronie używają srcdoc zamiast src, co umieszcza HTML ramki bezpośrednio w atrybucie, więc działają bez wczytywania innej strony:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>iframe</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    p { color: #2563eb; font-weight: 600; }
  </style>
</head>
<body>
  <p>This paragraph is in the outer page.</p>
  <iframe title="Inner page" width="320" height="120"
    srcdoc="<h1 style='font: 20px system-ui'>Hello from inside the frame</h1><p>The outer page's CSS does not reach me.</p>">
  </iframe>
</body>
</html>

Zewnętrzny akapit jest niebieski i pogrubiony; akapit w ramce nie jest, choć na stronie działa ta sama reguła p. Style nigdy nie przekraczają granicy ramki, w żadną stronę. Domyślna ramka i domyślny rozmiar 300×150 pochodzą od przeglądarki; atrybuty width i height nadpisują rozmiar.

Osadzanie filmu z YouTube lub mapy

Serwisy z filmami i mapami dają gotowy kod iframe. Na YouTube naciśnij Udostępnij, a potem Umieść:

<iframe width="560" height="315"
  src="https://www.youtube.com/embed/VIDEO_ID"
  title="YouTube video player"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowfullscreen></iframe>

W Mapach Google otwórz miejsce, naciśnij Udostępnij, potem Umieść mapę i tak samo skopiuj iframe. Zachowaj title (czytniki ekranu ogłaszają go przy wejściu do ramki) i zastąp stałe rozmiary responsywnym CSS opisanym niżej. Atrybut allow daje ramce funkcje takie jak autoodtwarzanie czy pełny ekran, które dla osadzonych stron są domyślnie wyłączone.

Rozmiar, ramka i responsywny iframe

Kopiowane kody do osadzania używają stałych rozmiarów w pikselach, które na telefonach wychodzą poza ekran. width: 100% plus aspect-ratio sprawia, że ramka wypełnia kontener i zachowuje proporcje, a border: 0 usuwa domyślną wklęsłą ramkę:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Responsive iframe</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    .embed {
      width: 100%;
      aspect-ratio: 16 / 9;
      border: 0;
      border-radius: 8px;
      background: #111827;
    }
    .wrap { max-width: 480px; }
  </style>
</head>
<body>
  <div class="wrap">
    <iframe class="embed" title="Video placeholder"
      srcdoc="<body style='margin:0;height:100vh;display:grid;place-items:center;color:#fff;font:16px system-ui'>16:9 frame">
    </iframe>
  </div>
</body>
</html>

Zmień max-width: 480px na inną wartość, a ramka zachowa proporcje 16:9 przy każdej szerokości. Usuń border: 0, żeby zobaczyć domyślną ramkę przeglądarki. Stare atrybuty frameborder, scrolling i marginheight są przestarzałe; używaj CSS.

sandbox: ograniczanie możliwości ramki

Ramka może uruchamiać skrypty, wysyłać formularze i otwierać wyskakujące okna jak każda strona. Atrybut sandbox odbiera jej te możliwości; pusty sandbox blokuje prawie wszystko, a każde słowo kluczowe przywraca jedną z nich. Obie ramki poniżej dostają ten sam HTML z małym skryptem:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>sandbox</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    iframe { width: 240px; height: 70px; border: 2px solid #e5e7eb; border-radius: 6px; }
    code { display: block; margin: 8px 0 4px; }
  </style>
</head>
<body>
  <code>sandbox=""</code>
  <iframe id="a" sandbox="" title="Sandboxed frame"></iframe>
  <code>sandbox="allow-scripts"</code>
  <iframe id="b" sandbox="allow-scripts" title="Frame with scripts allowed"></iframe>
  <script>
    const html = '<p id="s" style="font: 15px system-ui">Scripts are blocked</p>' +
      '<script>document.getElementById("s").textContent = "JavaScript ran";<\/script>';
    document.getElementById('a').srcdoc = html;
    document.getElementById('b').srcdoc = html;
  </script>
</body>
</html>

Pierwsza ramka zachowuje tekst zastępczy, bo jej skrypt nigdy się nie uruchamia (konsola Chrome zapisuje dla niej komunikat "Blocked script execution"). Używaj sandbox zawsze, gdy osadzasz treść, której nie ufasz w pełni, np. HTML napisany przez użytkowników, i dodawaj tylko potrzebne słowa kluczowe:

Słowo kluczowe	Pozwala na
`allow-scripts`	Uruchamianie JavaScriptu
`allow-forms`	Wysyłanie formularzy
`allow-popups`	`window.open` i linki `target="_blank"`
`allow-modals`	`alert()`, `confirm()` i `prompt()`
`allow-same-origin`	Traktowanie treści jako pochodzącej z jej prawdziwego źródła (ciasteczka, pamięć)
`allow-top-navigation`	Przeniesienie całej karty z twojej strony gdzie indziej

Nigdy nie łącz allow-scripts z allow-same-origin dla treści z własnego źródła: osadzony skrypt mógłby wtedy usunąć własny sandbox.

Komunikacja z ramką: postMessage

Zewnętrzna strona i ramka to osobne dokumenty. Gdy ich źródła się różnią, nie mogą dotykać nawzajem swojego DOM, ale mogą wysyłać wiadomości. Wpisz wiadomość i wyślij ją do ramki:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>postMessage</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    iframe { display: block; width: 280px; height: 80px; margin-top: 10px; border: 2px solid #2563eb; border-radius: 6px; }
  </style>
</head>
<body>
  <input id="msg" value="Hello, frame">
  <button id="send">Send</button>
  <iframe id="frame" title="Message receiver" srcdoc="
    <p style='font: 15px system-ui' id='got'>Waiting for a message</p>
    <script>
      addEventListener('message', (e) => {
        document.getElementById('got').textContent = 'Received: ' + e.data;
      });
    </script>">
  </iframe>
  <script>
    document.getElementById('send').onclick = () => {
      const frame = document.getElementById('frame');
      frame.contentWindow.postMessage(document.getElementById('msg').value, '*');
    };
  </script>
</body>
</html>

W prawdziwym kodzie podawaj dokładne źródło ramki (np. 'https://maps.example.com') zamiast '*' i sprawdzaj e.origin po stronie odbiorcy, żeby wiadomości trafiały tylko do oczekiwanej strony i tylko od niej pochodziły.

Wydajność i strony, które odmawiają

Leniwe wczytywanie. Dodaj loading="lazy" do ramek daleko w dół strony; przeglądarka wczyta je dopiero, gdy czytelnik się do nich zbliży. Każdy iframe to pełne wczytanie strony, więc strona z wieloma osadzeniami bez tego zwalnia.
"Odmowa połączenia". Wiele stron (banki, większość sieci społecznościowych, wyszukiwarka Google) wysyła nagłówek X-Frame-Options lub frame-ancestors, który zabrania osadzania, a przeglądarka pokazuje w ramce błąd. Twoja strona nie może tego obejść. Użyj oficjalnego adresu do osadzania albo linku.
Dostępność. Zawsze ustawiaj title. Dzięki niemu czytnik ekranu nazywa ramkę, a po stronie z kilkoma ramkami bez tytułów trudno się poruszać.

Częste błędy

Brak title. Czytniki ekranu ogłaszają ramkę jako nienazwaną.
Stałe szerokości ze skopiowanego kodu. Zastąp je przez width: 100% i aspect-ratio.
Osadzanie zwykłego pliku wideo w ramce. Dla własnego pliku .mp4 użyj elementu video; iframe służy do stron.
Ufanie osadzonej treści. Dodaj sandbox do wszystkiego, czego nie piszesz samodzielnie.
Oczekiwanie, że zewnętrzny CSS wystylizuje ramkę. Stylizuj osadzoną stronę od środka.

Najczęściej zadawane pytania

Czym jest iframe w HTML?

<iframe> (inline frame, czyli ramka wewnętrzna) to pudełko, które wyświetla osobną stronę internetową w bieżącej. Ma własny dokument, style i skrypty, dlatego używa się go do osadzania filmów, map, reklam i podglądów kodu.

Jak osadzić film z YouTube przez iframe?

Na YouTube wybierz Udostępnij, potem Umieść i skopiuj kod. To iframe, którego src to https://www.youtube.com/embed/ plus identyfikator filmu. Zachowaj atrybuty title i allowfullscreen, a responsywność zapewnij w CSS przez aspect-ratio: 16 / 9 z width: 100%.

Dlaczego mój iframe pokazuje, że strona odmówiła połączenia?

Strona wysyła nagłówek X-Frame-Options lub Content-Security-Policy: frame-ancestors, który zabrania innym stronom osadzania jej w ramce. Wiele stron robi tak, żeby zapobiec clickjackingowi. Nie da się tego obejść z twojej strony; użyj oficjalnego adresu do osadzania, jeśli strona go ma.

Jak usunąć ramkę z iframe?

Ustaw border: 0 w CSS. Stary atrybut frameborder="0" jest przestarzały, choć wiele kopiowanych kodów do osadzania nadal go zawiera.

Jak zrobić responsywny iframe?

Nadaj mu width: 100% i aspect-ratio w CSS, na przykład aspect-ratio: 16 / 9 dla wideo, i pomiń stałą wysokość. Iframe skaluje się wtedy razem z kontenerem i zachowuje proporcje.

Do czego służy atrybut sandbox w iframe?

Pusty atrybut sandbox blokuje w ramce skrypty, wysyłanie formularzy, wyskakujące okna i nie tylko, a jej treść traktuje jako pochodzącą z unikalnego źródła. Potem zezwalasz tylko na to, czego potrzebuje osadzona treść, słowami kluczowymi takimi jak allow-scripts czy allow-forms.

Powiązane zagadnienia