Dialog
showModal()로 여는 가운데 정렬 네이티브 <dialog>입니다. open으로 제어하거나, defaultOpen으로 비제어 방식으로 둘 수 있습니다. Escape와 배경 클릭으로 닫기는 기본으로 켜져 있고 끌 수 있습니다. 시트로 변하지 않습니다.
열릴 때는 200ms 동안 opacity가 변합니다. 지원되는 곳에서는 @starting-style을 쓰고, data-entered가 대체 수단이라 지원하지 않는 엔진에서도 전환이 일어납니다. 닫힐 때는 transitionend까지 마운트된 채로 있습니다(대체 시간 160ms).
다크, compact, 배경 클릭으로 닫기 꺼짐.
오버레이는 ThemeProvider / DensityProvider에서 토큰을 상속합니다. 프로바이더 노드에 붙은 추가 클래스는 상속하지 않습니다.
iOS에서는 열린 오버레이 뒤의 페이지가 여전히 고무줄처럼 튕길 수 있습니다. Chrome은 사용자 활성화가 없으면 cancel.preventDefault()를 무시할 수 있습니다. 그래도 상태는 네이티브 close 이벤트로 다시 동기화됩니다.
언제 쓰나요
언제: 가운데 정렬 모달 작업이나 확인(네이티브 <dialog>, 제어 open 또는 비제어 defaultOpen). 이름은 Dialog.Title이나 aria-label로 붙입니다. Escape와 배경 클릭으로 닫기가 기본입니다.
쓰지 않을 때: 아래에서 올라오는 모바일 선택기 → BottomSheet. 높이를 가득 채우는 사이드 패널 → Drawer. 앵커에 고정된 비모달 패널 → Popover. 짧은 힌트 → Tooltip. 모바일에서 시트로 바뀌어야 할 때(Dialog는 절대 모양이 바뀌지 않습니다).
Props
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| open | boolean | 아니요 | — | 제어 열림 상태. 비제어 대화상자에서는 생략하세요. |
| defaultOpen | boolean | 아니요 | false | 비제어일 때 마운트 시 대화상자를 엽니다. 트리거 파트가 없어서 한 번 닫히면 다시 마운트해야 다시 열립니다. |
| onOpenChange | (open: boolean, reason: DialogCloseReason) => void | 아니요 | — | 닫기 요청. 제어 방식에서 열린 상태를 유지하면 대화상자가 열린 채로 남습니다. 이유: escape, backdrop, close-button, form(<form method="dialog"> 제출. 제출한 요소의 값은 요소의 returnValue에 있습니다), native(다른 무언가가 요소를 닫음). |
| dismissOnEscape | boolean | 아니요 | true | Escape가 onOpenChange(false, "escape")를 호출합니다. |
| dismissOnBackdrop | boolean | 아니요 | true | 스크림 클릭이 onOpenChange(false, "backdrop")을 호출합니다. |
| aria-label | string | 아니요 | — | Dialog.Title을 생략했을 때의 이름. |
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| children | React.ReactNode | 아니요 | — | 제목 텍스트. |
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| children | React.ReactNode | 아니요 | — | 설명 텍스트. |
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| aria-label | string | 아니요 | "Close" when its text, not counting aria-hidden or SVG parts, has fewer than two letters or digits | 접근 가능한 이름. "Cancel"처럼 글자나 숫자가 두 개 이상인 텍스트가 있으면 그 텍스트가 버튼의 이름이 됩니다. 그렇지 않으면 StringsProvider의 close 문자열이 이름이 되며, 영어로는 Close입니다. |
| onClick | React.MouseEventHandler<HTMLButtonElement> | 아니요 | — | 닫기 요청 전에 실행됩니다. 대화상자를 열어 두려면 event.preventDefault()를 호출하세요. |