Создание вашего первого приложения

Следуйте пошаговому руководству

Это часть 2 руководства по Electron.

Цели обучения

В этой части руководства вы узнаете, как настроить свой проект Electron и написать минимальное стартовое приложение. К концу этого раздела вы сможете запустить работающее приложение Electron в режиме разработки из своей командной строки.

Настройка проекта

Избегайте WSL

Если вы работаете на компьютере с Windows, пожалуйста, не используйте Windows Subsystem for Linux (WSL) при выполнении этого руководства, так как у вас могут возникнуть проблемы при попытке выполнить приложение.

Инициализация вашего проекта npm

Приложения Electron создаются с помощью npm, используя файл package.json в качестве точки входа. Начните с создания папки и инициализации npm-пакета в ней с помощью npm init.

npm
Yarn

mkdir my-electron-app && cd my-electron-app
npm init

mkdir my-electron-app && cd my-electron-app
yarn init

Эта команда предложит вам настроить некоторые поля в вашем файле package.json. Для целей этого руководства необходимо соблюдать несколько правил:

точка входа должна быть main.js (вы скоро создадите этот файл).
автор, лицензия и описание могут быть любыми значениями, но будут необходимы для упаковки позже.

Затем установите Electron в devDependencies вашего приложения, что является списком внешних зависимостей только для разработки, не требуемых в производстве.

Почему Electron является devDependency?

Это может показаться нелогичным, так как ваш производственный код использует Electron API. Однако упакованные приложения будут поставляться вместе с бинарником Electron, что исключает необходимость указывать его в качестве производственной зависимости.

npm
Yarn

npm install electron --save-dev

yarn add electron --dev

Файл package.json должен выглядеть примерно так после инициализации пакета и установки Electron. У вас также должна быть папка node_modules, содержащая исполняемый файл Electron, а также файл package-lock.json lockfile, который определяет точные версии зависимостей для установки.

package.json

{
  "name": "my-electron-app",
  "version": "1.0.0",
  "description": "Hello World!",
  "main": "main.js",
  "author": "Jane Doe",
  "license": "MIT",
  "devDependencies": {
    "electron": "19.0.0"
  }
}

Расширенные шаги по установке Electron

Если установка Electron напрямую завершается неудачей, обратитесь к нашей документации по расширенной установке для получения инструкций по зеркалам загрузок, прокси и шагам по устранению неполадок.

Добавление .gitignore

Файл .gitignore определяет, какие файлы и каталоги следует избегать отслеживания с помощью Git. Вы должны скопировать шаблон .gitignore от GitHub для Node.js в корневую папку своего проекта, чтобы избежать коммита папки node_modules вашего проекта.

Запуск приложения Electron

Дополнительные материалы

Прочитайте документацию по модели процессов Electron, чтобы лучше понять, как взаимодействуют несколько процессов Electron.

Скрипт main, который вы определили в package.json, является точкой входа любого приложения Electron. Этот скрипт управляет главным процессом, который работает в среде Node.js и отвечает за управление жизненным циклом приложения, отображение нативных интерфейсов, выполнение привилегированных операций и управление процессами рендеринга (подробнее об этом позже).

Прежде чем создавать ваше первое приложение Electron, вы сначала используете тривиальный скрипт, чтобы убедиться, что ваша точка входа главного процесса настроена правильно. Создайте файл main.js в корневой папке вашего проекта с одной строкой кода:

main.js

console.log(`Hello from Electron 👋`)

Поскольку главный процесс Electron — это среда выполнения Node.js, вы можете выполнять произвольный код Node.js с помощью команды electron (вы можете даже использовать её как REPL). Чтобы выполнить этот скрипт, добавьте electron . к команде start в поле scripts в вашем файле package.json. Эта команда сообщит исполняемому файлу Electron искать основной скрипт в текущем каталоге и выполнить его в режиме разработки.

package.json

{
  "name": "my-electron-app",
  "version": "1.0.0",
  "description": "Hello World!",
  "main": "main.js",
  "author": "Jane Doe",
  "license": "MIT",
  "scripts": {
    "start": "electron ."
  },
  "devDependencies": {
    "electron": "^19.0.0"
  }
}

npm
Yarn

npm run start

yarn run start

В вашей командной строке должно появиться Hello from Electron 👋. Поздравляем, вы выполнили свою первую строку кода в Electron! Далее вы узнаете, как создавать пользовательские интерфейсы с помощью HTML и загружать их в нативное окно.

Загрузка веб-страницы в BrowserWindow

В Electron каждое окно отображает веб-страницу, которую можно загрузить либо из локального файла HTML, либо с удаленного веб-адреса. В этом примере вы будете загружать локальный файл. Начните с создания простой веб-страницы в файле index.html в корневой папке вашего проекта:

index.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
    <meta
      http-equiv="Content-Security-Policy"
      content="default-src 'self'; script-src 'self'"
    />
    <meta
      http-equiv="X-Content-Security-Policy"
      content="default-src 'self'; script-src 'self'"
    />
    <title>Hello from Electron renderer!</title>
  </head>
  <body>
    <h1>Hello from Electron renderer!</h1>
    <p>👋</p>
  </body>
</html>

Теперь, когда у вас есть веб-страница, вы можете загрузить её в Electron BrowserWindow. Замените содержимое вашего файла main.js следующим кодом. Мы объясним каждый выделенный блок отдельно.

main.js

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

const createWindow = () => {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
  })

  win.loadFile('index.html')
}

app.whenReady().then(() => {
  createWindow()
})

Импорт модулей

main.js (Строка 1)

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

В первой строке мы импортируем два модуля Electron с помощью синтаксиса модулей CommonJS:

app, который управляет жизненным циклом событий вашего приложения.
BrowserWindow, который создаёт и управляет окнами приложения.

Конвенции написания заглавных букв

Вы, возможно, заметили разницу в написании заглавных букв в модулях app и BrowserWindow. Electron следует типичным JavaScript-конвенциям: модули в PascalCase являются экземплярами конструкторов классов (например, BrowserWindow, Tray, Notification), в то время как модули в camelCase не являются экземплярами (например, app, ipcRenderer, webContents).

ES-модули в Electron

Модули ECMAScript (т. е. с использованием import для загрузки модуля) в настоящее время не поддерживаются напрямую в Electron. Дополнительную информацию о состоянии ESM в Electron можно найти в electron/electron#21457.

Написание многократно используемой функции для создания окон

Функция createWindow() загружает вашу веб-страницу в новый экземпляр BrowserWindow:

main.js (строки 3-10)

const createWindow = () => {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
  })

  win.loadFile('index.html')
}

Вызов вашей функции при готовности приложения

main.js (строки 12-14)

app.whenReady().then(() => {
  createWindow()
})

Многие основные модули Electron являются Node.js поставщиками событий, которые соответствуют асинхронной архитектуре обработки событий Node. Модуль app является одним из таких поставщиков событий.

В Electron BrowserWindows могут быть созданы только после срабатывания события ready модуля app. Вы можете дождаться этого события, используя API app.whenReady(), и вызвав createWindow() после выполнения его обещания.

info

Вы обычно подключаетесь к Node.js-событиям, используя функцию .on поставщика событий.

+ app.on('ready').then(() => {
- app.whenReady().then(() => {
  createWindow()
})

Однако, Electron предоставляет app.whenReady() в качестве помощника, специально для события ready, чтобы избежать тонких проблем с непосредственным подключением к этому событию. Подробности см. в electron/electron#21972.

В этот момент выполнение команды start вашего приложения Electron должно успешно открыть окно, отображающее вашу веб-страницу!

Каждая веб-страница, отображаемая вашим приложением в окне, будет выполняться в отдельном процессе, называемом процессом рендеринга (или просто рендером). Процессы рендеринга имеют доступ к тем же JavaScript-API и инструментам, которые вы используете для обычного фронтэнд-разработки веб-приложений, например, к webpack для объединения и минификации кода или React для создания пользовательских интерфейсов.

Управление жизненным циклом окон вашего приложения

Поведение окон приложений различается на разных операционных системах. Вместо того, чтобы навязывать эти конвенции по умолчанию, Electron даёт вам возможность реализовать их в коде вашего приложения, если вы хотите следовать им. Вы можете реализовать базовые конвенции окон, подключившись к событиям, генерируемым модулями app и BrowserWindow.

Поток управления, специфичный для процесса

Проверка переменной Node process.platform может помочь вам условно выполнять код на определённых платформах. Обратите внимание, что Electron может работать только на трёх платформах: win32 (Windows), linux (Linux) и darwin (macOS).

Выход из приложения при закрытии всех окон (Windows и Linux)

В Windows и Linux закрытие всех окон, как правило, приводит к полному выходу из приложения. Чтобы реализовать этот шаблон в приложении Electron, подключайтесь к событию window-all-closed модуля app и вызывайте app.quit() для выхода из приложения, если пользователь не находится на macOS.

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') app.quit()
})

Открытие окна, если ни одно окно не открыто (macOS)

В приложениях macOS, в отличие от этого, приложение, как правило, продолжает работу даже без открытых окон. При активации приложения при отсутствии окон должно открываться новое окно.

Для реализации этой функции подключайтесь к событию activate модуля app и вызывайте существующий метод createWindow(), если ни одно окно BrowserWindow не открыто.

Поскольку окна не могут быть созданы до события ready, вы должны подключаться к событиям activate только после инициализации вашего приложения. Сделайте это, подключившись к событиям активации только внутри вашего существующего обратного вызова whenReady().

app.whenReady().then(() => {
  createWindow()

  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

Конечный стартовый код

docs/fiddles/tutorial-first-app (20.1.0)Открыть в Fiddle

main.js
index.html

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

const createWindow = () => {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
  });

  win.loadFile('index.html');
};

app.whenReady().then(() => {
  createWindow();

  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) {
      createWindow();
    }
  });
});

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit();
  }
});

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta
      http-equiv="Content-Security-Policy"
      content="default-src 'self'; script-src 'self'"
    />
    <meta
      http-equiv="X-Content-Security-Policy"
      content="default-src 'self'; script-src 'self'"
    />
    <title>Hello from Electron renderer!</title>
  </head>
  <body>
    <h1>Hello from Electron renderer!</h1>
    <p>👋</p>
    <p id="info"></p>
  </body>
  <script src="./renderer.js"></script>
</html>

Необязательно: отладка из VS Code

Если вы хотите отладить своё приложение с помощью VS Code, вам нужно подключить VS Code к основному и процессам рендеринга. Вот пример конфигурации для запуска. Создайте конфигурацию launch.json в новом каталоге .vscode в вашем проекте:

.vscode/launch.json

{
  "version": "0.2.0",
  "compounds": [
    {
      "name": "Main + renderer",
      "configurations": ["Main", "Renderer"],
      "stopAll": true
    }
  ],
  "configurations": [
    {
      "name": "Renderer",
      "port": 9222,
      "request": "attach",
      "type": "pwa-chrome",
      "webRoot": "${workspaceFolder}"
    },
    {
      "name": "Main",
      "type": "pwa-node",
      "request": "launch",
      "cwd": "${workspaceFolder}",
      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
      "windows": {
        "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd"
      },
      "args": [".", "--remote-debugging-port=9222"],
      "outputCapture": "std",
      "console": "integratedTerminal"
    }
  ]
}

Вариант "Основной + рендеринг" появится при выборе "Запустить и отладить" в боковой панели, позволяя вам устанавливать точки останова и просматривать переменные, среди прочего, как в основном, так и в процессах рендеринга.

То, что мы сделали в файле launch.json - это создание 3 конфигураций:

Main используется для запуска основного процесса и также экспонирует порт 9222 для удалённой отладки (--remote-debugging-port=9222). Именно этот порт мы будем использовать для подключения отладчика к Renderer. Так как основной процесс — это Node.js-процесс, тип установлен на pwa-node (pwa- — это префикс, который сообщает VS Code использовать самый последний JavaScript-отладчик).
Renderer используется для отладки процесса рендеринга. Поскольку основной процесс создаёт процесс рендеринга, нам нужно к нему "подключиться" ("request": "attach") вместо создания нового. Процесс рендеринга — веб-процесс, поэтому используемый отладчик — pwa-chrome.
Main + renderer — это составная задача, которая выполняет предыдущие задачи одновременно.

предупреждение

Поскольку мы подключаемся к процессу в Renderer, возможно, что первые строки вашего кода будут пропущены, так как отладчик не успеет подключиться до их выполнения. Вы можете обойти эту проблему, обновив страницу или установив таймаут перед выполнением кода в режиме разработки.

Дополнительное чтение

Если вы хотите углубиться в область отладки, следующие руководства предоставляют дополнительную информацию:

Обзор

Приложения Electron настраиваются с использованием пакетов npm. Файл Electron должен быть установлен в devDependencies вашего проекта и может быть запущен в режиме разработки с помощью скрипта в файле package.json.

Исполняемый файл запускает точку входа JavaScript, расположенную в свойстве main вашего файла package.json. Этот файл управляет главным процессом Electron, который выполняет экземпляр Node.js и отвечает за жизненный цикл приложения, отображение нативных интерфейсов, выполнение привилегированных операций и управление процессами рендеринга.

Процессы рендеринга (или рендеры вкратце) отвечают за отображение графического контента. Вы можете загрузить веб-страницу в процесс рендеринга, указав либо веб-адрес, либо локальный HTML-файл. Процессы рендеринга ведут себя очень похоже на обычные веб-страницы и имеют доступ к тем же веб-API.

В следующей части учебника мы узнаем, как расширить процесс рендеринга с помощью привилегированных API и как обмениваться данными между процессами.

Цели обучения​

Настройка проекта​

Инициализация вашего проекта npm​

Добавление .gitignore​

Запуск приложения Electron​

Загрузка веб-страницы в BrowserWindow​

Импорт модулей​

Написание многократно используемой функции для создания окон​

Вызов вашей функции при готовности приложения​

Управление жизненным циклом окон вашего приложения​

Выход из приложения при закрытии всех окон (Windows и Linux)​

Открытие окна, если ни одно окно не открыто (macOS)​

Конечный стартовый код​

Необязательно: отладка из VS Code​

Обзор​