lment HTML <iframe> : l'lment de cadre intgr

Exemple interactif

<iframe
  id="inlineFrameExample"
  title="Exemple de cadre intgr"
  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%; /* prvaut sur la largeur dfinie par l'attribut HTML width */
}

Chaque contexte de navigation intgr possde son propre document et permet des navigations vers des URL. Les navigations de chaque contexte de navigation intgr sont linarises 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 gnralement la fentre du navigateur, reprsente par l'objet Window.

Attributs

Cet lment inclut les attributs universels.

allow

Dfinit une Permissions Policy pour l'<iframe>. La politique dfinit quelles fonctionnalits sont disponibles pour l'<iframe> (par exemple l'accs au microphone, la camra, la batterie, au partage Web, etc.) en fonction de l'origine de la requte.

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

Note : Une Permissions Policy dfinie par l'attribut allow applique une restriction supplmentaire en plus de la politique indique dans l'en-tte Permissions-Policy. Elle ne la remplace pas.

allowfullscreen

Cet attribut, lorsqu'il vaut true, indique que l'<iframe> intgre peut tre passe en plein cran avec la mthode requestFullscreen().

Note : Cet attribut est considr comme historique et a t redfini avec allow="fullscreen".

allowpaymentrequest

Cet attribut, lorsqu'il vaut true, permet l'<iframe> intgre d'appeler l'API Payment Request.

Note : Cet attribut est considr comme historique et a t redfini avec allow="payment".

browsingtopics

Un attribut boolen qui, s'il est prsent, indique que les sujets slectionns pour l'utilisateurice courante doivent tre envoys avec la requte pour la source d'un <iframe>.

credentialless

Mettre true pour rendre l'<iframe> sans identifiants, son contenu est charg dans un contexte phmre qui n'a pas accs au rseau, aux cookies ni aux donnes de stockage associes son origine. Il utilise un contexte local la dure de vie du document de plus haut niveau. En contrepartie, les rgles d'intgration de Cross-Origin-Embedder-Policy (COEP) peuvent tre leves, permettant des documents avec COEP dfini d'intgrer des documents tiers qui ne le sont pas. Voir IFrame credentialless pour plus de dtails.

csp

L'attribut csp dfinit la politique de scurit du contenu que le document intgr doit respecter. Voir HTMLIFrameElement.csp pour plus de dtails.

height

Cet attribut dfinit la hauteur du cadre en pixels CSS. La valeur par dfaut est 150.

loading

Cet attribut indique la faon dont le navigateur doit charger le cadre intgr :

eager

Charger le cadre intgr immdiatement au chargement de la page (c'est la valeur par dfaut).

lazy

Retarder le chargement du cadre intgr jusqu' ce qu'elle atteigne une distance calcule par rapport au zone d'affichage, telle que dfinie par le navigateur. L'intention est d'viter d'utiliser la bande passante rseau et de stockage ncessaire pour rcuprer le cadre tant que le navigateur n'est pas raisonnablement certain qu'elle est ncessaire. Cela amliore les performances et rduit les cots dans la plupart des cas d'utilisation typiques, en particulier en rduisant 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 diffr lorsque le script est dsactiv, il est toujours possible pour un site de suivre la position de dfilement approximative d'une utilisateurice tout au long d'une session, en plaant stratgiquement des cadres intgrs (iframes en anglais) dans le balisage d'une page de manire ce qu'un serveur puisse suivre combien de cadres intgrs sont demands et quand.

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 lment <a>, <form>, ou <base> ; l'attribut formtarget d'un lment <input> ou <button> ; ou le paramtre windowName de la mthode . De plus, ce nom devient une proprit des objets Window et Document, contenant une rfrence la fentre intgre ou l'lment lui-mme.

referrerpolicy

Une chane de caractres qui indique le rfrent (referrer) utiliser lors de la rcupration de la ressource :

no-referrer

L'en-tte Referer n'est pas envoy.

no-referrer-when-downgrade

L'en-tte Referer n'est envoy lorsqu'on navigue vers une origine qui n'utilise pas TLS (HTTPS).

origin

Le rfrent est l'origine de la page (c'est--dire son schma, son hte et le port utilis).

origin-when-cross-origin

Le rfrent envoy vers d'autres origines est limit au schma, l'hte et au port. Les navigations sur la mme origine inclut toujours le chemin.

same-origin

Un rfrent est envoy pour les mmes origines mais les requtes multiple-origines ne contient pas d'informations de rfrent.

strict-origin

Seule l'origine du document est envoye comme rfrent lorsque le protocole de scurit est le mme (HTTPSHTTPS). L'origine n'est pas envoye lorsque la destination est moins scurise (HTTPSHTTP).

strict-origin-when-cross-origin (par dfaut)

Envoie de l'URL complte pour les requtes de mme origine, seule l'origine est envoye lorsque le protocole de scurit est le mme (HTTPSHTTPS) et aucun en-tte n'est envoy pour une destination moins scurise (HTTPSHTTP).

unsafe-url

Le rfrent inclut l'origine et le chemin (mais pas le fragment, le mot de passe ou le nom utilisateurice). Cette valeur n'est pas sre, car elle peut entraner des fuites d'origine ou de chemin provenant de ressources scurises avec TLS vers des origines non scurises.

sandbox

Cet attribut permet d'appliquer des restrictions sur le contenu qui peut apparatre dans l'<iframe>. Si cet attribut vaut la chane de caractres vide, toutes les restrictions sont appliques, sinon, on peut utiliser une liste de mots-cls spars par des espaces pour dfinir des restrictions prcises. Les mots-cls qui peuvent tre utiliss sont :

allow-downloads

Permet le tlchargement de fichiers avec un lment <a> ou <area> avec l'attribut download, ainsi qu'avec la navigation qui conduit au tlchargement d'un fichier. Cela fonctionne que l'utilisateurice ait cliqu sur le lien ou que du code JavaScript l'ait initi sans interaction de l'utilisateurice.

allow-forms

Permet la page d'envoyer des formulaires. Si ce mot-cl n'est pas utilis, un formulaire s'affiche normalement, mais son envoi n'active pas la validation des champs, n'envoie pas de donnes au serveur web et ne ferme pas un dialogue.

allow-modals

Permet la page d'ouvrir des fentres bloquantes avec Window.alert(), Window.confirm(), Window.print() et Window.prompt() ; l'ouverture d'un <dialog> est autorise indpendamment de ce mot-cl. Il permet galement la page de recevoir l'vnement BeforeUnloadEvent.

allow-orientation-lock

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

allow-pointer-lock

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

allow-popups

Permet l'ouverture de popups (cres, par exemple, par ou target="_blank"). Si ce mot-cl n'est pas utilis, cette fonctionnalit choue 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 permet, par exemple, une publicit tierce d'tre mise en bac sable sans imposer les mmes restrictions la page vers laquelle la publicit pointe. Si ce drapeau n'est pas inclus, une page redirige, une fentre intrusive ou un nouvel onglet est envoy aux mmes restrictions de sandbox qu'un <iframe> d'origine.

allow-presentation

Permet aux intgrateurs de contrler si un cadre intgr peut dmarrer une session de prsentation.

allow-same-origin

Si ce jeton n'est pas utilis, la ressource est traite comme provenant d'une origine spciale qui choue toujours la police de mme origine (empchant potentiellement l'accs au stockage/de cookies et certaines API JavaScript).

Note : Lorsque allow-same-origin est prsent, un document parent de mme origine peut toujours accder au DOM de l'iframe et interagir avec lui, mme si allow-scripts n'est pas dfini. Le jeton allow-scripts ne contrle que l'excution de scripts dans le contexte de navigation intgr et n'affecte pas l'accs au DOM depuis le parent.

allow-scripts

Permet la page d'excuter des scripts (mais pas de crer des fentres pop-up). Si ce mot-cl n'est pas utilis, cette opration n'est pas autorise.

allow-storage-access-by-user-activation

Permet un document charg dans un <iframe> d'utiliser l'API d'accs au stockage pour demander l'accs aux cookies non partitionns.

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 c'est initi par un geste de l'utilisateurice.

allow-top-navigation-to-custom-protocols

Permet les navigations vers des protocoles non-http intgrs au navigateur ou enregistrs par un site. Cette fonctionnalit est galement active par les mots-cls allow-popups ou allow-top-navigation.

Note :

• Lorsque le document intgr possde la mme origine que la page englobante, il est fortement dconseill d'utiliser la fois allow-scripts et allow-same-origin, car cela permet au document intgr de retirer l'attribut sandbox le rendant aussi peu sr que de ne pas utiliser sandbox du tout.
• La mise en bac sable est inutile si une attaquante peut afficher du contenu en dehors d'un iframe sandbox par exemple si lea visiteureuse ouvre le cadre dans un nouvel onglet. Un tel contenu doit galement tre servi depuis une origine spare pour limiter les dommages potentiels.

Note : Lorsqu'on redirige l'utilisateurice, ouvre une fentre intrusive ou un nouvel onglet depuis une page intgre dans un <iframe> avec l'attribut sandbox, le nouveau contexte de navigation est envoy aux mmes restrictions sandbox. Cela peut poser des problmes par exemple, si une page intgre dans un <iframe> sans l'attribut sandbox="allow-forms" ou sandbox="allow-popups-to-escape-sandbox" ouvre un nouveau site dans un onglet spar, l'envoi d'un formulaire dans ce nouveau contexte de navigation choue silencieusement.

src

L'URL de la page intgrer. Utilisez la valeur about:blank pour intgrer une page vide conforme la politique de mme 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 bass sur Chromium et Safari/iOS.

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

srcdoc

Le HTML inline intgrer, 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 lments puissent tre omis et que seul le contenu du corps soit conserv. Ce document a pour emplacement about:srcdoc. Si un navigateur ne prend pas en charge l'attribut srcdoc, il utilise l'URL indique par l'attribut src.

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

width

La largeur du cadre en pixels CSS. La valeur par dfaut est 300.

Attributs obsoltes

align

Cet attribut obsolte permettait de dfinir l'alignement d'un cadre intgr (iframe) par rapport son contexte englobant.

frameborder

Lorsqu'il vaut 1 (la valeur par dfaut), cet attribut indique au navigateur de dfinir une bordure entre ce cadre et tout autre cadre. Lorsqu'il vaut 0, aucune bordure n'est dessine. Plutt que cet attribut, on utilise la proprit CSS border pour dessiner la bordure autour d'une iframe.

longdesc

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

marginheight

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

marginwidth

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

scrolling

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

auto

Uniquement lorsque le contenu de la frame dpasse ses dimensions.

yes

Toujours afficher une barre de dfilement.

no

Ne jamais afficher de barre de dfilement.

Scripts

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

En utilisant l'lment HTMLIFrameElement du DOM, les scripts peuvent accder l'objet window de la page HTML incluse par la proprit contentWindow. La proprit contentDocument fait rfrence au document contenu dans l'iframe (l'quivalent de contentWindow.document).

Depuis le cadre intgr (iframe), un script peut obtenir une rfrence la fentre parente avec la proprit window.parent.

Les scripts qui tentent d'accder au contenu du cadre intgr (iframe) doivent respecter les rgles de mme origine. Les scripts ne peuvent pas accder la plupart des proprits des autres objets window s'ils ont t chargs depuis un domaine diffrent. Cela s'applique galement aux scripts d'un cadre intgr qui souhaitent accder au contexte englobant. On peut toutefois communiquer entre diffrents domaines grce la mthode Window.postMessage().

Navigation vers le haut depuis des cadres d'origines diffrentes

Les scripts excuts dans un cadre de mme origine peuvent accder la proprit Window.top et dfinir window.top.location pour rediriger la page de plus haut niveau vers une nouvelle URL. Ce comportement est appel  navigation vers le haut .

Un cadre d'origines diffrentes est autoris rediriger la page de plus haut niveau en utilisant top uniquement si le cadre dispose de activation persistante. Si la navigation vers le haut est bloque, les navigateurs peuvent soit demander l'autorisation de l'utilisateurice pour la redirection, soit consigner l'erreur dans la console de dveloppement (ou les deux). Les navigateurs dsignent cette restriction par le terme framebusting intervention. Concrtement, un cadre d'origines diffrentes ne peut pas rediriger immdiatement la page de plus haut niveau l'utilisateurice doit avoir pralablement interagi avec le cadre ou avoir accord l'autorisation de redirection.

Un cadre en bac sable bloque toute navigation vers le haut moins que les valeurs de l'attribut sandbox ne soient dfinies sur allow-top-navigation ou allow-top-navigation-by-user-activation. Notez que les autorisations de navigation vers le haut sont hrites, un cadre imbriqu ne peut effectuer une navigation vers le haut que si ses cadres parentes y sont galement autorises.

Positionnement et redimensionnement

En tant qu'lment remplac, la position, l'alignement et le redimensionnement du document embarqu avec <iframe> peuvent tre ajusts par la proprit object-position.

Comportement des vnements error et load

Les vnements error et load dclenchs sur des <iframe> pourraient tre utiliss pour sonder l'espace d'URL des serveurs HTTP du rseau local. Par consquent, par mesure de scurit, les agents utilisateur ne dclenchent pas l'vnement error sur les <iframe>, et l'vnement load est toujours dclench mme si le contenu de l'<iframe> choue se charger.

Dimensionnement adaptatif de <iframe>

Pour des raisons de scurit et de confidentialit, les lments <iframe> n'exposent pas par dfaut d'informations au document parent sur la taille du contenu dans le document qu'ils intgrent.

Pour permettre le dimensionnement adaptatif des lments <iframe> en fonction de leur contenu, la balise <meta name="responsive-embedded-sizing"> peut tre incluse dans un document intgr pour lui permettre de partager les informations sur sa taille avec le document parent. La proprit CSS frame-sizing peut ensuite tre dfinie sur l'<iframe> pour qu'il adopte la mme taille horizontale ou verticale que la taille relle du contenu du document intgr. Cela garantit que le contenu d'un <iframe> s'intgre parfaitement dans son conteneur, vitant ainsi les barres de dfilement inutiles.

Pour redimensionner dynamiquement un <iframe> lorsque le document intgr modifie la taille de sa mise en page, vous pouvez appeler la mthode Window.requestResize() depuis le document intgr pour lui faire signaler une taille mise jour.

Accessibilit

Les personnes utilisant des technologies d'assistance telles qu'un lecteur d'cran peuvent utiliser l'attribut title sur un <iframe> pour tiqueter son contenu. La valeur de l'attribut title doit dcrire de manire concise le contenu intgr :

<iframe
  title="Page Wikipedia pour les avocatiers"
  src="https://fr.wikipedia.org/wiki/Avocatier"></iframe>

Sans ce titre, ils doivent naviguer dans un <iframe> pour dterminer quel est le contenu intgr. Ce changement de contexte peut tre droutant et chronophage, en particulier pour les pages comportant plusieurs <iframe> et/ou si les contenus intgrs contiennent du contenu interactif comme de la vido ou de l'audio.

Exemples

Un <iframe> simple

Cet exemple intgre la page https://example.org dans un cadre intgr. C'est un cas d'utilisation courant des cadres intgrs : intgrer du contenu provenant d'un autre site. Par exemple, l'exemple en direct luimme et l'exemple interactif en haut de la page sont tous deux des intgrations <iframe> de contenu provenant d'un autre site MDN.

HTML

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

Rsultat

Intgrer du code source dans un <iframe>

Cet exemple affiche directement du code source dans une iframe. Cela peut tre utilis comme technique pour empcher l'injection de scripts lors de l'affichage de contenu gnr par des utilisateurices, lorsqu'on le combine avec l'attribut sandbox.

Notez que lorsque vous utilisez srcdoc, toutes les URL relatives du contenu intgr sont rsolues par rapport l'URL de la page englobante. Si vous voulez utiliser des liens d'ancrage qui pointent vers des emplacements du contenu intgr, vous devez dfinir 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 manires d'utiliser l'lment <code>iframe</code>&nbsp;:</p>
<ol>
<li><a href=&quot;about:srcdoc#embed_another&quot;>Pour intgrer du contenu provenant d'une autre page</a></li>
<li><a href=&quot;about:srcdoc#embed_user&quot;>Pour intgrer du contenu gnr par les utilisateurices</a></li>
</ol>
<h2 id=&quot;embed_another&quot;>Intgrer du contenu depuis une autre page</h2>
<p>Utilisez l'attribut <code>src</code> pour dfinir l'URL de la page  intgrer&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;>Intgrer du contenu gnr par les utilisateurices</h2>
<p>Utilisez l'attribut <code>srcdoc</code> pour dfinir le contenu  intgrer. Ce billet en est dj un exemple&nbsp;!</p>
"
    width="500"
    height="250"
></iframe>
</article>

Voici comment crire les squences d'chappement lorsque vous utilisez srcdoc :

• Premirement, crivez le HTML en chappant les caractres que vous chappez dans un document HTML normal (par exemple <, >, &, etc.).
• < et < reprsentent exactement le mme caractre dans l'attribut srcdoc. Par consquent, pour en faire une vritable squence 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 prmaturment ferm (si vous utilisez ' la place, remplacez ' par '). Cette tape intervient aprs la prcdente, donc les " gnrs ici ne deviennent pas ".

Rsultat

Rsum technique

Spcifications

Compatibilit des navigateurs

Voir aussi

• CSP : frame-ancestors
• Vie prive, autorisations et scurit de l'information
• Accs au rseau local