nativeImage

PNG 또는 JPG 파일을 사용해 트레이, 독, 애플리케이션 아이콘을 생성한다.

프로세스: Main, Renderer

nativeImage 모듈은 시스템 이미지를 조작하기 위한 통합 인터페이스를 제공한다. 동일한 아이콘의 여러 크기 버전을 제공하거나 macOS 템플릿 이미지를 활용할 때 유용하다.

이미지 파일을 받는 Electron API는 파일 경로나 NativeImage 인스턴스를 모두 허용한다. null을 전달하면 빈 투명 이미지가 사용된다.

예를 들어, Tray를 생성하거나 BrowserWindow의 아이콘을 설정할 때, 문자열로 이미지 파일 경로를 전달할 수 있다:

Main Process

const { BrowserWindow, Tray } = require('electron')

const tray = new Tray('/Users/somebody/images/icon.png')
const win = new BrowserWindow({ icon: '/Users/somebody/images/window.png' })

또는 동일한 파일로부터 NativeImage 인스턴스를 생성할 수도 있다:

Main Process

const { BrowserWindow, nativeImage, Tray } = require('electron')

const trayIcon = nativeImage.createFromPath('/Users/somebody/images/icon.png')
const appIcon = nativeImage.createFromPath('/Users/somebody/images/window.png')
const tray = new Tray(trayIcon)
const win = new BrowserWindow({ icon: appIcon })

지원되는 파일 형식

현재 모든 플랫폼에서 PNG와 JPEG 이미지 형식을 지원한다. 투명도와 무손실 압축을 지원하는 PNG를 권장한다.

Windows에서는 파일 경로에서 ICO 아이콘을 로드할 수도 있다. 최상의 시각적 품질을 위해 최소한 다음 크기를 포함하는 것이 좋다:

• 작은 아이콘
  • 16x16 (100% DPI 스케일)
  • 20x20 (125% DPI 스케일)
  • 24x24 (150% DPI 스케일)
  • 32x32 (200% DPI 스케일)
• 큰 아이콘
  • 32x32 (100% DPI 스케일)
  • 40x40 (125% DPI 스케일)
  • 48x48 (150% DPI 스케일)
  • 64x64 (200% DPI 스케일)
  • 256x256

Windows 앱 아이콘 구성 참조 문서의 아이콘 스케일링 섹션을 확인하라.

note

현재 EXIF 메타데이터는 지원되지 않으며, 이미지 인코딩과 디코딩 과정에서 고려되지 않는다.

고해상도 이미지

Apple Retina와 같은 고픽셀 밀도 디스플레이를 지원하는 플랫폼에서는 이미지의 기본 파일명 뒤에 @2x를 붙여 2배 크기의 고해상도 이미지로 표시할 수 있다.

예를 들어, icon.png가 일반 해상도 이미지라면, icon@2x.png는 DPI(Dots per Inch) 밀도가 두 배인 고해상도 이미지로 처리된다.

다양한 DPI 밀도를 가진 디스플레이를 동시에 지원하려면, 다른 크기의 이미지를 같은 폴더에 넣고 DPI 접미사 없이 파일명만 사용하면 된다. 예를 들면 다음과 같다:

images/
├── icon.png
├── icon@2x.png
└── icon@3x.png

Main Process

const { Tray } = require('electron')
const appTray = new Tray('/Users/somebody/images/icon.png')

다음 DPI 접미사도 지원된다:

• @1x
• @1.25x
• @1.33x
• @1.4x
• @1.5x
• @1.8x
• @2x
• @2.5x
• @3x
• @4x
• @5x

템플릿 이미지 macOS

macOS에서 템플릿 이미지는 검은색과 알파 채널로 구성된다. 템플릿 이미지는 단독으로 사용하기보다는 다른 콘텐츠와 혼합해 최종적으로 원하는 모습을 만드는 데 활용된다.

가장 일반적인 사용 사례는 메뉴 바(트레이) 아이콘으로, 이를 통해 밝은 배경과 어두운 배경 모두에 적응할 수 있다.

이미지를 템플릿 이미지로 표시하려면 기본 파일명 끝에 Template이라는 단어를 붙여야 한다(예: xxxTemplate.png). 또한 다양한 DPI 밀도에 맞는 템플릿 이미지를 지정할 수도 있다(예: xxxTemplate@2x.png).

메서드

nativeImage 모듈은 다음과 같은 메서드를 제공한다. 모든 메서드는 NativeImage 클래스의 인스턴스를 반환한다:

nativeImage.createEmpty()

NativeImage 타입을 반환한다.

비어 있는 NativeImage 인스턴스를 생성한다.

nativeImage.createThumbnailFromPath(path, size) macOS Windows

• path string - 썸네일을 생성할 파일의 경로
• size Size - 썸네일의 원하는 너비와 높이(양수)

Promise<NativeImage>를 반환 - 파일의 썸네일 미리보기 이미지인 NativeImage로 이행된다.

참고: 윈도우 구현에서는 size.height를 무시하고 size.width에 따라 높이를 조절한다.

nativeImage.createFromPath(path)

• path string - 이미지를 생성하려는 파일의 경로

NativeImage를 반환한다.

지정된 path에 위치한 파일로부터 새로운 NativeImage 인스턴스를 생성한다. 만약 path가 존재하지 않거나, 읽을 수 없거나, 유효한 이미지가 아닌 경우 빈 이미지를 반환한다.

const { nativeImage } = require('electron')

const image = nativeImage.createFromPath('/Users/somebody/images/icon.png')
console.log(image)

nativeImage.createFromBitmap(buffer, options)

• buffer Buffer
• options Object
  • width Integer
  • height Integer
  • scaleFactor Number (선택 사항) - 기본값은 1.0.

NativeImage를 반환한다.

toBitmap()에서 반환된 원시 비트맵 픽셀 데이터가 포함된 buffer로부터 새로운 NativeImage 인스턴스를 생성한다. 구체적인 형식은 플랫폼에 따라 다르다.

nativeImage.createFromBuffer(buffer[, options])

• buffer Buffer
• options Object (선택 사항)
  • width Integer (선택 사항) - 비트맵 버퍼의 경우 필수.
  • height Integer (선택 사항) - 비트맵 버퍼의 경우 필수.
  • scaleFactor Number (선택 사항) - 기본값은 1.0.

NativeImage를 반환한다.

buffer로부터 새로운 NativeImage 인스턴스를 생성한다. 먼저 PNG나 JPEG로 디코딩을 시도한다.

nativeImage.createFromDataURL(dataURL)

• dataURL string

NativeImage를 반환

base64로 인코딩된 Data URL 문자열인 dataUrl을 사용해 새로운 NativeImage 인스턴스를 생성한다.

nativeImage.createFromNamedImage(imageName[, hslShift]) macOS

• imageName string
• hslShift number[] (선택 사항)

NativeImage를 반환한다.

주어진 이미지 이름에 매핑되는 NSImage로부터 새로운 NativeImage 인스턴스를 생성한다. 가능한 값 목록은 Apple의 NSImageName 문서를 참고한다.

hslShift는 이미지에 다음과 같은 규칙으로 적용된다:

• hsl_shift[0] (색상): 이미지의 절대적인 색상 값. 0과 1은 색상 휠에서 0과 360(빨간색)에 해당한다.
• hsl_shift[1] (채도): 이미지의 채도 변화. 주요 값은 다음과 같다: 0 = 모든 색상을 제거. 0.5 = 변경 없음. 1 = 이미지를 완전히 채도 높임.
• hsl_shift[2] (명도): 이미지의 명도 변화. 주요 값은 다음과 같다: 0 = 모든 명도를 제거(모든 픽셀을 검은색으로). 0.5 = 변경 없음. 1 = 완전한 명도(모든 픽셀을 흰색으로).

즉, [-1, 0, 1]은 이미지를 완전히 흰색으로 만들고, [-1, 1, 0]은 이미지를 완전히 검은색으로 만든다.

일부 경우에는 NSImageName이 문자열 표현과 일치하지 않을 수 있다. 예를 들어 NSFolderImageName은 실제로 NSFolder라는 문자열로 표현된다. 따라서 이미지를 전달하기 전에 올바른 문자열 표현을 확인해야 한다. 이는 다음과 같은 방법으로 수행할 수 있다:

echo -e '#import <Cocoa/Cocoa.h>\nint main() { NSLog(@"%@", SYSTEM_IMAGE_NAME); }' | clang -otest -x objective-c -framework Cocoa - && ./test

여기서 SYSTEM_IMAGE_NAME은 이 목록의 어떤 값으로 대체해야 한다.

Class: NativeImage

트레이, 독, 애플리케이션 아이콘과 같은 이미지를 네이티브로 감싸는 클래스

프로세스: 메인, 렌더러
이 클래스는 'electron' 모듈에서 직접 내보내지 않는다. Electron API의 다른 메서드 반환값으로만 사용할 수 있다.

인스턴스 메서드

NativeImage 클래스의 인스턴스에서 사용할 수 있는 메서드는 다음과 같다:

image.toPNG([옵션])

• 옵션 Object (선택사항)
  • scaleFactor Number (선택사항) - 기본값은 1.0입니다.

Buffer를 반환합니다. 이미지의 PNG 인코딩 데이터를 포함하는 Buffer입니다.

image.toJPEG(quality)

• quality Integer - 0부터 100 사이의 정수

Buffer를 반환한다. 이 버퍼는 이미지의 JPEG 인코딩된 데이터를 포함한다.

image.toBitmap([options])

• options Object (선택 사항)
  • scaleFactor Number (선택 사항) - 기본값은 1.0입니다.

Buffer를 반환합니다. 이는 이미지의 원시 비트맵 픽셀 데이터를 복사한 Buffer입니다.

image.toDataURL([options])

History

Version(s)	Changes
None	nativeImage.toDataURL will preserve PNG colorspace

• options Object (선택 사항)
  • scaleFactor Number (선택 사항) - 기본값은 1.0.

string을 반환한다. 이미지의 Data URL을 반환한다.

image.getBitmap([options])

• options Object (선택 사항)
  • scaleFactor Number (선택 사항) - 기본값은 1.0

Buffer를 반환한다. 반환된 Buffer는 이미지의 원시 비트맵 픽셀 데이터를 포함한다.

getBitmap()과 toBitmap()의 차이점은 getBitmap()은 비트맵 데이터를 복사하지 않는다는 점이다. 따라서 반환된 Buffer를 현재 이벤트 루프 틱에서 즉시 사용해야 한다. 그렇지 않으면 데이터가 변경되거나 소멸될 수 있다.

image.getNativeHandle() macOS

Buffer를 반환한다. 이 버퍼는 이미지의 기본 네이티브 핸들에 대한 C 포인터를 저장한다. macOS에서는 NSImage 인스턴스에 대한 포인터가 반환된다.

반환된 포인터는 기본 네이티브 이미지에 대한 약한 참조이므로, 복사본이 아니다. 따라서 관련된 nativeImage 인스턴스가 계속 유지되도록 해야 한다.

image.isEmpty()

boolean 타입을 반환한다. 이미지가 비어 있는지 여부를 나타낸다.

image.getSize([scaleFactor])

• scaleFactor Number (선택 사항) - 기본값은 1.0입니다.

Size를 반환합니다.

scaleFactor를 전달하면, 전달된 값과 가장 근접한 이미지 표현에 해당하는 크기를 반환합니다.

image.setTemplateImage(option)

• option boolean

이미지를 macOS 템플릿 이미지로 표시한다.

image.isTemplateImage()

boolean 타입의 값을 반환한다. 이 값은 해당 이미지가 macOS의 템플릿 이미지인지 여부를 나타낸다.

image.crop(rect)

• rect Rectangle - 이미지에서 잘라낼 영역.

NativeImage를 반환한다. 잘라낸 이미지가 반환된다.

image.resize(options)

• options 객체
  • width 정수 (선택 사항) - 기본값은 이미지의 너비.
  • height 정수 (선택 사항) - 기본값은 이미지의 높이.
  • quality 문자열 (선택 사항) - 리사이즈된 이미지의 품질. 가능한 값은 good, better, 또는 best. 기본값은 best. 이 값들은 품질과 속도 간의 균형을 나타낸다. 이 값들은 해당 플랫폼의 성능(CPU, GPU)에 따라 알고리즘별로 변환된다. 특정 플랫폼에서는 세 가지 방법이 동일한 알고리즘으로 매핑될 수 있다.

반환값: NativeImage - 리사이즈된 이미지.

height 또는 width 중 하나만 지정하면 리사이즈된 이미지에서 현재 종횡비가 유지된다.

image.getAspectRatio([scaleFactor])

• scaleFactor Number (선택 사항) - 기본값은 1.0입니다.

Number를 반환합니다. 이미지의 종횡비(너비를 높이로 나눈 값)입니다.

scaleFactor를 전달하면, 전달된 값과 가장 근접한 이미지 표현에 해당하는 종횡비를 반환합니다.

image.getScaleFactors()

Number[] 타입의 배열을 반환한다. 이 배열은 주어진 NativeImage에 대한 모든 스케일 팩터를 포함한다. 각 스케일 팩터는 이미지의 다양한 표현에 대응한다.

image.addRepresentation(options)

• options Object
  • scaleFactor Number (선택 사항) - 이미지 표현을 추가할 스케일 팩터.
  • width Integer (선택 사항) - 기본값은 0. 비트맵 버퍼가 buffer로 지정된 경우 필수.
  • height Integer (선택 사항) - 기본값은 0. 비트맵 버퍼가 buffer로 지정된 경우 필수.
  • buffer Buffer (선택 사항) - 원시 이미지 데이터를 포함하는 버퍼.
  • dataURL string (선택 사항) - base64로 인코딩된 PNG 또는 JPEG 이미지를 포함하는 데이터 URL.

특정 스케일 팩터에 대한 이미지 표현을 추가한다. 이를 통해 프로그래밍 방식으로 이미지에 다양한 스케일 팩터 표현을 추가할 수 있다. 이 메서드는 빈 이미지에서도 호출할 수 있다.

인스턴스 속성

nativeImage.isMacTemplateImage macOS

이 속성은 이미지가 템플릿 이미지로 간주되는지 여부를 결정하는 boolean 타입의 값이다.

이 속성은 macOS에서만 유효하다는 점에 유의한다.