본문 바로가기
JavaScript/Electron

Electron의 주요 API

by curious week 2025. 3. 18.

Electron 창(Window) 관련 API

Electron에서 창을 관리할 때 BrowserWindow API를 사용합니다.
창을 생성하고 크기 조정, 숨기기, 닫기 등의 동작을 수행할 수 있습니다.

창 생성 및 설정 (BrowserWindow)
창 크기 및 옵션 설정 (width, height, resizable 등)
창 이벤트 (ready-to-show, closed 등)
창 조작 (show(), hide(), maximize(), minimize(), close() 등)

즉, Electron의 BrowserWindow를 사용하면 네이티브 데스크톱 애플리케이션처럼 창을 제어할 수 있습니다!

1. BrowserWindow 생성 및 설정

BrowserWindow 기본 생성

const { app, BrowserWindow } = require("electron");

let mainWindow;

app.whenReady().then(() => {
  mainWindow = new BrowserWindow({
    width: 800,  // 창 너비
    height: 600, // 창 높이
    webPreferences: {
      preload: __dirname + "/preload.js", // 보안 설정을 위한 Preload 스크립트
      contextIsolation: true,
      nodeIntegration: false,
    }
  });

  mainWindow.loadFile("index.html"); // HTML 파일 로드
});

이제 애플리케이션이 실행되면 800x600 크기의 창이 생성됩니다. 

2. 창 옵션 (width, height, resizable 등)

Electron에서는 창을 생성할 때 다양한 옵션을 설정할 수 있습니다.

BrowserWindow 창 옵션

const mainWindow = new BrowserWindow({
  width: 1024,         // 창 너비
  height: 768,         // 창 높이
  minWidth: 800,       // 최소 너비
  minHeight: 600,      // 최소 높이
  maxWidth: 1600,      // 최대 너비
  maxHeight: 1200,     // 최대 높이
  resizable: true,     // 창 크기 조절 가능 여부
  movable: true,       // 창 이동 가능 여부
  alwaysOnTop: false,  // 항상 위에 위치 여부
  fullscreen: false,   // 전체 화면 모드 여부
  title: "Electron 앱", // 창 제목
  frame: true,         // 기본 창 프레임 표시 여부 (false면 테두리 없는 창)
  transparent: false,  // 투명 창 여부
  webPreferences: {
    preload: __dirname + "/preload.js",
    contextIsolation: true,
    nodeIntegration: false
  }
});

창의 크기, 최소/최대 크기, 크기 조절 여부 등을 설정할 수 있습니다! 

3. 창 이벤트 (ready-to-show, closed 등)

창이 로드되거나 닫힐 때 특정 동작을 실행할 수 있습니다.

BrowserWindow 창 이벤트 목록

  • ready-to-show - 창이 준비되었을 때 실행됨
  • closed - 창이 완전히 닫혔을 때 실행됨
  • focus - 창이 포커스를 받을 때 실행됨
  • blur - 창이 포커스를 잃을 때 실행됨
  • maximize - 창이 최대화될 때 실행됨
  • unmaximize - 창이 최대화에서 원래 크기로 복원될 때 실행됨
  • minimize - 창이 최소화될 때 실행됨
  • restore - 창이 최소화에서 복원될 때 실행됨

창 이벤트 

mainWindow.on("ready-to-show", () => {
  console.log("창이 준비되었습니다!");
});

mainWindow.on("closed", () => {
  console.log("창이 닫혔습니다.");
});

mainWindow.on("focus", () => {
  console.log("창이 활성화되었습니다.");
});

mainWindow.on("blur", () => {
  console.log("창이 비활성화되었습니다.");
});

이제 창이 열리거나 닫힐 때 콘솔에 로그가 출력됩니다!

4. 창 조작 (show(), hide(), maximize(), minimize(), close() 등)

Electron에서는 창을 조작할 수 있는 다양한 메서드를 제공합니다.

BrowserWindow 창 조작 메서드

메서드 설명
show() 창을 표시
hide() 창을 숨김
maximize() 창을 최대화
unmaximize() 창을 원래 크기로 복원
minimize() 창을 최소화
restore() 최소화된 창을 복원
close() 창을 닫음
setBounds({ width, height }) 창 크기를 변경
setFullScreen(true/false) 창을 전체 화면 모드로 변경

창 조작

setTimeout(() => {
  mainWindow.hide(); // 창 숨기기
}, 3000);

setTimeout(() => {
  mainWindow.show(); // 창 다시 표시
}, 5000);

setTimeout(() => {
  mainWindow.maximize(); // 창 최대화
}, 7000);

setTimeout(() => {
  mainWindow.unmaximize(); // 최대화 해제
}, 9000);

setTimeout(() => {
  mainWindow.minimize(); // 창 최소화
}, 11000);

setTimeout(() => {
  mainWindow.restore(); // 최소화 해제
}, 13000);

이제 창이 자동으로 숨기기, 최대화, 최소화 등의 동작을 수행합니다!

5. 창을 여러 개 생성 (멀티 윈도우)

Electron에서는 하나의 애플리케이션에서 여러 개의 창을 생성할 수 있습니다.

다중 창 생성

let secondWindow;

app.whenReady().then(() => {
  mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: { preload: __dirname + "/preload.js" }
  });

  mainWindow.loadFile("index.html");

  secondWindow = new BrowserWindow({
    width: 600,
    height: 400,
    parent: mainWindow, // 부모 창 설정
    modal: true, // 부모 창이 닫히기 전까지 닫히지 않음
    webPreferences: { preload: __dirname + "/preload.js" }
  });

  secondWindow.loadFile("second.html");
});

이제 두 개의 창이 동시에 실행됩니다!

6. 창을 항상 위에 유지 (alwaysOnTop)

어떤 경우에는 창을 다른 모든 창 위에 계속 표시해야 할 때가 있습니다.

창을 항상 위에 유지

mainWindow.setAlwaysOnTop(true);

이제 창이 항상 최상위에 유지됩니다!

7. 창이 닫힐 때 사용자에게 확인 메시지 표시

Electron에서 창을 닫기 전에 사용자에게 확인 메시지를 띄우는 방법입니다.

창 닫기 확인

const { dialog } = require("electron");

mainWindow.on("close", (event) => {
  const choice = dialog.showMessageBoxSync(mainWindow, {
    type: "question",
    buttons: ["취소", "종료"],
    title: "앱 종료",
    message: "정말 종료하시겠습니까?"
  });

  if (choice === 0) {
    event.preventDefault(); // 창 닫기 취소
  }
});

이제 사용자가 종료 버튼을 클릭하면 확인 메시지가 표시됩니다!

Electron 시스템 기능 연동 (Clipboard, NativeTheme, PowerMonitor, PowerSaveBlocker)

Electron은 OS의 네이티브 기능과 상호작용할 수 있도록 다양한 API를 제공합니다.
이 중에서도 클립보드 복사, 다크 모드 감지, 배터리 상태 확인, 화면 꺼짐 방지 등 유용한 기능을 활용할 수 있습니다.

클립보드 기능 (clipboard) → 복사/붙여넣기 기능
OS 테마 감지 (nativeTheme) → 다크 모드/라이트 모드 감지
배터리 상태 확인 (powerMonitor) → 배터리 충전 상태 감지
화면 꺼짐 방지 (powerSaveBlocker) → 일정 시간 동안 화면 꺼짐 방지

즉, Electron의 시스템 기능을 활용하면 데스크톱 애플리케이션을 더욱 강력하게 만들 수 있습니다!

1. clipboard (클립보드 복사/붙여넣기)

Electron의 clipboard 모듈을 사용하면 사용자의 클립보드 데이터를 읽거나, 새로운 데이터를 복사할 수 있습니다.

1️⃣ 클립보드 데이터 복사 및 붙여넣기

const { clipboard } = require("electron");

// 📌 클립보드에 텍스트 복사
clipboard.writeText("Hello, Electron!");

setTimeout(() => {
  // 📌 클립보드에서 텍스트 읽기
  console.log("클립보드 내용:", clipboard.readText());
}, 2000);

이제 클립보드에 "Hello, Electron!"이 복사되고, 콘솔에서 읽어올 수 있습니다.

2️⃣ 클립보드에서 HTML 데이터 복사/읽기

Electron에서는 HTML 데이터를 클립보드에 복사할 수도 있습니다.

// 📌 HTML 데이터 클립보드에 복사
clipboard.writeHTML("<b>Electron</b> 클립보드 예제");

setTimeout(() => {
  console.log("클립보드 HTML:", clipboard.readHTML());
}, 2000);

이제 클립보드에 <b>Electron</b>이라는 HTML이 저장됩니다.

3️⃣ 클립보드에서 이미지 복사/읽기

Electron에서는 이미지를 클립보드에 복사하고 읽을 수 있습니다.

const { clipboard, nativeImage } = require("electron");

// 📌 이미지 파일을 클립보드에 복사
const image = nativeImage.createFromPath("example.png");
clipboard.writeImage(image);

setTimeout(() => {
  console.log("클립보드 이미지 크기:", clipboard.readImage().getSize());
}, 2000);

이제 example.png 파일이 클립보드에 복사됩니다.

2. nativeTheme (OS 테마 감지)

Electron의 nativeTheme 모듈을 사용하면 운영체제(OS)의 다크 모드/라이트 모드를 감지할 수 있습니다.

1️⃣ OS 테마 감지

const { nativeTheme } = require("electron");

console.log("현재 OS 테마:", nativeTheme.shouldUseDarkColors ? "다크 모드" : "라이트 모드");

현재 OS의 테마가 다크 모드인지, 라이트 모드인지 확인할 수 있습니다.

2️⃣ 테마 변경 감지 이벤트

사용자가 OS의 다크 모드 설정을 변경하면 이벤트를 감지할 수 있습니다.

nativeTheme.on("updated", () => {
  console.log("OS 테마 변경됨:", nativeTheme.shouldUseDarkColors ? "다크 모드" : "라이트 모드");
});

이제 OS 테마가 변경될 때마다 자동으로 감지할 수 있습니다.

3. powerMonitor (배터리 상태 확인)

Electron의 powerMonitor를 사용하면 배터리 충전 상태 및 전원 연결 여부를 확인할 수 있습니다.

1️⃣ 배터리 충전 상태 감지

const { powerMonitor } = require("electron");

powerMonitor.on("on-battery", () => {
  console.log("⚡ 배터리로 실행 중 (전원 어댑터 제거됨)");
});

powerMonitor.on("on-ac", () => {
  console.log("🔌 전원 어댑터가 연결됨");
});

이제 전원 케이블을 연결하거나 제거할 때마다 이벤트가 감지됩니다.

2️⃣ 시스템이 절전 모드로 전환될 때 감지

powerMonitor.on("suspend", () => {
  console.log("💤 시스템이 절전 모드로 전환됨");
});

powerMonitor.on("resume", () => {
  console.log("⏰ 시스템이 다시 실행됨");
});

이제 컴퓨터가 절전 모드로 전환되거나 복귀할 때 이벤트를 감지할 수 있습니다.

3️⃣ 시스템이 종료될 때 감지

powerMonitor.on("shutdown", () => {
  console.log("⚠ 시스템이 종료됨");
});

이제 사용자가 시스템을 종료하면 이를 감지할 수 있습니다. 

4. powerSaveBlocker (화면 꺼짐 방지)

Electron의 powerSaveBlocker를 사용하면 애플리케이션이 일정 시간 동안 시스템의 절전 모드를 방지할 수 있습니다.

1️⃣ 화면 꺼짐 방지 활성화

const { powerSaveBlocker } = require("electron");

// 📌 화면 꺼짐 방지 시작
const blockerId = powerSaveBlocker.start("prevent-display-sleep");

console.log("🛑 화면 꺼짐 방지 활성화됨, ID:", blockerId);

이제 시스템이 자동으로 화면을 끄지 않도록 방지할 수 있습니다. 

2️⃣ 화면 꺼짐 방지 해제

// 📌 화면 꺼짐 방지 중지
powerSaveBlocker.stop(blockerId);
console.log("✅ 화면 꺼짐 방지 해제됨");

화면 꺼짐 방지를 해제하면 다시 시스템의 기본 절전 모드가 적용됩니다. 

5. 전체 코드 

아래 코드를 실행하면 클립보드 복사, OS 테마 감지, 배터리 상태 확인, 화면 꺼짐 방지 기능을 테스트할 수 있습니다.

const { app, clipboard, nativeTheme, powerMonitor, powerSaveBlocker } = require("electron");

app.whenReady().then(() => {
  // 클립보드 복사 테스트
  clipboard.writeText("Hello, Electron!");
  console.log("클립보드 내용:", clipboard.readText());

  // OS 테마 감지
  console.log("현재 OS 테마:", nativeTheme.shouldUseDarkColors ? "다크 모드" : "라이트 모드");
  nativeTheme.on("updated", () => {
    console.log("OS 테마 변경됨:", nativeTheme.shouldUseDarkColors ? "다크 모드" : "라이트 모드");
  });

  // 배터리 상태 감지
  powerMonitor.on("on-battery", () => console.log("⚡ 배터리 모드"));
  powerMonitor.on("on-ac", () => console.log("🔌 전원 연결됨"));

  // 화면 꺼짐 방지 활성화
  const blockerId = powerSaveBlocker.start("prevent-display-sleep");
  console.log("🛑 화면 꺼짐 방지 활성화됨, ID:", blockerId);
});

이제 클립보드 기능, OS 테마 감지, 배터리 상태 감지, 화면 꺼짐 방지가 정상적으로 동작합니다!

Electron에서 파일 시스템 & 저장소 사용법

Electron은 파일 시스템을 조작하고 데이터를 저장할 수 있는 다양한 방법을 제공합니다.
이를 통해 로컬 파일을 읽고 쓰거나, 데이터베이스(SQLite, LevelDB 등)를 활용하여 영구 저장소를 구성할 수 있습니다.

fs 모듈을 사용한 파일 읽기/쓰기
Electron에서 fs를 안전하게 사용하는 방법
path 모듈을 활용한 파일 경로 조작
app.getPath()를 사용하여 시스템 경로 가져오기
SQLite, LevelDB, NeDB 등을 활용한 데이터 저장

1. fs 모듈을 사용한 파일 읽기/쓰기

Electron에서 파일을 읽거나 쓰려면 Node.js의 fs(파일 시스템) 모듈을 사용할 수 있습니다.

1️⃣ 파일 쓰기 (텍스트 파일 생성)

const fs = require("fs");

fs.writeFile("test.txt", "Hello, Electron!", (err) => {
  if (err) throw err;
  console.log("파일이 생성되었습니다!");
});

이제 "test.txt" 파일이 생성되고, "Hello, Electron!"이라는 내용이 저장됩니다. 

2️⃣ 파일 읽기

fs.readFile("test.txt", "utf8", (err, data) => {
  if (err) throw err;
  console.log("파일 내용:", data);
});

파일을 읽어 콘솔에 출력합니다. 

3️⃣ 파일 존재 여부 확인

if (fs.existsSync("test.txt")) {
  console.log("파일이 존재합니다!");
} else {
  console.log("파일이 없습니다!");
}

이제 test.txt 파일이 존재하는지 확인할 수 있습니다. 

4️⃣ 파일 삭제

fs.unlink("test.txt", (err) => {
  if (err) throw err;
  console.log("파일이 삭제되었습니다!");
});

파일을 삭제하고, 콘솔에 로그를 출력합니다. 

2. Electron에서 fs를 안전하게 사용하는 방법

Electron에서는 렌더러 프로세스에서 직접 fs를 사용할 수 없으므로, preload.js를 통해 안전하게 제공해야 합니다.

1️⃣ preload.js에서 안전한 파일 읽기 API 제공

const { contextBridge, ipcRenderer } = require("electron");

contextBridge.exposeInMainWorld("electronAPI", {
  readFile: (filePath) => ipcRenderer.invoke("readFile", filePath),
  writeFile: (filePath, data) => ipcRenderer.invoke("writeFile", filePath, data)
});

2️⃣ main.js에서 ipcMain.handle()을 사용하여 파일 시스템 접근

const { ipcMain } = require("electron");
const fs = require("fs").promises;

ipcMain.handle("readFile", async (event, filePath) => {
  return await fs.readFile(filePath, "utf8");
});

ipcMain.handle("writeFile", async (event, filePath, data) => {
  await fs.writeFile(filePath, data, "utf8");
  return "파일이 저장되었습니다!";
});

3️⃣ index.js에서 파일 읽기 및 쓰기 실행

document.getElementById("readFile").addEventListener("click", async () => {
  const content = await window.electronAPI.readFile("test.txt");
  console.log("파일 내용:", content);
});

document.getElementById("writeFile").addEventListener("click", async () => {
  await window.electronAPI.writeFile("test.txt", "Electron에서 저장한 데이터");
  console.log("파일이 저장되었습니다!");
});

이제 보안을 유지하면서 파일을 안전하게 읽고 쓸 수 있습니다!

3. path 모듈을 활용한 파일 경로 조작

파일 경로를 다룰 때는 Node.js의 path 모듈을 활용하면 편리합니다.

1️⃣ path.join()을 사용한 경로 생성

const path = require("path");

const filePath = path.join(__dirname, "data", "file.txt");
console.log("파일 경로:", filePath);

현재 디렉토리에 "data/file.txt" 경로를 생성합니다. 

2️⃣ 특정 파일의 디렉토리 경로 가져오기

const dirPath = path.dirname("/Users/electron/Desktop/file.txt");
console.log("디렉토리 경로:", dirPath);

/Users/electron/Desktop/가 출력됩니다. 

3️⃣ 파일 확장자 가져오기

const ext = path.extname("test.txt");
console.log("파일 확장자:", ext);

.txt가 출력됩니다. 

4. app.getPath()로 시스템 경로 가져오기

Electron의 app.getPath()를 사용하면 시스템의 기본 경로를 가져올 수 있습니다.

1️⃣ app.getPath()로 시스템 폴더 경로 가져오기

const { app } = require("electron");

console.log("홈 디렉토리:", app.getPath("home"));
console.log("데스크톱 경로:", app.getPath("desktop"));
console.log("문서 폴더 경로:", app.getPath("documents"));
console.log("앱 데이터 경로:", app.getPath("appData"));
console.log("로그 경로:", app.getPath("logs"));

이제 시스템의 기본 폴더 경로를 가져올 수 있습니다. 

5. SQLite, LevelDB, NeDB 등을 사용한 데이터 저장

Electron에서는 SQLite, LevelDB, NeDB 등의 데이터베이스를 활용하여 데이터를 저장할 수 있습니다.

1️⃣ SQLite를 사용한 데이터 저장

SQLite는 가벼운 SQL 데이터베이스이며 Electron과 잘 어울립니다.

SQLite 설치

npm install sqlite3

SQLite 데이터 저장 예제

const sqlite3 = require("sqlite3").verbose();
const db = new sqlite3.Database("database.db");

// 테이블 생성
db.run("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)");

db.run("INSERT INTO users (name) VALUES (?)", ["Alice"], function (err) {
  if (err) throw err;
  console.log("데이터 삽입 완료:", this.lastID);
});

// 데이터 조회
db.all("SELECT * FROM users", (err, rows) => {
  if (err) throw err;
  console.log("데이터:", rows);
});

이제 database.db 파일이 생성되고 데이터가 저장됩니다! 

2️⃣ LevelDB 사용

LevelDB는 빠른 Key-Value 저장소

LevelDB 설치

npm install level

LevelDB 사용 

const level = require("level");
const db = level("myDatabase");

// 데이터 저장
db.put("username", "electron_user", (err) => {
  if (err) throw err;
  console.log("데이터 저장 완료");
});

// 데이터 가져오기
db.get("username", (err, value) => {
  if (err) throw err;
  console.log("저장된 데이터:", value);
});

이제 "username" 키에 "electron_user" 데이터가 저장됩니다! 

저작자표시 동일조건 (새창열림)

'JavaScript > Electron' 카테고리의 다른 글

Electron과 웹 기술 연동  (0) 2025.03.18
Electron의 보안 문제  (0) 2025.03.18
Electron 핵심 프로세스 - 프로세스 간 통신  (0) 2025.03.18
Electron 핵심 프로세스 - 렌더러 프로세스  (0) 2025.03.17
Electron 핵심 프로세스 - 메인 프로세스  (0) 2025.03.17

관련글

티스토리툴바