<iframe> : l'élément de cadre intégré
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
L'élément HTML <iframe>
représente un contexte de navigation imbriqué qui permet en fait d'obtenir une page HTML intégrée dans la page courante.
Exemple interactif
Chaque contexte de navigation possède son propre historique et son propre document actif. Le contexte de navigation qui contient le contenu intégré est appelé « contexte de navigation parent ». Le contexte de navigation le plus élevé (qui n'a pas de contexte parent) correspond généralement à la fenêtre du navigateur (cf. Window
).
Attention : Chaque contexte de navigation créé par un élément <iframe>
représente un document à part entière et cela peut donc augmenter les ressources nécessaires à l'utilisation de la page. Aussi, bien qu'en théorie on puisse ajouter autant d'iframes que possible sur autant de niveaux d'imbrication que voulus, on gardera à l'esprit que cela peut nuire aux performances.
Catégories de contenu | Contenu de flux, contenu phrasé, contenu intégré, contenu interactif, contenu tangible. |
---|---|
Contenu autorisé | Aucun. |
Omission de balise | Aucune omission, la balise ouvrante et la balise fermante doivent être présentes. |
Parents autorisés | Tout élément qui accepte du contenu intégré. |
Rôle ARIA implicite | Aucun rôle correspondant |
Rôles ARIA autorisés |
application ,
document , img , none ,
presentation
|
Interface DOM | HTMLIFrameElement |
Attributs
Cet élément prend en charge les attributs universels.
allow
-
L'attribut
allow
permet de définir une politique de fonctionnalité pour l'iframe. Cette politique définit les fonctionnalités disponibles au sein de l'iframe selon l'origine de la requête (les fonctionnalités peuvent être l'accès au micro, à la caméra, aux informations de batterie, etc.). Pour plus d'informations, voir l'article sur l'utilisation deFeature-Policy
. allowfullscreen
-
Cet attribut, lorsqu'il vaut
true
, indique que l'iframe intégrée peut être passée en plein écran via la méthodeElement.requestFullscreen()
.Note : Cet attribut est considéré comme historique et a été redéfini avec
allow="fullscreen"
. allowpaymentrequest
-
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"
. csp
Expérimental-
L'attribut
csp
définit la politique de sécurité du contenu que le document intégré doit respecter. VoirHTMLIFrameElement.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
Expérimental-
Cet attribut indique la façon dont le navigateur devrait charger l'iframe :
eager
: L'iframe doit être chargée immédiatement, même si elle n'est pas dans la zone d'affichage (viewport) visible. C'est la valeur par défaut.lazy
: Le chargement de l'iframe est retardé jusqu'à ce que celle-ci atteigne une distance donnée du viewport, définie par le navigateur.
name
-
Un nom pour le contexte de navigation (ou la frame). Ce nom peut être utilisé comme la valeur de l'attribut
target
(cible) d'un élément<a>
ou<form>
(formulaire) ou comme valeur de l'attributformtarget
d'un élément<input>
(entrée) ou<button>
(bouton). Il peut également être utilisé comme valeur pour le paramètrewindowName
de la méthodewindow.open()
. 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
signifie que l'en-têteReferer
ne sera pas envoyé.no-referrer-when-downgrade
signifie qu'aucun en-têteReferer
ne sera envoyé lorsqu'on navigue vers une origine qui n'utilise pas TLS (HTTPS). C'est le comportement par défaut de l'agent utilisateur.origin
signifie que 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
signifie que les navigations vers d'autres origines seront limitées aux schémas, hôtes et ports. Les navigations sur la même origine incluront le chemin explicite du référent.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
: l'URL complète est envoyée 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
signifie que 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-without-user-activation
Expérimental : permet aux téléchargements d'avoir lieu sans un signe de l'utilisateur.allow-downloads
: permet aux téléchargements d'avoir lieu après une action de la part de l'utilisateur.allow-forms
: le contexte de navigation intégré peut envoyer des formulaires. Si ce mot-clé n'est pas utilisé, cette opération n'est pas autorisée.allow-modals
: le contexte de navigation peut ouvrir des fenêtres modales.allow-orientation-lock
: le contexte de navigation peut désactiver le verrouillage de l'orientation de l'écran.allow-pointer-lock
: le contexte de navigation peut utliser l'API Pointer Lock.allow-popups
: le contexte de navigation peut déclencher des fenêtres contextuelles (par exemple avecwindow.open
,target="_blank"
,showModalDialog
). Si ce mot-clé n'est pas utilisé, la fonctionnalité échouera sans message d'erreur.allow-popups-to-escape-sandbox
: ce mot-clé permet à un document isolé dans un bac à sable (sandboxed) d'ouvrir de nouvelles fenêtres sans avoir à forcer la mise en bac à sable pour ces fenêtres. Cela permettra par exemple à une publicité tierce d'être correctement mise dans un bac à sable sans appliquer les mêmes restrictions sur la page initiale.allow-presentation
: ce mot-clé permet à un iframe de démarrer une session de présentation.allow-same-origin
: ce mot-clé permet au document isolé de supporter les tests de same-origin policy en désactivant le remplacement de l'origine de l'iframe par une origine unique.allow-scripts
: le contexte de navigation peut exécuter des scripts (mais ne peut pas créer de fenêtres contextuelles). Si ce mot-clé n'est pas utilisé, cette opération n'est pas autorisée.allow-storage-access-by-user-activation
Expérimental : ce mot-clé permet au contexte de navigation embarqué de demander l'accès aux fonctionnalités de stockage du document parent (ex. ses cookies, le stockage web) grâce à l'API Storage Access.allow-top-navigation
: le contexte de navigation peut charger du contenu depuis le contexte de navigation de plus haut niveau. Si ce mot-clé est absent, cette opération n'est pas autorisée.allow-top-navigation-by-user-activation
: le contexte de navigation peut charger du contenu depuis le contexte de plus haut niveau uniquement si l'action provient de l'utilisateur. Si ce mot-clé est absent, cette opération n'est pas autorisée.
Note :
- Lorsque le document intégré possède la même origine que la page principale, il est fortement déconseillé d'employer
allow-scripts
etallow-same-origin
simultanément, car cela permet de retirer l'attributsandbox
via un programme, c'est donc aussi sûr que de ne pas utiliser l'attributsandbox
. - La mise en bac à sable (sandboxing) est d'une aide minime si un attaquant peut faire en sorte qu'un contenu potentiellement hostile soit affiché dans le navigateur de l'utilisateur en dehors d'un iframe sous sandbox. Aussi, il est recommandé de diffuser le contenu depuis un domaine dédié séparé, afin de limiter les éventuels dommages.
- L'attribut
sandbox
n'est pas pris en charge par Internet Explorer 9 et les versions antérieures.
src
-
L'URL de la page qu'on souhaite intégrer. On pourra utiliser
about:blank
pour les pages vides afin de respecter les règles de même origine (Same-Origin Policy). On notera également que retirer l'attributsrc
d'un élément<iframe>
à l'aide d'un script (par exemple avecElement.removeAttribute()
) provoquera le chargement deabout:blank
dans la frame pour Firefox à partir de la version 65, pour les navigateurs basés sur Chromium ainsi que pour Safari. srcdoc
-
Le contenu de la page qu'on souhaite intégrer dans le contexte de navigation et qui surcharge celui indiqué par
src
. width
-
Cet attribut indique la largeur de l'iframe en pixels CSS. Par défaut, cet attribut vaut
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
: la barre de défilement est uniquement affichée lorsque c'est nécessaire.yes
: la barre de défilement est toujours affichée.no
: aucune barre de défilement n'est affichée.
Attributs non-standard Non-standard
mozbrowser
Non-standard-
Cet attribut est uniquement disponible pour les WebExtensions. L'iframe se comporte comme une fenêtre de navigateur de plus haut niveau. Voir le bug 1318532 quant à l'exposition de cet attribut dans Firefox.
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 et ne peuvent pas accéder à la plupart des propriétés d'une autre fenêtre 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()
.
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 les propriétés object-position
et object-fit
.
Exemples
Une <iframe> simple
L'exemple qui suit utilise la page située à https://example.org pour l'intégrer à la page courante via une iframe.
HTML
<iframe
src="https://example.org"
title="Exemple d'iframe"
width="400"
height="300">
</iframe>
Résultat
Accessibilité
Les personnes qui utilisent des outils d'assistance tels que des lecteurs d'écran peuvent utiliser l'attribut title
pour obtenir la description du contenu embarqué par l'iframe
. La valeur du titre doit décrire, de façon claire et concise, le contenu embarqué.
<iframe
title="La page Wikipédia consacrée à Robert Louis Stevenson"
src="https://fr.wikipedia.org/wiki/Robert_Louis_Stevenson">
</iframe>
Sans cette description, les utilisateurs peuvent devoir naviguer à l'intérieur de l'iframe
et parcourir le contenu afin de comprendre de quoi il s'agit. Le changement de contexte peut être source de confusion et demander un temps de réflexion, notamment pour les pages qui contiennent plusieurs iframe
et/ou du contenu interactif tel que des vidéos ou de la musique.
Spécifications
Specification |
---|
HTML Standard # the-iframe-element |
Compatibilité des navigateurs
BCD tables only load in the browser