<iframe> : l'élément de cadre intégré

Exemple interactif

<iframe
  id="inlineFrameExample"
  title="Exemple de cadre intégré"
  width="300"
  height="200"
  src="https://www.openstreetmap.org/export/embed.html?bbox=-0.004017949104309083%2C51.47612752641776%2C0.00030577182769775396%2C51.478569861898606&amp;layer=mapnik">
</iframe>

iframe {
  border: 1px solid black;
  width: 100%; /* prévaut sur la largeur définie par l'attribut HTML width */
}

Chaque contexte de navigation intégré possède son propre document et permet des navigations vers des URL. Les navigations de chaque contexte de navigation intégré sont linéarisées dans l'historique de session du contexte de navigation le plus élevé. Le contexte de navigation qui contient les autres est appelé contexte de navigation parent. Le contexte de navigation le plus élevé — celui qui n'a pas de parent — correspond généralement à la fenêtre du navigateur, représentée par l'objet Window.

Attributs

Cet élément inclut les attributs universels.

allow

Définit une Permissions Policy pour l'<iframe>. La politique définit quelles fonctionnalités sont disponibles pour l'<iframe> (par exemple l'accès au microphone, à la caméra, à la batterie, au partage Web, etc.) en fonction de l'origine de la requête.

Voir iframes dans le sujet Permissions-Policy pour des exemples.

Note : Une Permissions Policy définie par l'attribut allow applique une restriction supplémentaire en plus de la politique indiquée dans l'en-tête Permissions-Policy. Elle ne la remplace pas.

allowfullscreen

Cet attribut, lorsqu'il vaut true, indique que l'<iframe> intégrée peut être passée en plein écran via la méthode requestFullscreen().

Note : Cet attribut est considéré comme historique et a été redéfini avec allow="fullscreen".

allowpaymentrequest Obsolète Non standard

Cet attribut, lorsqu'il vaut true, permet à l'<iframe> intégrée d'appeler l'API Payment Request.

Note : Cet attribut est considéré comme historique et a été redéfini avec allow="payment".

browsingtopics Expérimental Non standard

Un attribut booléen qui, s'il est présent, indique que les sujets sélectionnés pour l'utilisateur·ice courant·e doivent être envoyés avec la requête pour la source de l'<iframe>. Voir Utilisation de l'API Topics pour plus de détails.

credentialless Expérimental

Mettre à true pour rendre l'<iframe> sans identifiants, son contenu sera chargé dans un contexte éphémère qui n'a pas accès au réseau, aux cookies ni aux données de stockage associées à son origine. Il utilise un contexte local à la durée de vie du document de plus haut niveau. En contrepartie, les règles d'intégration de Cross-Origin-Embedder-Policy (COEP) peuvent être levées, permettant à des documents avec COEP défini d'intégrer des documents tiers qui ne le sont pas. Voir IFrame credentialless pour plus de détails.

csp Expérimental

L'attribut csp définit la politique de sécurité du contenu que le document intégré doit respecter. Voir HTMLIFrameElement.csp pour plus de détails.

height

Cet attribut définit la hauteur du cadre en pixels CSS. La valeur par défaut est 150.

loading

Cet attribut indique la façon dont le navigateur devrait charger le cadre intégré :

eager

Charger le cadre intégré immédiatement au chargement de la page (c'est la valeur par défaut).

lazy

Retarder le chargement du cadre intégré jusqu'à ce qu'elle atteigne une distance calculée par rapport au zone d'affichage, telle que définie par le navigateur. L'intention est d'éviter d'utiliser la bande passante réseau et de stockage nécessaire pour récupérer le cadre tant que le navigateur n'est pas raisonnablement certain qu'elle sera nécessaire. Cela améliore les performances et réduit les coûts dans la plupart des cas d'utilisation typiques, en particulier en réduisant le temps de chargement initial de la page.

Note : Le chargement n'est retardé que lorsque JavaScript est activé. Il s'agit d'une mesure anti-pistage.

name

Un nom pour le contexte de navigation (ou la frame). Ce nom peut être utilisé comme la valeur de l'attribut target d'un élément <a>, <form>, ou <base> ; l'attribut formtarget d'un élément <input> ou <button> ; ou le paramètre windowName de la méthode window.open(). De plus, ce nom devient une propriété des objets Window et Document, contenant une référence à la fenêtre intégrée ou à l'élément lui-même.

referrerpolicy

Une chaîne de caractères qui indique le référent (referrer) à utiliser lors de la récupération de la ressource :

no-referrer

L'en-tête Referer ne sera pas envoyé.

no-referrer-when-downgrade

L'en-tête Referer ne sera envoyé lorsqu'on navigue vers une origine qui n'utilise pas TLS (HTTPS).

origin

Le référent sera l'origine de la page (c'est-à-dire son schéma, son hôte et le port utilisé).

origin-when-cross-origin

Le référent envoyé vers d'autres origines sera limité au schéma, à l'hôte et au port. Les navigations sur la même origine incluront toujours le chemin.

same-origin

Un référent sera envoyé pour les mêmes origines mais les requêtes multi-origines ne contiendront pas d'informations de référent.

strict-origin

Seule l'origine du document est envoyée comme référent lorsque le protocole de sécurité est le même (HTTPS→HTTPS). L'origine n'est pas envoyée lorsque la destination est moins sécurisée (HTTPS→HTTP).

strict-origin-when-cross-origin (par défaut)

Envoie de l'URL complète pour les requêtes de même origine, seule l'origine est envoyée lorsque le protocole de sécurité est le même (HTTPS→HTTPS) et aucun en-tête n'est envoyé pour une destination moins sécurisée (HTTPS→HTTP).

unsafe-url

Le référent inclura l'origine et le chemin (mais pas le fragment, le mot de passe ou le nom utilisateur). Cette valeur n'est pas sûre, car elle peut entraîner des fuites d'origine ou de chemin provenant de ressources sécurisées avec TLS vers des origines non sécurisées.

sandbox

Cet attribut permet d'appliquer des restrictions sur le contenu qui peut apparaître dans l'<iframe>. Si cet attribut vaut la chaîne de caractères vide, toutes les restrictions sont appliquées, sinon, on peut utiliser une liste de mots-clés séparés par des espaces pour définir des restrictions précises. Les mots-clés qui peuvent être utilisés sont :

allow-downloads

Permet le téléchargement de fichiers via un élément <a> ou <area> avec l'attribut download, ainsi que via la navigation qui conduit au téléchargement d'un fichier. Cela fonctionne que l'utilisateur·ice ait cliqué sur le lien ou que du code JavaScript l'ait initié sans interaction de l'utilisateur·ice.

allow-forms

Permet à la page d'envoyer des formulaires. Si ce mot-clé n'est pas utilisé, un formulaire s'affichera normalement, mais son envoi n'activera pas la validation des champs, n'enverra pas de données au serveur web et ne fermera pas un dialogue.

allow-modals

Permet à la page d'ouvrir des fenêtres modales via Window.alert(), Window.confirm(), Window.print() et Window.prompt() ; l'ouverture d'un <dialog> est autorisée indépendamment de ce mot-clé. Il permet également à la page de recevoir l'événement BeforeUnloadEvent.

allow-orientation-lock

Permet à la ressource de verrouiller l'orientation de l'écran via Screen.lockOrientation.

allow-pointer-lock

Permet à la page d'utiliser l'API Pointer Lock.

allow-popups

Permet l'ouverture de popups (créées, par exemple, par Window.open() ou target="_blank"). Si ce mot-clé n'est pas utilisé, cette fonctionnalité échouera silencieusement.

allow-popups-to-escape-sandbox

Permet à un document en bac à sable d'ouvrir un nouveau contexte de navigation sans lui appliquer les drapeaux de sandbox. Cela permettra, par exemple, à une publicité tierce d'être mise en bac à sable sans imposer les mêmes restrictions à la page vers laquelle la publicité pointe. Si ce drapeau n'est pas inclus, une page redirigée, une fenêtre popup ou un nouvel onglet sera soumis aux mêmes restrictions de sandbox que l'<iframe> d'origine.

allow-presentation

Permet aux intégrateurs de contrôler si un cadre intégré peut démarrer une session de présentation.

allow-same-origin

Si ce jeton n'est pas utilisé, la ressource est traitée comme provenant d'une origine spéciale qui échoue toujours à la police de même origine (empêchant potentiellement l'accès au stockage/de cookies et à certaines API JavaScript).

allow-scripts

Permet à la page d'exécuter des scripts (mais pas de créer des fenêtres pop-up). Si ce mot-clé n'est pas utilisé, cette opération n'est pas autorisée.

allow-storage-access-by-user-activation Expérimental

Permet à un document chargé dans l'<iframe> d'utiliser la l'API d'accès au stockage pour demander l'accès aux cookies non partitionnés.

allow-top-navigation

Permet à la ressource de naviguer le contexte de navigation de plus haut niveau (celui nommé _top).

allow-top-navigation-by-user-activation

Permet à la ressource de naviguer le contexte de navigation de plus haut niveau, mais uniquement si cela est initié par un geste utilisateur.

allow-top-navigation-to-custom-protocols

Permet les navigations vers des protocoles non-http intégrés au navigateur ou enregistrés par un site. Cette fonctionnalité est également activée par les mots-clés allow-popups ou allow-top-navigation.

Note :

• Lorsque le document intégré possède la même origine que la page englobante, il est fortement déconseillé d'utiliser à la fois allow-scripts et allow-same-origin, car cela permettrait au document intégré de retirer l'attribut sandbox — le rendant aussi peu sûr que de ne pas utiliser sandbox du tout.
• La mise en bac à sable est inutile si un attaquant peut afficher du contenu en dehors d'un iframe sandboxé — par exemple si le visiteur ouvre le cadre dans un nouvel onglet. Un tel contenu devrait également être servi depuis une origine séparée pour limiter les dommages potentiels.

Note : Lorsqu'on redirige l'utilisateur·ice, ouvre une fenêtre popup ou un nouvel onglet depuis une page intégrée dans un <iframe> avec l'attribut sandbox, le nouveau contexte de navigation est soumis aux mêmes restrictions sandbox. Cela peut poser des problèmes — par exemple, si une page intégrée dans un <iframe> sans l'attribut sandbox="allow-forms" ou sandbox="allow-popups-to-escape-sandbox" ouvre un nouveau site dans un onglet séparé, l'envoi d'un formulaire dans ce nouveau contexte de navigation échouera silencieusement.

src

L'URL de la page à intégrer. Utilisez la valeur about:blank pour intégrer une page vide conforme à la politique de même origine. Notez également que supprimer par programme l'attribut src d'un <iframe> (par exemple via Element.removeAttribute()) provoque le chargement de about:blank dans la frame pour Firefox (à partir de la version 65), les navigateurs basés sur Chromium et Safari/iOS.

Note : La page about:blank utilise l'URL du document englobant comme URL de base lors de la résolution des URL relatives, comme les liens d'ancrage.

srcdoc

Le HTML inline à intégrer, qui remplace l'attribut src. Son contenu doit respecter la syntaxe d'un document HTML complet (directive doctype, balises <html>, <body>, etc.), bien que la plupart de ces éléments puissent être omis et que seul le contenu du corps soit conservé. Ce document aura pour emplacement about:srcdoc. Si un navigateur ne prend pas en charge l'attribut srcdoc, il utilisera l'URL indiquée par l'attribut src.

Note : La page about:srcdoc utilise l'URL du document englobant comme URL de base lors de la résolution des URL relatives, comme les liens d'ancrage.

width

La largeur du cadre en pixels CSS. La valeur par défaut est 300.

Attributs dépréciés

align Obsolète

Cet attribut obsolète permettait de définir l'alignement de l'iframe par rapport à son contexte englobant.

frameborder Obsolète

Lorsqu'il vaut 1 (la valeur par défaut), cet attribut indique au navigateur de définir une bordure entre ce cadre et tout autre cadre. Lorsqu'il vaut 0, aucune bordure n'est dessinée. Plutôt que cet attribut, on utilisera la propriété CSS border pour dessiner la bordure autour d'une iframe.

longdesc Obsolète

Un URI vers une description détaillée du cadre. En raison d'un mauvais usage, cet attribut n'est pas utile pour les navigateurs non-visuels.

marginheight Obsolète

L'espace, exprimé en pixels, entre le contenu du cadre et ses marges haute et basse.

marginwidth Obsolète

L'espace, exprimé en pixels, entre le contenu du cadre et ses marges gauche et droite.

scrolling Obsolète

Un attribut à valeur contrainte qui indique si le navigateur doit afficher une barre de défilement (ou tout autre moyen de défilement) pour le cadre :

auto

Uniquement lorsque le contenu de la frame dépasse ses dimensions.

yes

Toujours afficher une barre de défilement.

no

Ne jamais afficher de barre de défilement.

Scripts

Les iframes (et aussi les <frame>) font partie du pseudo-tableau window.frames.

En utilisant l'élément HTMLIFrameElement du DOM, les scripts peuvent accéder à l'objet window de la page HTML incluse par la propriété contentWindow. La propriété contentDocument fait référence au document contenu dans l'iframe (l'équivalent de contentWindow.document).

Depuis l'iframe, un script peut obtenir une référence à la fenêtre parente via la propriété window.parent.

Les scripts qui tentent d'accéder au contenu de l'iframe doivent respecter les règles de même origine. Les scripts ne peuvent pas accéder à la plupart des propriétés des autres objets window s'ils ont été chargés depuis un domaine différent. Cela s'applique également aux scripts d'un iframe qui souhaitent accéder au contexte englobant. On peut toutefois communiquer entre différents domaines grâce à la méthode Window.postMessage().

Navigation vers le haut depuis des cadres d'origines différentes

Les scripts exécutés dans un cadre de même origine peuvent accéder à la propriété Window.top et définir window.top.location pour rediriger la page de plus haut niveau vers une nouvelle URL. Ce comportement est appelé « navigation vers le haut ».

Une cadre d'origines différentes est autorisée à rediriger la page de plus haut niveau en utilisant top uniquement si la cadre dispose de activation persistante. Si la navigation vers le haut est bloquée, les navigateurs peuvent soit demander l'autorisation de l'utilisateur·ice pour la redirection, soit consigner l'erreur dans la console de développement (ou les deux). Les navigateurs désignent cette restriction par le terme framebusting intervention. Concrètement, une cadre d'origines différentes ne peut pas rediriger immédiatement la page de plus haut niveau — l'utilisateur·ice doit avoir préalablement interagi avec la cadre ou avoir accordé l'autorisation de redirection.

Une cadre en bac à sable bloque toute navigation vers le haut à moins que les valeurs de l'attribut sandbox ne soient définies sur allow-top-navigation ou allow-top-navigation-by-user-activation. Notez que les autorisations de navigation vers le haut sont héritées, une cadre imbriquée ne peut effectuer une navigation vers le haut que si ses cadres parentes y sont également autorisées.

Positionnement et redimensionnement

En tant qu'élément remplacé, la position, l'alignement et le redimensionnement du document embarqué via <iframe> peuvent être ajustés via la propriété object-position.

Comportement des événements error et load

Les événements error et load déclenchés sur des <iframe> pourraient être utilisés pour sonder l'espace d'URL des serveurs HTTP du réseau local. Par conséquent, par mesure de sécurité, les agents utilisateur ne déclenchent pas l'événement error sur les <iframe>, et l'événement load est toujours déclenché même si le contenu de l'<iframe> échoue à se charger.

Exemples

Un <iframe> simple

Cet exemple intègre la page https://example.org dans un cadre intégré. C'est un cas d'utilisation courant des cadres intégrés : intégrer du contenu provenant d'un autre site. Par exemple, l'exemple en direct lui‑même et l'exemple interactif en haut de la page sont tous deux des intégrations <iframe> de contenu provenant d'un autre site MDN.

HTML

<iframe
  src="https://example.org"
  title="Exemple d'iframe"
  width="400"
  height="300">
</iframe>

Résultat

Intégrer du code source dans un <iframe>

Cet exemple affiche directement du code source dans une iframe. Cela peut être utilisé comme technique pour empêcher l'injection de scripts lors de l'affichage de contenu généré par des utilisateur·ice·s, lorsqu'on le combine avec l'attribut sandbox.

Notez que lorsque vous utilisez srcdoc, toutes les URL relatives du contenu intégré seront résolues par rapport à l'URL de la page englobante. Si vous voulez utiliser des liens d'ancrage qui pointent vers des emplacements du contenu intégré, vous devez spécifier explicitement about:srcdoc comme URL de base.

HTML

<article>
  <footer>Il y a neuf minutes, <i>jc</i> a écrit&nbsp;:</footer>
  <iframe
    sandbox
    srcdoc="<p>Il existe deux manières d'utiliser l'élément <code>iframe</code>&nbsp;:</p>
<ol>
<li><a href=&quot;about:srcdoc#embed_another&quot;>Pour intégrer du contenu provenant d'une autre page</a></li>
<li><a href=&quot;about:srcdoc#embed_user&quot;>Pour intégrer du contenu généré par les utilisateur·ice·s</a></li>
</ol>
<h2 id=&quot;embed_another&quot;>Intégrer du contenu depuis une autre page</h2>
<p>Utilisez l'attribut <code>src</code> pour spécifier l'URL de la page à intégrer&nbsp;:</p>
<pre><code>&amp;lt;iframe src=&quot;https://example.org&quot;&amp;gt;&amp;lt;/iframe&amp;gt;</code></pre>
<h2 id=&quot;embed_user&quot;>Intégrer du contenu généré par les utilisateur·ice·s</h2>
<p>Utilisez l'attribut <code>srcdoc</code> pour spécifier le contenu à intégrer. Ce billet en est déjà un exemple&nbsp;!</p>
"
    width="500"
    height="250"
></iframe>
</article>

Voici comment écrire les séquences d'échappement lorsque vous utilisez srcdoc :

• Premièrement, écrivez le HTML en échappant les caractères que vous échappez dans un document HTML normal (par exemple <, >, &, etc.).
• < et < représentent exactement le même caractère dans l'attribut srcdoc. Par conséquent, pour en faire une véritable séquence d'échappement dans le document HTML, remplacez toute esperluette (&) par &. Par exemple, < devient <, et & devient &.
• Remplacez les guillemets doubles (") par " pour éviter que l'attribut srcdoc ne soit prématurément fermé (si vous utilisez ' à la place, remplacez ' par '). Cette étape intervient après la précédente, donc les " générés ici ne deviennent pas ".

Résultat

Résumé technique

Spécifications

Compatibilité des navigateurs

Voir aussi

• CSP : frame-ancestors
• Vie privée, autorisations et sécurité de l'information