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

Exemple interactif

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.

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.

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

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

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.

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.

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.

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

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

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

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.

Le chargement n'est retardé que lorsque JavaScript est activé. Il s'agit d'une mesure anti-pistage, car si un agent utilisateur prenait en charge le chargement différé lorsque le script est désactivé, il serait toujours possible pour un site de suivre la position de défilement approximative d'un·e utilisateur·ice tout au long d'une session, en plaçant stratégiquement des cadres intégrés (iframes en anglais) dans le balisage d'une page de manière à ce qu'un serveur puisse suivre combien de cadres intégrés sont demandés et quand.

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.

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

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

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

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

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.

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.

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).

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).

Le référent inclura l'origine et le chemin (mais pas le fragment, le mot de passe ou le nom utilisateur·ice). 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.

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 :

Permet le téléchargement de fichiers avec un élément <a> ou <area> avec l'attribut download, ainsi qu'avec 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.

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.

Permet à la page d'ouvrir des fenêtres modales avec 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.

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

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

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.

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.

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

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).

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.

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

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

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

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.

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 avec 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.

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.

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

Attributs obsolètes

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

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.

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.

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

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

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 :

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

Toujours afficher une barre de défilement.

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 avec 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é avec <iframe> peuvent être ajustés par 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

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 définir explicitement about:srcdoc comme URL de base.

HTML

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.).
• &lt; 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 &amp;. Par exemple, &lt; devient &amp;lt;, et &amp; devient &amp;amp;.
• Remplacez les guillemets doubles (") par &quot; pour éviter que l'attribut srcdoc ne soit prématurément fermé (si vous utilisez ' à la place, remplacez ' par &apos;). Cette étape intervient après la précédente, donc les &quot; générés ici ne deviennent pas &amp;quot;.

Résultat

Résumé technique

Spécifications

Compatibilité des navigateurs

Activez JavaScript pour afficher ce tableau de compatibilité des navigateurs.

Voir aussi

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