HTML <iframe>: 인라인 프레임 요소

HTML <iframe> 요소는 현재 페이지에 다른 브라우징 맥락, 즉 HTML 페이지를 삽입할 수 있습니다.

<iframe
  title="인라인 프레임 예제"
  width="300"
  height="200"
  src="https://www.openstreetmap.org/export/embed.html?bbox=126.36909487657252%2C37.22035149975492%2C127.71492007188502%2C37.892603243609926&amp;layer=mapnik"
></iframe>

<iframe>으로 삽입한 각각의 브라우징 맥락은 자신만의 세션 기록과 문서를 가집니다. 최상위 브라우징 맥락, 즉 아무데도 삽입되지 않은 브라우징 맥락은 대개 Window 객체로 표현되는 브라우저 창입니다.

특성

전역 특성을 포함합니다.

allow

<iframe>의 기능 정책을 지정합니다. 기능 정책은 <iframe> 내에서 요청의 출처에 따라서, 사용 가능한 기능(마이크와 카메라 접근, 배터리와 웹 공유 API 등)을 정의합니다.

기능 정책 사용하기의 iframe allow 특성을 참고하세요.

allowfullscreen

true를 지정하면 프레임 내에서 requestFullscreen()을 호출했을 때 전체화면 모드로 들어갑니다.

이 특성은 레거시로 분류됩니다. allow="fullscreen"을 사용하세요.

allowpaymentrequest

true를 지정하면 프레임 내에서 Payment Request API를 호출할 수 있습니다.

이 특성은 레거시로 분류됩니다. allow="payment"를 사용하세요.

csp

프레임 내에 강제하는 콘텐츠 보안 정책입니다. HTMLIFrameElement.csp를 참고하세요.

fetchpriority

문서를 가져올 때의 우선순위에 대한 힌트를 브라우저에 제공합니다. 가능한 값은 다음과 같습니다.

high

다른 문서에 비해 높은 우선순위로 가져와야 함을 표시합니다.

low

다른 문서에 비해 낮은 우선순위로 가져와야 함을 표시합니다.

auto

기본 값입니다. 브라우저가 우선순위를 자동으로 판단합니다.

height

프레임의 CSS 픽셀 단위 높이입니다. 기본 값은 150입니다.

loading

브라우저가 프레임을 불러오는 방식을 지정합니다.

• eager: 프레임을 즉시 불러옵니다. 현재 뷰포트에서 프레임을 볼 수 있는지는 고려하지 않습니다. 기본 값입니다.
• lazy: 뷰포트에서 브라우저가 계산한 특정 거리 내에 프레임이 들어오기 전까지 불러오기를 지연합니다

name

삽입한 브라우징 맥락을 선택할 때 사용할 수 있는 이름입니다. <a>, <form>, <base>의 target 특성, <input>, <button>의 formtarget 특성, window.open() 메서드의 windowName 매개변수로 지정할 수 있습니다.

referrerpolicy

리소스를 가져올 때 사용할 리퍼러(referrer)를 지정합니다. 다음 값을 사용해야 합니다.

• no-referrer: Referer 헤더를 전송하지 않습니다.
• no-referrer-when-downgrade: TLS(HTTPS) 지원을 하지 않는 출처에 대해서는 Referer 헤더를 전송하지 않습니다.
• origin: Referer 헤더가 요청의 출처, 즉 스킴, 호스트, 포트를 포함합니다.
• origin-when-cross-origin: 다른 출처로 요청할 땐 리퍼러 데이터를 스킴, 호스트, 포트로 제한합니다. 동일 출처로 요청할 땐 전체 경로도 포함합니다.
• same-origin: 동일 출처 요청에는 리퍼러를 전송하고, 교차 출처 요청에는 전송하지 않습니다.
• strict-origin: 보안 수준이 동일(HTTPS→HTTPS)할 땐 문서의 출처를 리퍼러로 전송하고, 더 낮을(HTTPS→HTTP) 땐 전송하지 않습니다.
• strict-origin-when-cross-origin (기본 값): 동일 출처 요청에는 전체 URL을 전송합니다. 교차 출처 요청에 대해서는 보안 수준이 동일(HTTPS→HTTPS)할 땐 문서의 출처를 리퍼러로 전송하고, 더 낮을(HTTPS→HTTP) 땐 전송하지 않습니다.
• unsafe-url: 리퍼러가 항상 출처, 경로, 쿼리 문자열을 포함합니다. 프래그먼트, 비밀번호, 사용자 이름은 포함하지 않습니다. 안전하지 않은 값입니다. TLS로 보호받는 리소스에서 보호 없는 출처로 정보가 누출될 수 있습니다.

sandbox

프레임 콘텐츠에 추가 제약을 설정합니다. 빈 문자열을 지정하면 모든 제약을 설정합니다. 아래 값을 공백으로 구분해 지정하면 해당하는 제약만 해제할 수 있습니다.

• allow-downloads-without-user-activation : 사용자 입력 없는 다운로드를 허용합니다.

• allow-downloads: 사용자의 입력을 통한 다운로드를 허용합니다.

• allow-forms: 양식 제출을 허용합니다.

• allow-modals: 프레임 내에서 모달 창을 열 수 있습니다.

• allow-orientation-lock: 프레임 내에서 화면 방향을 고정할 수 있습니다.

• allow-pointer-lock: 프레임에서 Pointer Lock API를 사용할 수 있습니다.

• allow-popups: 프레임 내에서 팝업(window.open(), target="_blank")을 열 수 있습니다.

• allow-popups-to-escape-sandbox: 프레임 내에서 샌드박스 제약을 상속하지 않는 새로운 창을 열 수 있습니다. 이 값을 사용하면 광고 프레임을 안전하게 샌드박싱하면서, 광고가 가리키는 링크는 제약하지 않을 수 있습니다.

• allow-presentation: 프레임이 프레젠테이션 세션을 시작할 수 있습니다.

• allow-same-origin: 이 값을 지정하지 않으면, 프레임의 출처를 동일 출처 정책에 항상 실패하는 특수 출처로 지정합니다. (데이터 저장소와 쿠키에 접근할 수 없고, 및 일부 JavaScript API가 실패할 수 있습니다)

• allow-scripts: 프레임이 스크립트를 실행할 수 있습니다. (팝업은 열 수 없습니다)

• allow-storage-access-by-user-activation : 프레임 내에서 Storage Access API를 통해 부모의 저장소에 접근할 수 있습니다.

• allow-top-navigation: 프레임 내에서 최상위 브라우징 맥락의 탐색을 유발할 수 있습니다. (target="_top")

• allow-top-navigation-by-user-activation: 프레임 내에서 사용자의 입력을 통한 최상위 브라우징 맥락의 탐색을 유발할 수 있습니다.

• 프레임 내의 문서가 부모와 같은 출처라면 allow-scripts와 allow-same-origin을 함께 쓰지 않아야 합니다. 두 값을 동시에 지정할 경우 프레임 내에서 <iframe>의 sandbox 특성을 제거할 수 있으므로, 특성을 쓰지 않은 것과 비교했을 때 보안 차이가 없어집니다.
• 공격자가 콘텐츠를 샌드박스 프레임 밖에 표시할 수 있으면, 예컨대 사용자가 프레임을 새 탭에서 열게 되면, 샌드박싱이 무의미해집니다. 따라서 신뢰할 수 없는 콘텐츠는 잠재적인 피해를 제한할 수 있도록 분리된 출처에서 제공해야 합니다.

src

삽입할 페이지의 URL입니다. about:blank를 지정하면 동일 출처 정책을 준수하는 빈 페이지를 삽입할 수 있습니다. 코드(Element.removeAttribute() 등)를 통해 <iframe>의 src 특성을 제거하는 경우에도 프레임은 about:blank를 불러옵니다.

srcdoc

삽입할 인라인 HTML 코드입니다. src 특성보다 우선합니다. 브라우저가 srcdoc을 지원하지 않을 경우 src 특성의 URL을 대신 불러옵니다.

width

프레임의 CSS 픽셀 단위 높이입니다. 기본 값은 300입니다.

사용 일람

스크립팅

프레임의 window 객체에 접근하려면 <iframe>의 DOM HTMLIFrameElement 객체 contentWindow 속성을 사용하세요. 마찬가지로 contentDocument로 프레임의 document를 가져올 수 있습니다.

프레임 내에서 부모의 window에 접근해야 하면 window.parent를 사용하세요.

프레임 내부에 대한 스크립트 접근은 동일 출처 정책의 적용 대상입니다. 스크립트는 자신과 다른 출처의 window에 대해서는 대부분의 속성에 접근할 수 없습니다. 프레임 내에서 부모의 window에 접근할 때도 마찬가지입니다. window간 교차 출처 통신은 postMessage()를 사용하세요.

CSS 스타일링

<iframe>은 대체 요소로, CSS object-position과 object-fit 속성을 사용해 삽입한 문서의 위치와 정렬, 크기를 조절할 수 있습니다.

접근성 고려사항

스크린 리더와 같은 보조 기술은 <iframe>의 title을 사용해 내부 콘텐츠를 설명할 수 있습니다. title의 값은 콘텐츠를 명확하게 나타내야 합니다.

<iframe title="아보카도에 대한 위키백과 페이지" src="https://ko.wikipedia.org/wiki/아보카도"></iframe>

title이 없으면, 보조 기술 사용자는 <iframe> 내부를 탐색해 무슨 콘텐츠인지 확인해야 합니다. 이때 발생하는 맥락의 변화는 시간도 오래 걸릴 뿐더러 혼란스럽기 쉽습니다. 프레임 내에 비디오나 오디오 등 대화형 콘텐츠가 있거나, 한 페이지가 다수의 <iframe>을 포함하는 경우 더 심각한 문제입니다.

명세

HTML Living Standard

브라우저 호환성