Spec-Zone.ru › Electron

Быстрый старт

Это руководство проведет вас через процесс создания простого приложения «Привет, мир» в Electron, аналогично electron/electron-quick-start.

По окончании этого туториала ваше приложение откроет окно браузера, отображающее веб-страницу с информацией о версиях Chromium, Node.js и Electron.

Предварительные требования​

Для использования Electron необходимо установить Node.js. Рекомендуется использовать последнюю LTS версию, доступную.

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

Чтобы проверить корректность установки Node.js, введите следующие команды в терминале:

node -v
npm -v

Команды должны вывести версии Node.js и npm соответственно.

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

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

Сборка проекта​

Приложения Electron имеют ту же общую структуру, что и другие проекты Node.js. Начните с создания папки и инициализации пакета npm.

  • npm
  • Yarn
mkdir my-electron-app && cd my-electron-app
npm init
mkdir my-electron-app && cd my-electron-app
yarn init

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

  • entry point должен быть main.js.
  • author и description могут иметь любое значение, но необходимы для упаковки приложения упаковки приложения.

Ваш файл package.json должен выглядеть примерно так:

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

Затем, установите пакет electron в devDependencies вашего приложения.

  • npm
  • Yarn
npm install --save-dev electron
yarn add --dev electron

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

Наконец, вам необходимо выполнить Electron. В поле scripts вашей конфигурации package.json добавьте команду start следующим образом:

{
  "scripts": {
    "start": "electron ."
  }
}

Эта start команда позволит вам открыть ваше приложение в режиме разработки.

  • npm
  • Yarn
npm start
yarn start
# couldn't auto-convert command

Примечание: Этот скрипт сообщает Electron запустить приложение в корневой папке вашего проекта. На данном этапе ваше приложение немедленно выдаст ошибку, сообщая о невозможности найти приложение для запуска.

Запуск основного процесса​

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

Во время выполнения Electron будет искать этот скрипт в поле main конфигурации package.json приложения, которую вы должны были настроить на этапе создания приложения.

Для инициализации скрипта main, создайте пустой файл с именем main.js в корневой папке вашего проекта.

Примечание: Если вы снова запустите скрипт start в этот момент, ваше приложение больше не будет генерировать ошибки! Однако пока оно ничего не сделает, потому что мы еще не добавили код в main.js.

Создание веб-страницы​

Прежде чем мы сможем создать окно для нашего приложения, нам нужно создать содержимое, которое будет загружено в него. В Electron каждое окно отображает веб-содержимое, которое может быть загружено как из локального файла HTML, так и с удалённого URL.

Для этого туториала вы будете использовать первый вариант. Создайте файл 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'">
    <title>Hello World!</title>
  </head>
  <body>
    <h1>Hello World!</h1>
    We are using Node.js <span id="node-version"></span>,
    Chromium <span id="chrome-version"></span>,
    and Electron <span id="electron-version"></span>.
  </body>
</html>

Примечание: Посмотрев на этот HTML-документ, вы можете заметить, что номера версий отсутствуют в тексте тела. Мы добавим их вручную позже с помощью JavaScript.

Открытие веб-страницы в окне браузера​

Теперь, когда у вас есть веб-страница, загрузите её в окно приложения. Для этого вам понадобятся два модуля Electron:

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

Так как основной процесс выполняет Node.js, вы можете импортировать их как модули CommonJS в верхней части своего файла:

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

Затем, добавьте функцию createWindow(), которая загружает index.html в новую инстанцию BrowserWindow.

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

  win.loadFile('index.html')
}

Далее, вызовите эту функцию createWindow(), чтобы открыть окно.

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

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

Примечание: На данном этапе ваше приложение Electron должно успешно открыть окно, отображающее вашу веб-страницу!

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

Хотя вы теперь можете открыть окно браузера, вам потребуется дополнительный шаблонный код, чтобы сделать его более нативным для каждой платформы. Окна приложений ведут себя по-разному на каждой ОС, и Electron возлагает ответственность на разработчиков за реализацию этих соглашений в их приложении.

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

END_OF_DOCUMENT_MARKER

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

В Windows и Linux закрытие всех окон обычно приводит к полному выходу из приложения.

Для реализации этого, прослушайте событие 'window-all-closed' модуля app, и вызовите app.quit(), если пользователь не находится на macOS (darwin).

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

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

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

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

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

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

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

Примечание: В этот момент ваши элементы управления окнами должны быть полностью функциональными!

Доступ к Node.js из рендера с помощью скрипта предварительной загрузки​

Теперь последнее, что нужно сделать, это вывести на вашу веб-страницу номера версий Electron и его зависимостей.

Доступ к этой информации тривиален в основном процессе через глобальный объект Node process. Однако вы не можете просто изменить DOM из основного процесса, потому что он не имеет доступа к контексту рендера document. Они находятся в совершенно разных процессах!

Примечание: Если вам нужен более глубокий взгляд на процессы Electron, см. документ Модель процессов.

Здесь пригодится прикрепление скрипта предварительной загрузки к вашему рендерингу. Скрипт предварительной загрузки выполняется до загрузки процесса рендеринга и имеет доступ как к глобальным переменным рендера (например, window и document), так и к среде Node.js.

Создайте новый скрипт под названием preload.js следующим образом:

window.addEventListener('DOMContentLoaded', () => {
  const replaceText = (selector, text) => {
    const element = document.getElementById(selector)
    if (element) element.innerText = text
  }

  for (const dependency of ['chrome', 'node', 'electron']) {
    replaceText(`${dependency}-version`, process.versions[dependency])
  }
})

Приведенный выше код получает доступ к объекту Node.js process.versions и выполняет простую вспомогательную функцию replaceText, чтобы вставить номера версий в HTML-документ.

Чтобы прикрепить этот скрипт к процессу рендеринга, передайте путь к скрипту предварительной загрузки в параметр webPreferences.preload в вашем существующем конструкторе BrowserWindow. 

// include the Node.js 'path' module at the top of your file
const path = require('path')

// modify your existing createWindow() function
const createWindow = () => {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js')
    }
  })

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

Здесь используются два понятия Node.js:

  • Строка __dirname указывает на путь к выполняемому скрипту (в данном случае — корневую папку вашего проекта).
  • API path.join объединяет несколько сегментов пути, создавая объединенный путь, который работает во всех платформах.

Мы используем путь, относительный к текущему выполняемому JavaScript-файлу, чтобы ваш относительный путь работал как в режиме разработки, так и в упакованном.

Бонус: Добавьте функциональность в веб-содержимое​

На этом этапе вы можете задаться вопросом, как добавить больше функциональности в ваше приложение.

Для любых взаимодействий с веб-содержимым вы хотите добавить скрипты в процесс рендеринга. Поскольку рендер работает в обычной веб-среде, вы можете добавить тег <script> прямо перед закрывающим </body> тегом файла index.html, чтобы включить любые произвольные скрипты:

<script src="./renderer.js"></script>

Код, содержащийся в renderer.js, может использовать те же JavaScript-API и инструменты, что и при обычном фронтенд-разработке, например, использовать webpack для объединения и минификации кода или React для управления пользовательскими интерфейсами.

Резюме​

После выполнения вышеперечисленных шагов у вас должно быть полностью функциональное приложение Electron, которое выглядит так:

Simplest Electron app

Полный код представлен ниже:

// main.js

// Modules to control application life and create native browser window
const { app, BrowserWindow } = require('electron')
const path = require('path')

const createWindow = () => {
  // Create the browser window.
  const mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js')
    }
  })

  // and load the index.html of the app.
  mainWindow.loadFile('index.html')

  // Open the DevTools.
  // mainWindow.webContents.openDevTools()
}

// This method will be called when Electron has finished
// initialization and is ready to create browser windows.
// Some APIs can only be used after this event occurs.
app.whenReady().then(() => {
  createWindow()

  app.on('activate', () => {
    // On macOS it's common to re-create a window in the app when the
    // dock icon is clicked and there are no other windows open.
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

// Quit when all windows are closed, except on macOS. There, it's common
// for applications and their menu bar to stay active until the user quits
// explicitly with Cmd + Q.
app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') app.quit()
})

// In this file you can include the rest of your app's specific main process
// code. You can also put them in separate files and require them here.
// preload.js

// All the Node.js APIs are available in the preload process.
// It has the same sandbox as a Chrome extension.
window.addEventListener('DOMContentLoaded', () => {
  const replaceText = (selector, text) => {
    const element = document.getElementById(selector)
    if (element) element.innerText = text
  }

  for (const dependency of ['chrome', 'node', 'electron']) {
    replaceText(`${dependency}-version`, process.versions[dependency])
  }
})
<!--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'">
    <title>Hello World!</title>
  </head>
  <body>
    <h1>Hello World!</h1>
    We are using Node.js <span id="node-version"></span>,
    Chromium <span id="chrome-version"></span>,
    and Electron <span id="electron-version"></span>.

    <!-- You can also require other files to run in this process -->
    <script src="./renderer.js"></script>
  </body>
</html>
docs/fiddles/quick-start (20.1.0)Открыть в Fiddle
  • main.js
  • preload.js
  • index.html
const { app, BrowserWindow } = require('electron')
const path = require('path')

function createWindow () {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js')
    }
  })

  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()
  }
})

window.addEventListener('DOMContentLoaded', () => {
  const replaceText = (selector, text) => {
    const element = document.getElementById(selector)
    if (element) element.innerText = text
  }

  for (const type of ['chrome', 'node', 'electron']) {
    replaceText(`${type}-version`, process.versions[type])
  }
})

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Hello World!</title>
    <meta http-equiv="Content-Security-Policy" content="script-src 'self' 'unsafe-inline';" />
</head>
<body>
    <h1>Hello World!</h1>
    <p>
        We are using Node.js <span id="node-version"></span>,
        Chromium <span id="chrome-version"></span>,
        and Electron <span id="electron-version"></span>.
    </p>
</body>
</html>

Подводя итог всем проделанным шагам:

  • Мы создали приложение Node.js и добавили Electron в качестве зависимости.
  • Мы создали скрипт main.js, который выполняет наш основной процесс, управляющий приложением и работающий в среде Node.js. В этом скрипте мы использовали модули Electron app и BrowserWindow для создания окна браузера, отображающего веб-контент в отдельном процессе (рендер).
  • Для доступа к определенным функциям Node.js в рендере мы прикрепили скрипт предварительной загрузки к нашему конструктору BrowserWindow.

Упаковывание и распространение приложения​

Самый быстрый способ распространения вашего нового приложения — использовать Electron Forge.

  1. Добавьте Electron Forge в качестве зависимости разработки вашего приложения и используйте команду import для настройки каркаса Forge:

    • npm
    • Yarn
    npm install --save-dev @electron-forge/cli
npx electron-forge import

✔ Checking your system
✔ Initializing Git Repository
✔ Writing modified package.json file
✔ Installing dependencies
✔ Writing modified package.json file
✔ Fixing .gitignore

We have ATTEMPTED to convert your app to be in a format that electron-forge understands.

Thanks for using "electron-forge"!!!
    yarn add --dev @electron-forge/cli
npx electron-forge import

✔ Checking your system
✔ Initializing Git Repository
✔ Writing modified package.json file
✔ Installing dependencies
✔ Writing modified package.json file
✔ Fixing .gitignore

We have ATTEMPTED to convert your app to be in a format that electron-forge understands.

Thanks for using "electron-forge"!!!

  2. Создайте дистрибутив, используя команду make Forge:

    • npm
    • Yarn
    npm run make

> my-electron-app@1.0.0 make /my-electron-app
> electron-forge make

✔ Checking your system
✔ Resolving Forge Config
We need to package your application before we can make it
✔ Preparing to Package Application for arch: x64
✔ Preparing native dependencies
✔ Packaging Application
Making for the following targets: zip
✔ Making for target: zip - On platform: darwin - For arch: x64
    yarn run make

> my-electron-app@1.0.0 make /my-electron-app
> electron-forge make

✔ Checking your system
✔ Resolving Forge Config
We need to package your application before we can make it
✔ Preparing to Package Application for arch: x64
✔ Preparing native dependencies
✔ Packaging Application
Making for the following targets: zip
✔ Making for target: zip - On platform: darwin - For arch: x64

    Electron Forge создаёт папку out, где будет расположен ваш пакет:

    // Example for macOS
out/
├── out/make/zip/darwin/x64/my-electron-app-darwin-x64-1.0.0.zip
├── ...
└── out/my-electron-app-darwin-x64/my-electron-app.app/Contents/MacOS/my-electron-app

© GitHub Inc.
Licensed under the MIT license.
https://www.electronjs.org/docs/latest/tutorial/quick-start

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API