HTML iframe Etiketi: sandbox, allow, srcdoc, loading ve Güvenlik

iframe nedir, ne zaman kullanılır?

MDN <iframe>'ı iç içe bir tarama bağlamı (nested browsing context) olarak tanımlar. Her gömülü bağlamın kendi belgesi vardır ve kendi içinde adres gezintisi yapabilir; bu gezintiler en üstteki tarama bağlamının oturum geçmişine eklenir. Diğerlerini gömen bağlama üst (parent) bağlam, hiç üst bağlamı olmayan en üstteki bağlama da genellikle tarayıcı penceresi denir. Harita, video oynatıcı, ödeme formu ya da başka bir sitenin widget'ı gibi başka bir kaynaktan gelen tam bir sayfayı göstermek tipik kullanımlardır.

Temel kullanım ve title

<iframe
  src="https://example.org"
  title="Örnek alan adının ana sayfası"
  width="400"
  height="300">
</iframe>

width ve height çerçevenin boyutunu CSS pikseli cinsinden verir; yazılmazsa varsayılan genişlik 300, yükseklik 150'dir. CSS ile verilen genişlik HTML özniteliğinin önüne geçer. <iframe>'ın izin verilen içeriği "yok"tur: açılış ve kapanış etiketleri zorunludur ama aralarına yedek metin yazmak geçerli değildir. Bu, <video> ya da <object> öğelerinden önemli bir farktır.

title özniteliği çerçevenin içeriğini yardımcı teknolojilere tanıtır. MDN, başlık olmadığında ekran okuyucu kullananların neyin gömüldüğünü anlamak için çerçevenin içine girmek zorunda kaldığını, bunun özellikle birden fazla çerçeve olan ya da video ve ses gibi etkileşimli içerik gömülen sayfalarda kafa karıştırıcı ve zaman alıcı olduğunu belirtir. Başlık kısa ve içeriği tarif eden bir metin olmalıdır: "iframe" ya da "çerçeve 1" değil, "Ankara şubesinin konumunu gösteren harita" gibi. Erişilebilir ad konusunu erişilebilir ad yazısında genel olarak ele aldık.

sandbox: gömülen içeriği kısıtlamak

sandbox özniteliği gömülen içeriğe uygulanan kısıtlamaları yönetir. Değeri boş bırakırsanız tüm kısıtlamalar uygulanır; boşlukla ayrılmış belirteçler yazarak belirli kısıtlamaları tek tek kaldırırsınız. Mantık "varsayılan olarak kapalı, istediğini aç" şeklindedir.

Bu listeye ek olarak allow-storage-access-by-user-activation belirteci, çerçevedeki belgenin Storage Access API ile bölümlenmemiş çerezlere erişim istemesine izin verir. allow-same-origin ile ilgili MDN bir ayrıntının altını çizer: bu belirteç varken aynı kökendeki üst belge, allow-scripts olmasa bile çerçevenin DOM'una erişip onunla etkileşebilir; allow-scripts yalnızca çerçevenin içinde betik çalışıp çalışmayacağını belirler.

<!-- Üçüncü taraf bir anket widget'ı: betik ve form çalışsın, başka hiçbir şey açılmasın -->
<iframe
  src="https://anket.example.net/form/42"
  title="Müşteri memnuniyeti anketi"
  sandbox="allow-scripts allow-forms"
  width="600"
  height="420">
</iframe>

Tehlikeli birleşim: allow-scripts ve allow-same-origin

MDN'nin en önemli uyarısı şudur: gömülen belge gömen sayfayla aynı kökendeyse allow-scripts ile allow-same-origin'ı birlikte kullanmak kesinlikle önerilmez. Bu birleşim, gömülen belgenin sandbox özniteliğini kendisi kaldırabilmesine yol açar; sonuç, hiç sandbox kullanmamaktan daha güvenli değildir.

MDN iki sınırlamayı daha hatırlatır. Saldırgan içeriği korumalı çerçevenin dışında gösterebiliyorsa, örneğin kullanıcı çerçeveyi yeni bir sekmede açarsa, sandbox işe yaramaz; bu tür içerik zararı sınırlamak için ayrı bir kökenden sunulmalıdır. Ayrıca korumalı bir çerçeveden yapılan yönlendirme, açılan pencere veya yeni sekme aynı kısıtlamaları devralır. Örneğin allow-forms ya da allow-popups-to-escape-sandbox verilmemiş bir çerçeve yeni sekmede bir site açarsa, o sekmedeki form gönderimleri sessizce başarısız olur.

allow: izin politikası

allow özniteliği çerçeve için bir izin politikası (Permissions Policy) tanımlar ve mikrofon, kamera, pil, web paylaşımı gibi özelliklerin isteğin kökenine göre kullanılabilir olup olmadığını belirler. MDN önemli bir ilişkiyi not eder: allow ile verilen politika, Permissions-Policy HTTP başlığıyla belirlenen politikanın yerine geçmez, onun üzerine ek bir kısıtlama uygular.

Eski öznitelikler de bu mekanizmaya bağlanmıştır. allowfullscreen, çerçevenin requestFullscreen() ile tam ekrana geçebilmesini sağlar ve artık eski (legacy) bir öznitelik olarak allow="fullscreen *" biçiminde yeniden tanımlanmıştır. Aynı şekilde allowpaymentrequest de allow="payment *" karşılığına sahiptir.

<iframe
  src="https://video.example.com/embed/abc123"
  title="Ürün tanıtım videosu"
  width="560"
  height="315"
  allow="fullscreen *"
  loading="lazy"
  referrerpolicy="strict-origin-when-cross-origin">
</iframe>

loading: tembel çerçeve

loading iki değer alır: eager (varsayılan) çerçeveyi sayfa yüklenirken hemen yükler, lazy ise çerçeve görünür alana tarayıcının belirlediği bir mesafe kadar yaklaşana dek yüklemeyi erteler. Amaç, çerçeveye gerçekten ihtiyaç duyulacağı neredeyse kesinleşene kadar ağ ve depolama kullanmamaktır; MDN bunun özellikle ilk sayfa yükleme süresini kısalttığını belirtir. Görsellerde olduğu gibi erteleme yalnızca JavaScript etkinken yapılır: aksi hâlde bir sunucu, sayfaya stratejik olarak yerleştirdiği çerçevelerin ne zaman istendiğine bakarak kullanıcının kaydırma konumunu izleyebilirdi. Sayfanın altındaki harita ve video gömmeleri bu öznitelik için doğal adaylardır.

referrerpolicy

referrerpolicy, çerçevenin kaynağı istenirken hangi yönlendiren bilgisinin gönderileceğini belirler. Değerler <img> ile aynıdır:

name ve hedeflenebilir çerçeve

name, gömülü tarama bağlamına hedeflenebilir bir ad verir. Bu ad <a>, <form> ve <base> öğelerinin target özniteliğinde, <input> ve <button> öğelerinin formtarget özniteliğinde ve window.open() yönteminin windowName parametresinde kullanılabilir. Böylece bir bağlantıya tıklandığında sayfa yerine çerçevenin içeriği değişir:

<p>
  <a href="harita-ankara.html" target="harita">Ankara</a> |
  <a href="harita-izmir.html" target="harita">İzmir</a>
</p>
<iframe name="harita" src="harita-ankara.html" title="Şube haritası" width="600" height="400"></iframe>

target özniteliğinin diğer değerleri a etiketi yazısında, formların bir çerçeveye gönderilmesi form etiketi yazısında anlatılıyor.

srcdoc: HTML'i doğrudan gömmek

srcdoc, gömülecek HTML'i doğrudan öznitelik değeri olarak verir ve src özniteliğinin önüne geçer. İçeriği doctype, <html> ve <body> içeren tam bir belge söz dizimine uymalıdır, ama bunların çoğu atlanıp yalnızca gövde içeriği bırakılabilir. Bu belgenin konumu about:srcdoc olur. srcdoc'u desteklemeyen bir tarayıcı src adresine geri döner.

MDN, sandbox ile birleştirildiğinde bu tekniğin kullanıcı tarafından üretilen içeriği gösterirken betik enjeksiyonunu önlemenin bir yolu olabileceğini belirtir. Değeri yazarken üç kaçış kuralına uyulur:

• Önce HTML'i normal bir belgede kaçırdığınız gibi yazın (<, >, & gibi karakterler).
• Öznitelik içinde < ile < aynı karakteri temsil eder. Bu yüzden gerçek bir kaçış dizisi istiyorsanız tüm & karakterlerini & yapın: < değeri < olur.
• Son olarak çift tırnakları " ile değiştirin ki öznitelik erken kapanmasın (tek tırnak kullanıyorsanız tek tırnakları ' yapın). Bu adım öncekinden sonra yapıldığı için üretilen " ikinci kez kaçırılmaz.

<article>
  <footer>Dokuz dakika önce <i>ayse</i> yazdı:</footer>
  <iframe
    sandbox
    title="Kullanıcı yorumu"
    srcdoc="<p>Bir kod örneği: <code>&amp;lt;b&amp;gt;</code> kalın yazar.</p>
<p><a href=&quot;about:srcdoc#ek&quot;>Ek bilgiye git</a></p>
<h2 id=&quot;ek&quot;>Ek bilgi</h2>"
    width="500"
    height="200"></iframe>
</article>

Örnekteki iç bağlantının about:srcdoc#ek biçiminde yazılmasının bir nedeni var: about:srcdoc belgesi göreli adresleri çözümlerken gömen sayfanın adresini temel adres olarak kullanır. Gömülü içeriğin kendi içindeki bir yere atlayan bağlantılar için temel adresin açıkça about:srcdoc olarak verilmesi gerekir. Aynı durum src="about:blank" ile gömülen boş sayfa için de geçerlidir; bu boş sayfa aynı köken politikasına uyar ve göreli adreslerde gömen belgenin adresini kullanır. Karakter referansları için HTML entity yazısına bakabilirsiniz.

Betikler, aynı köken politikası ve üst gezinme

JavaScript tarafında çerçeveler window.frames sözde dizisinde yer alır. HTMLIFrameElement nesnesinin contentWindow özelliği çerçevedeki belgenin window nesnesini, contentDocument özelliği de içindeki belgeyi verir; çerçevenin içinden üst pencereye window.parent ile ulaşılır. Bu erişimlerin tamamı aynı köken politikasına tabidir: farklı kökenden yüklenmiş bir betik, diğer window nesnelerinin çoğu özelliğine erişemez. Kökenler arası iletişim için Window.postMessage() kullanılır.

Aynı kökendeki bir çerçevedeki betik window.top.location değerini değiştirerek en üst sayfayı başka bir adrese yönlendirebilir; buna "üst gezinme" (top navigation) denir. Farklı kökenden bir çerçeve ise bunu ancak çerçevede kalıcı kullanıcı etkileşimi (sticky activation) varsa yapabilir. Engellendiğinde tarayıcı kullanıcıdan izin isteyebilir ya da konsola hata yazabilir; MDN bu kısıtlamaya "framebusting intervention" adının verildiğini belirtir. Korumalı (sandbox) bir çerçeve, allow-top-navigation veya allow-top-navigation-by-user-activation verilmedikçe tüm üst gezinmeleri engeller; bu izinler devralınır, yani iç içe bir çerçeve ancak üst çerçeveleri de izinliyse üst gezinme yapabilir.

Bir güvenlik ayrıntısı daha: <iframe> üzerindeki error ve load olayları yerel ağdaki HTTP sunucularını yoklamak için kötüye kullanılabileceğinden, tarayıcılar çerçevelerde error olayını tetiklemez ve içerik yüklenemese bile load olayını her zaman tetikler. Yani "çerçeve yüklenemedi mi?" sorusunu bu olaylarla cevaplayamazsınız.

PDF gömmek

<iframe> bir PDF dosyasını tarayıcının yerleşik PDF görüntüleyicisiyle gösterebilir. Ancak <object>'ten farklı olarak, PDF görüntülenemezse gösterilecek bir yedek içerik desteklemez. MDN bu yüzden kullanıcıların PDF'i ayrıca açabilmesi için çerçevenin dışına bir bağlantı koymanızı önerir. sandbox özniteliği, allow-scripts veya allow-downloads verilse bile yerleşik PDF görüntüleyicisinin yüklenmesini engelleyebilir; MDN bunu yerel PDF önizlemesine kısıtlama eklemenin taşınabilir bir yolu olarak görmez ve tarayıcının PDF görüntüleyicisinin çalıştırılabilir içeriği zaten kendi içinde sınırladığını belirtir.

<iframe src="fiyat-listesi.pdf" title="2026 fiyat listesi (PDF)" width="800" height="600"></iframe>
<p><a href="fiyat-listesi.pdf">Fiyat listesini PDF olarak açın</a></p>

Boyut, konumlandırma ve duyarlı çerçeveler

<iframe> yerine konan (replaced) bir öğe olduğu için gömülü belgenin kutu içindeki konumu object-position ile ayarlanabilir; MDN object-fit özelliğinin ise çerçevelerde hiçbir etkisi olmadığını not eder. Güvenlik ve gizlilik nedeniyle çerçeveler, varsayılan olarak gömdükleri belgenin içerik boyutu hakkında üst belgeye bilgi vermez. MDN, gömülen belgeye <meta name="responsive-embedded-sizing"> eklenerek boyut bilgisinin paylaşılmasına izin verilebildiğini, üst sayfada da frame-sizing CSS özelliğiyle çerçevenin içeriğin gerçek boyutunu alabildiğini anlatır. Bu mekanizmayı kullanmadan önce tarayıcı desteği için MDN uyumluluk tablosuna bakın.

Diğer öznitelikler ve kullanımdan kalkanlar

MDN credentialless (çerçeveyi kendi ağ, çerez ve depolama verilerine erişmeyen geçici bir bağlamda yükler), csp (gömülen kaynağa bir içerik güvenlik politikası uygular), browsingtopics ve privateToken gibi daha özel öznitelikleri de listeler. Bunları kullanmadan önce tarayıcı desteği için MDN uyumluluk tablosuna bakın.

frameborder, scrolling, marginwidth, marginheight, align ve longdesc ise kullanımdan kalkmıştır; yeni içerikte kullanılmamalı, mevcut içerikten de kaldırılmalıdır. Kenarlık için MDN CSS border özelliğini önerir. longdesc için MDN, yaygın yanlış kullanım nedeniyle görsel olmayan tarayıcılara yardımcı olmadığını söyler. Eski <frame> ve <frameset> yapıları kullanımdan kalkan etiketler yazısında.

Sık yapılan hatalar

• title yazmamak: Ekran okuyucu kullananlar neyin gömüldüğünü anlamak için çerçeveye girmek zorunda kalır.
• Aynı kökenden içerikte allow-scripts ve allow-same-origin vermek: Gömülen belge sandbox'ı kaldırabilir.
• Çerçevenin içine yedek metin yazmak: İzin verilen içerik yoktur; yedek bağlantıyı çerçevenin dışına koyun.
• sandbox ekleyip formların neden çalışmadığını aramak: allow-forms olmadan form görünür ama gönderilmez.
• Yeni sekmede açılan sayfanın da kısıtlandığını unutmak: Açılan bağlamlar sandbox kısıtlamalarını devralır; gerekiyorsa allow-popups-to-escape-sandbox kullanın.
• load olayına güvenmek: İçerik yüklenemese bile tetiklenir; error hiç tetiklenmez.
• srcdoc içinde tırnak ve ve-işaretini kaçırmamak: Öznitelik erken kapanır ya da kaçış dizileri yanlış çözülür.
• Sayfayı çerçevelerle doldurmak: Her çerçeve ayrı bir belge ortamıdır ve kaynak tüketir.
• frameborder ve scrolling kullanmak: Kullanımdan kalkmıştır.

Sık Sorulan Sorular

sandbox özniteliği boş bırakılırsa ne olur?

Tüm kısıtlamalar uygulanır: betik çalışmaz, form gönderilmez, açılır pencere açılmaz ve içerik aynı köken denetiminden her zaman kalan özel bir köken altında değerlendirilir. İhtiyaç duyduğunuz izinleri belirteçlerle tek tek açarsınız.

allowfullscreen mı, allow="fullscreen" mı?

MDN allowfullscreen'ı eski bir öznitelik olarak niteler ve allow="fullscreen *" biçiminde yeniden tanımlandığını belirtir. Yeni kodda izin politikası söz dizimini kullanın.

iframe içindeki sayfaya JavaScript ile erişebilir miyim?

Yalnızca aynı kökendeyse. contentWindow ve contentDocument aynı köken politikasına tabidir; farklı kökenler arasında postMessage() ile mesajlaşılır.

Çerçeveyi tembel yüklemek güvenli mi?

loading="lazy" geçerli bir değerdir ve ilk yüklemede ağ kullanımını azaltır. Erteleme yalnızca JavaScript etkinken uygulanır; JavaScript kapalı bir tarayıcı çerçeveyi hemen yükler.

PDF görüntülenmezse kullanıcı ne görür?

<iframe> yedek içerik desteklemez. MDN'nin önerisine uyarak çerçevenin dışına PDF'e giden bir bağlantı ekleyin.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: HTML öğrenme rehberi · XSS ve CSP koruması · video ve audio etiketi · a etiketi ve target · integrity ve crossorigin · Erişilebilir ad · HTML entity