다이얼로그

파일 열기 및 저장, 경고창 등 시스템 기본 다이얼로그를 표시한다.

프로세스: 메인

여러 파일을 선택하는 다이얼로그를 표시하는 예제:

const { dialog } = require('electron')
console.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] }))

메서드

dialog 모듈은 다음과 같은 메서드를 제공한다:

dialog.showOpenDialogSync([window, ]options)

• window BaseWindow (선택 사항)
• options Object
  • title string (선택 사항)
  • defaultPath string (선택 사항)
  • buttonLabel string (선택 사항) - 확인 버튼에 사용할 커스텀 라벨. 비워두면 기본 라벨이 사용된다.
  • filters FileFilter[] (선택 사항)
  • properties string[] (선택 사항) - 다이얼로그가 사용할 기능을 지정한다. 다음 값을 지원한다:
    • openFile - 파일 선택을 허용한다.
    • openDirectory - 디렉토리 선택을 허용한다.
    • multiSelections - 여러 경로 선택을 허용한다.
    • showHiddenFiles - 다이얼로그에서 숨겨진 파일을 표시한다.
    • createDirectory macOS - 다이얼로그에서 새로운 디렉토리 생성을 허용한다.
    • promptToCreate Windows - 다이얼로그에 입력한 파일 경로가 존재하지 않을 경우 생성 프롬프트를 표시한다. 이 옵션은 실제로 파일을 생성하지는 않지만, 애플리케이션에서 생성해야 할 존재하지 않는 경로를 반환한다.
    • noResolveAliases macOS - 자동으로 심볼릭 링크 경로를 해석하지 않는다. 선택한 심볼릭 링크는 대상 경로 대신 심볼릭 링크 경로를 반환한다.
    • treatPackageAsDirectory macOS - .app 폴더와 같은 패키지를 파일이 아닌 디렉토리로 처리한다.
    • dontAddToRecent Windows - 열린 항목을 최근 문서 목록에 추가하지 않는다.
  • message string (선택 사항) macOS - 입력 상자 위에 표시할 메시지.
  • securityScopedBookmarks boolean (선택 사항) macOS MAS - Mac App Store용으로 패키징할 때 보안 범위 북마크를 생성한다.

사용자가 선택한 파일 경로를 string[] | undefined로 반환한다. 다이얼로그가 취소되면 undefined를 반환한다.

window 인자는 다이얼로그가 부모 윈도우에 연결되도록 하여 모달로 동작하게 한다.

filters는 사용자를 특정 파일 타입으로 제한할 때 표시하거나 선택할 수 있는 파일 타입 배열을 지정한다. 예를 들어:

{
  filters: [
    { name: 'Images', extensions: ['jpg', 'png', 'gif'] },
    { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },
    { name: 'Custom File Type', extensions: ['as'] },
    { name: 'All Files', extensions: ['*'] }
  ]
}

extensions 배열은 와일드카드나 점 없이 확장자를 포함해야 한다 (예: 'png'는 유효하지만 '.png'와 '*.png'는 유효하지 않다). 모든 파일을 표시하려면 '*' 와일드카드를 사용한다 (다른 와일드카드는 지원되지 않는다).

참고: Windows와 Linux에서는 파일 선택기와 디렉토리 선택기를 동시에 사용할 수 없다. 따라서 properties를 ['openFile', 'openDirectory']로 설정하면 디렉토리 선택기가 표시된다.

dialog.showOpenDialogSync(mainWindow, {
  properties: ['openFile', 'openDirectory']
})

참고: Linux에서 포털 파일 선택기 다이얼로그를 사용할 때 defaultPath는 포털 백엔드 버전이 4 이상인 경우에만 지원된다. --xdg-portal-required-version 커맨드라인 스위치를 사용해 gtk 또는 kde 다이얼로그를 강제로 사용할 수 있다.

dialog.showOpenDialog([window, ]options)

• window BaseWindow (선택사항)
• options Object
  • title string (선택사항)
  • defaultPath string (선택사항)
  • buttonLabel string (선택사항) - 확인 버튼에 사용할 커스텀 라벨. 비워두면 기본 라벨이 사용된다.
  • filters FileFilter[] (선택사항)
  • properties string[] (선택사항) - 다이얼로그에서 사용할 기능을 지정한다. 지원되는 값은 다음과 같다:
    • openFile - 파일 선택을 허용한다.
    • openDirectory - 디렉터리 선택을 허용한다.
    • multiSelections - 여러 경로 선택을 허용한다.
    • showHiddenFiles - 다이얼로그에서 숨겨진 파일을 표시한다.
    • createDirectory macOS - 다이얼로그에서 새 디렉터리 생성이 가능하다.
    • promptToCreate Windows - 다이얼로그에 입력한 파일 경로가 존재하지 않을 경우 생성 프롬프트를 표시한다. 실제로 파일을 생성하지는 않지만, 애플리케이션에서 생성해야 할 존재하지 않는 경로를 반환한다.
    • noResolveAliases macOS - 자동으로 별칭(심볼릭 링크) 경로를 해석하지 않는다. 선택한 별칭은 대상 경로 대신 별칭 경로를 반환한다.
    • treatPackageAsDirectory macOS - .app 폴더와 같은 패키지를 파일이 아닌 디렉터리로 취급한다.
    • dontAddToRecent Windows - 열린 항목을 최근 문서 목록에 추가하지 않는다.
  • message string (선택사항) macOS - 입력 상자 위에 표시할 메시지.
  • securityScopedBookmarks boolean (선택사항) macOS MAS - Mac App Store용으로 패키징할 때 보안 범위 북마크를 생성한다.

Promise<Object>를 반환하며, 다음 속성을 가진 객체로 resolve된다:

• canceled boolean - 다이얼로그가 취소되었는지 여부.
• filePaths string[] - 사용자가 선택한 파일 경로 배열. 다이얼로그가 취소되면 빈 배열이 반환된다.
• bookmarks string[] (선택사항) macOS MAS - filePaths 배열과 일치하는 base64로 인코딩된 보안 범위 북마크 데이터 배열. securityScopedBookmarks가 활성화되어야 이 값이 채워진다. (반환 값에 대한 자세한 내용은 여기를 참조.)

window 인자는 다이얼로그가 부모 윈도우에 연결되어 모달로 동작하도록 한다.

filters는 사용자가 특정 타입의 파일만 선택할 수 있도록 제한하는 파일 타입 배열을 지정한다. 예를 들어:

{
  filters: [
    { name: 'Images', extensions: ['jpg', 'png', 'gif'] },
    { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },
    { name: 'Custom File Type', extensions: ['as'] },
    { name: 'All Files', extensions: ['*'] }
  ]
}

extensions 배열은 와일드카드나 점 없이 확장자를 포함해야 한다 (예: 'png'는 가능하지만 '.png'와 '*.png'는 불가능). 모든 파일을 표시하려면 '*' 와일드카드를 사용한다 (다른 와일드카드는 지원되지 않음).

참고: Windows와 Linux에서는 파일 선택기와 디렉터리 선택기를 동시에 사용할 수 없으므로, properties를 ['openFile', 'openDirectory']로 설정하면 디렉터리 선택기가 표시된다.

dialog.showOpenDialog(mainWindow, {
  properties: ['openFile', 'openDirectory']
}).then(result => {
  console.log(result.canceled)
  console.log(result.filePaths)
}).catch(err => {
  console.log(err)
})

참고: Linux에서는 포털 파일 선택기 다이얼로그를 사용할 때 defaultPath가 지원되지 않는다. 단, 포털 백엔드가 버전 4 이상인 경우는 예외다. --xdg-portal-required-version 커맨드라인 스위치를 사용해 gtk 또는 kde 다이얼로그를 강제로 사용할 수 있다.

dialog.showSaveDialogSync([window, ]options)

• window BaseWindow (선택 사항)
• options Object
  • title string (선택 사항) - 대화 상자 제목. 일부 Linux 데스크톱 환경에서는 표시되지 않을 수 있다.
  • defaultPath string (선택 사항) - 기본으로 사용할 절대 디렉터리 경로, 절대 파일 경로, 또는 파일 이름.
  • buttonLabel string (선택 사항) - 확인 버튼에 사용할 커스텀 라벨. 비워 두면 기본 라벨이 사용된다.
  • filters FileFilter[] (선택 사항)
  • message string (선택 사항) macOS - 텍스트 필드 위에 표시할 메시지.
  • nameFieldLabel string (선택 사항) macOS - 파일 이름 텍스트 필드 앞에 표시할 커스텀 라벨.
  • showsTagField boolean (선택 사항) macOS - 태그 입력 상자를 표시한다. 기본값은 true.
  • properties string[] (선택 사항)
    • showHiddenFiles - 대화 상자에서 숨겨진 파일을 표시한다.
    • createDirectory macOS - 대화 상자에서 새로운 디렉터리 생성이 가능하다.
    • treatPackageAsDirectory macOS - .app 폴더와 같은 패키지를 파일이 아닌 디렉터리로 취급한다.
    • showOverwriteConfirmation Linux - 사용자가 이미 존재하는 파일 이름을 입력할 경우 확인 대화 상자를 표시할지 여부를 설정한다.
    • dontAddToRecent Windows - 저장 중인 항목을 최근 문서 목록에 추가하지 않는다.
  • securityScopedBookmarks boolean (선택 사항) macOS MAS - Mac App Store용으로 패키징할 때 보안 범위 북마크를 생성한다. 이 옵션이 활성화되고 파일이 아직 존재하지 않으면 선택한 경로에 빈 파일이 생성된다.

string을 반환한다. 사용자가 선택한 파일의 경로를 반환하며, 대화 상자가 취소되면 빈 문자열을 반환한다.

window 인자는 대화 상자가 부모 윈도우에 연결되어 모달로 동작하도록 한다.

filters는 표시할 수 있는 파일 타입의 배열을 지정한다. 예제는 dialog.showOpenDialog를 참고한다.

dialog.showSaveDialog([window, ]options)

• window BaseWindow (옵션)
• options Object
  • title string (옵션) - 다이얼로그 제목. 일부 Linux 데스크탑 환경에서는 표시되지 않을 수 있다.
  • defaultPath string (옵션) - 기본으로 사용할 절대 디렉토리 경로, 절대 파일 경로 또는 파일 이름.
  • buttonLabel string (옵션) - 확인 버튼에 사용할 커스텀 라벨. 비어 있을 경우 기본 라벨이 사용된다.
  • filters FileFilter[] (옵션)
  • message string (옵션) macOS - 텍스트 필드 위에 표시할 메시지.
  • nameFieldLabel string (옵션) macOS - 파일 이름 텍스트 필드 앞에 표시할 커스텀 라벨.
  • showsTagField boolean (옵션) macOS - 태그 입력 상자를 표시할지 여부. 기본값은 true.
  • properties string[] (옵션)
    • showHiddenFiles - 다이얼로그에서 숨겨진 파일을 표시한다.
    • createDirectory macOS - 다이얼로그에서 새로운 디렉토리 생성이 가능하다.
    • treatPackageAsDirectory macOS - .app 폴더와 같은 패키지를 파일이 아닌 디렉토리로 처리한다.
    • showOverwriteConfirmation Linux - 사용자가 이미 존재하는 파일 이름을 입력할 경우 확인 다이얼로그를 표시할지 여부를 설정한다.
    • dontAddToRecent Windows - 저장된 항목을 최근 문서 목록에 추가하지 않는다.
  • securityScopedBookmarks boolean (옵션) macOS MAS - Mac App Store용으로 패키징할 때 보안 범위 북마크를 생성한다. 이 옵션이 활성화되고 파일이 아직 존재하지 않으면 선택한 경로에 빈 파일이 생성된다.

Promise<Object>를 반환하며, 다음을 포함하는 객체로 resolve된다:

• canceled boolean - 다이얼로그가 취소되었는지 여부.
• filePath string - 다이얼로그가 취소된 경우 빈 문자열이 반환된다.
• bookmark string (옵션) macOS MAS - 저장된 파일에 대한 보안 범위 북마크 데이터를 포함한 Base64 인코딩 문자열. 이 값이 존재하려면 securityScopedBookmarks가 활성화되어 있어야 한다. (반환 값에 대한 자세한 내용은 여기의 표를 참조.)

window 인자는 다이얼로그가 부모 윈도우에 연결되어 모달로 동작하도록 한다.

filters는 표시할 수 있는 파일 타입 배열을 지정한다. 예제는 dialog.showOpenDialog를 참조.

참고: macOS에서는 다이얼로그를 확장하고 축소할 때 발생할 수 있는 문제를 피하기 위해 비동기 버전을 사용하는 것이 권장된다.

dialog.showMessageBoxSync([window, ]options)

• window BaseWindow (옵션)
• options Object
  • message string - 메시지 박스의 내용.
  • type string (옵션) - none, info, error, question, warning 중 하나. 윈도우에서는 question이 info와 같은 아이콘을 표시하지만, icon 옵션을 사용해 아이콘을 설정할 수 있다. macOS에서는 warning과 error가 동일한 경고 아이콘을 표시한다.
  • buttons string[] (옵션) - 버튼에 표시할 텍스트 배열. 윈도우에서는 빈 배열일 경우 "OK" 라벨의 버튼 하나가 생성된다.
  • defaultId Integer (옵션) - 메시지 박스가 열릴 때 기본으로 선택될 버튼의 인덱스.
  • title string (옵션) - 메시지 박스의 제목. 일부 플랫폼에서는 표시되지 않을 수 있다.
  • detail string (옵션) - 메시지의 추가 정보.
  • icon (NativeImage | string) (옵션)
  • textWidth Integer (옵션) macOS - 메시지 박스 내 텍스트의 커스텀 너비.
  • cancelId Integer (옵션) - Esc 키를 통해 다이얼로그를 취소할 때 사용할 버튼의 인덱스. 기본적으로 "cancel" 또는 "no" 라벨이 있는 첫 번째 버튼이 할당된다. 해당 라벨이 없는 버튼이 존재하고 이 옵션이 설정되지 않았을 경우, 반환 값으로 0이 사용된다.
  • noLink boolean (옵션) - 윈도우에서 Electron은 buttons 중 일반적인 버튼(예: "Cancel" 또는 "Yes")을 식별하고 나머지를 커맨드 링크로 표시한다. 이는 다이얼로그를 모던 윈도우 앱 스타일로 보이게 한다. 이 동작을 원하지 않으면 noLink를 true로 설정할 수 있다.
  • normalizeAccessKeys boolean (옵션) - 플랫폼 간 키보드 접근 키를 정규화한다. 기본값은 false. 이 옵션을 활성화하면 버튼 라벨에서 &가 키보드 단축키 접근 키 위치로 사용되고, 라벨은 각 플랫폼에서 올바르게 동작하도록 변환된다. macOS에서는 & 문자가 제거되고, Linux에서는 _로 변환되며, 윈도우에서는 그대로 유지된다. 예를 들어, Vie&w라는 버튼 라벨은 Linux에서 Vie_w로, macOS에서는 View로 변환되며, 윈도우와 Linux에서는 Alt-W로 선택할 수 있다.

반환 값 Integer - 클릭한 버튼의 인덱스.

메시지 박스를 표시하며, 메시지 박스가 닫힐 때까지 프로세스를 블로킹한다. 클릭한 버튼의 인덱스를 반환한다.

window 인자를 사용하면 다이얼로그가 부모 윈도우에 모달로 연결된다. window가 표시되지 않으면 다이얼로그는 독립적인 윈도우로 표시된다.

dialog.showMessageBox([window, ]options)

• window BaseWindow (선택 사항)
• options Object
  • message string - 메시지 박스의 내용.
  • type string (선택 사항) - none, info, error, question, warning 중 하나. 윈도우에서는 question이 info와 동일한 아이콘을 표시하지만, icon 옵션으로 아이콘을 설정할 수 있다. macOS에서는 warning과 error가 동일한 경고 아이콘을 표시한다.
  • buttons string[] (선택 사항) - 버튼의 텍스트 배열. 윈도우에서 빈 배열을 사용하면 "OK" 라벨이 붙은 단일 버튼이 생성된다.
  • defaultId Integer (선택 사항) - 메시지 박스가 열릴 때 기본으로 선택될 버튼의 인덱스.
  • signal AbortSignal (선택 사항) - AbortSignal 인스턴스를 전달하면 메시지 박스를 취소할 수 있다. 이 경우, 메시지 박스는 사용자가 취소한 것처럼 동작한다. macOS에서는 부모 윈도우가 없는 메시지 박스에서 signal이 동작하지 않는다. 이러한 메시지 박스는 플랫폼 제약으로 인해 동기적으로 실행되기 때문이다.
  • title string (선택 사항) - 메시지 박스의 제목. 일부 플랫폼에서는 표시되지 않을 수 있다.
  • detail string (선택 사항) - 메시지의 추가 정보.
  • checkboxLabel string (선택 사항) - 이 값을 제공하면 메시지 박스에 체크박스가 포함된다. 체크박스의 라벨은 이 값으로 설정된다.
  • checkboxChecked boolean (선택 사항) - 체크박스의 초기 상태. 기본값은 false.
  • icon (NativeImage | string) (선택 사항)
  • textWidth Integer (선택 사항) macOS - 메시지 박스 내 텍스트의 커스텀 너비.
  • cancelId Integer (선택 사항) - Esc 키를 통해 다이얼로그를 취소할 때 사용할 버튼의 인덱스. 기본적으로 "cancel" 또는 "no" 라벨이 붙은 첫 번째 버튼이 이 역할을 한다. 해당 라벨이 없는 버튼이 있고 이 옵션이 설정되지 않았다면, 0이 반환 값으로 사용된다.
  • noLink boolean (선택 사항) - 윈도우에서 Electron은 buttons 중 일반적인 버튼(예: "Cancel" 또는 "Yes")을 식별하고, 나머지를 다이얼로그에서 커맨드 링크로 표시한다. 이를 통해 다이얼로그가 모던 윈도우 앱 스타일로 표시된다. 이 동작을 원하지 않으면 noLink를 true로 설정한다.
  • normalizeAccessKeys boolean (선택 사항) - 플랫폼 간 키보드 접근 키를 정규화한다. 기본값은 false. 이 옵션을 활성화하면 버튼 라벨에서 &를 사용해 키보드 단축키 접근 키를 배치할 수 있다. 라벨은 각 플랫폼에서 올바르게 동작하도록 변환된다. macOS에서는 & 문자가 제거되고, 리눅스에서는 _로 변환되며, 윈도우에서는 그대로 유지된다. 예를 들어, Vie&w 라벨은 리눅스에서 Vie_w, macOS에서는 View로 변환된다. 윈도우와 리눅스에서는 Alt-W로 선택할 수 있다.

반환 값: Promise<Object> - 다음 속성을 포함하는 Promise를 반환한다:

• response number - 클릭한 버튼의 인덱스.
• checkboxChecked boolean - checkboxLabel이 설정된 경우 체크박스의 상태. 그렇지 않으면 false.

메시지 박스를 표시한다.

window 인자는 다이얼로그가 부모 윈도우에 모달로 연결되도록 한다.

dialog.showErrorBox(title, content)

• title string - 에러 박스에 표시할 제목
• content string - 에러 박스에 표시할 텍스트 내용

에러 메시지를 보여주는 모달 대화 상자를 표시한다.

이 API는 app 모듈이 ready 이벤트를 발생시키기 전에도 안전하게 호출할 수 있다. 주로 애플리케이션 시작 초기 단계에서 발생한 오류를 보고하는 데 사용된다. 만약 Linux에서 앱이 ready 이벤트를 발생시키기 전에 이 API를 호출하면, 메시지는 stderr로 출력되고 GUI 대화 상자는 나타나지 않는다.

dialog.showCertificateTrustDialog([window, ]options) macOS Windows

• window BaseWindow (선택 사항)
• options Object
  • certificate Certificate - 신뢰하거나 가져올 인증서
  • message string - 사용자에게 표시할 메시지

Promise<void>를 반환한다. 인증서 신뢰 대화 상자가 표시되면 resolve된다.

macOS에서는 이 함수가 모달 대화 상자를 표시한다. 이 대화 상자는 메시지와 인증서 정보를 보여주며, 사용자가 인증서를 신뢰하거나 가져올 수 있는 옵션을 제공한다. window 인자를 제공하면 대화 상자가 부모 윈도우에 연결되어 모달로 동작한다.

Windows에서는 사용된 Win32 API로 인해 기능이 제한된다:

• message 인자는 사용되지 않는다. 운영체제가 자체적인 확인 대화 상자를 제공하기 때문이다.
• window 인자는 무시된다. 이 확인 대화 상자를 모달로 만들 수 없기 때문이다.

북마크 배열

showOpenDialog, showOpenDialogSync, showSaveDialog, 그리고 showSaveDialogSync 함수는 bookmarks 배열을 반환한다.

빌드 타입	securityScopedBookmarks 불리언	반환 타입	반환 값
macOS mas	True	성공	['LONGBOOKMARKSTRING']
macOS mas	True	오류	[''] (빈 문자열 배열)
macOS mas	False	해당 없음	[] (빈 배열)
non mas	any	해당 없음	[] (빈 배열)

시트

macOS에서 다이얼로그는 window 매개변수에 BaseWindow 참조를 제공하면 윈도우에 부착된 시트로 표시된다. 윈도우를 제공하지 않으면 모달로 나타난다.

BaseWindow.getCurrentWindow().setSheetOffset(offset)를 호출해 시트가 윈도우 프레임에 부착되는 위치의 오프셋을 조정할 수 있다.