Iframe

외부 웹 페이지 또는 내부 서비스 화면을 현재 화면 안에 내장하여 표시하는 인라인 프레임 컴포넌트

개요

Cals Iframe은 Foundation Iframe을 래핑해 기본 높이와 자기 프레임 메시지 수신을 더합니다. src는 소비자가 완성해 넘깁니다.

주요 특징

• ✅ title 필수: 스크린 리더가 읽는 프레임 이름(WCAG 4.1.2)
• ✅ 높이: 기본 250px, height로 바꾸고 부모를 채우려면 className="h-full"
• ✅ 자기 프레임 메시지: onMessage는 이 프레임이 보낸 메시지만 받는다(origin 검사)
• ✅ 표준 iframe 호환: sandbox·allow·referrerPolicy·loading 등 속성과 이벤트를 그대로 전달
• ✅ DOM ref: ref는 iframe 요소

기본 사용

src는 완성된 주소를 넘깁니다. title은 필수입니다(스크린 리더가 읽는 프레임 이름). 기본 높이는 250px입니다.

<Iframe title="업무 화면" src="https://example.com" />

높이 (height / className)

height(number → px)는 루트 높이가 됩니다. className 높이(예: h-full로 부모 높이를 채움)도 기본 250px을 이깁니다. style.height가 있으면 그 값이 이깁니다.

<Iframe title="높은 화면" src="https://example.com" height={400} />
 
<div className="h-[400px] border p-2">
  <Iframe title="부모를 채우는 화면" src="https://example.com" className="h-full" />
</div>

프레임 메시지 (onMessage)

onMessage(data, event)는 이 프레임(contentWindow)이 보낸 메시지만 받습니다. origin은 기본으로 src의 origin과 비교하고, messageOrigin으로 바꿉니다("*"는 명시할 때만). 프레임에 보낼 때는 ref의 contentWindow를 씁니다. 메시지 해석은 소비자가 합니다.

const frameRef = useRef<HTMLIFrameElement>(null)
 
<button onClick={() => frameRef.current?.contentWindow?.postMessage({ method: "refresh" }, "*")}>
  프레임에 보내기
</button>
<Iframe
  ref={frameRef}
  title="메시지 주고받기"
  srcDoc={doc}
  messageOrigin="*" // src 가 없어 기본 origin 을 정할 수 없으므로 messageOrigin 을 준다
  onMessage={(data) => {
    if ((data as { method?: string })?.method === "close") close()
  }}
/>

보안 속성 (sandbox / allow)

sandbox·allow·referrerPolicy에 기본값을 두지 않고 그대로 넘깁니다. 값은 화면마다 정합니다. 사용자 입력 URL의 검증은 소비자 몫이고, javascript: 주소는 React가 막습니다.

sandbox에 allow-same-origin이 없으면 프레임이 보낸 메시지의 origin은 "null"이라 기본값(src의 origin)으로는 받지 않습니다. 받으려면 messageOrigin="null"(또는 "*")을 줍니다.

<Iframe title="격리된 화면" src="https://example.com" sandbox="allow-scripts" referrerPolicy="no-referrer" />

API Reference

Props

표에 없는 iframe 속성(sandbox·allow·loading·referrerPolicy·name 등)은 iframe에 그대로 갑니다. name을 주면 프레임 이름(window.name, 링크·폼 target)이 됩니다.

Ref

ref는 iframe DOM 요소(HTMLIFrameElement)입니다. 프레임에 메시지를 보낼 때는 ref.current.contentWindow.postMessage를 씁니다(「프레임 메시지」 절 참고).

접근성

권장 사항

• ✅ title(필수)이 iframe의 accessible name이 됩니다.
• ✅ 외부 페이지 내용을 설명할 수 있는 의미 있는 제목을 사용합니다.
• ✅ 한 화면에 프레임이 여럿이면 title을 서로 다르게 줍니다. 스크린 리더가 프레임을 이름으로 구분합니다.
• ✅ 보안 정책상 필요한 경우 sandbox, referrerPolicy, allow 등의 표준 iframe 속성을 함께 지정합니다.
• ❌ 제목 없는 iframe을 사용하지 않습니다.

관련 컴포넌트

• Foundation Iframe: 기본 iframe 컴포넌트