Руководство по платформе Electron

Electron — это фреймворк, который использует веб-технологии (HTML, CSS и JS) для создания кроссплатформенных приложений для настольных компьютеров.

Системные требования

Linux

• Python версия 2.7.x. Рекомендуется проверить вашу версию Python, так как некоторые дистрибутивы, например CentOS 6.x, по-прежнему используют Python 2.6.x.

Mac

• Python версия 2.7.x с поддержкой TLS 1.2.
• Xcode, среда разработки для macOS, поставляется с необходимыми инструментами для разработки программного обеспечения для кодирования подписи и компиляции нативного кода для macOS. Версия 8.2.1 или выше.

• Поддержка сборки RedHat

  • Homebrew, один из доступных менеджеров пакетов macOS, используется для установки дополнительных инструментов и зависимостей. Homebrew необходим для установки зависимостей пакетирования RPM. Шаг установки Brew
  • RPM, стандартный менеджер пакетов для множества дистрибутивов Linux, является инструментом, используемым для создания пакета Linux RPM. Для установки этого инструмента используйте следующую команду Homebrew:

  brew install rpm
  

Windows

• Python версия 2.7.10 или выше.
• PowerShell для пользователей Windows 7 должен быть версии 3.0 или выше для подписи приложения.
• Инструменты отладки для Windows — это набор инструментов для расширения возможностей отладки. Рекомендуется установить вместе с Windows SDK 10.0.15063.468.

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

Создание проекта

npm i -g cordova
cordova create sampleApp
cd sampleApp
cordova platform add electron

Примечание: Если вы используете Cordova CLI до версии 9.x, вам необходимо использовать аргумент cordova-electron вместо electron для любой команды, требующей имени платформы. Например:

cordova platform add cordova-electron
cordova run cordova-electron

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

Для предварительного просмотра Electron-приложения не нужно его собирать. Поскольку процесс сборки может быть медленным, рекомендуется передать флаг --nobuild для отключения процесса сборки при предварительном просмотре.

cordova run electron --nobuild

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

Сборки отладки

cordova build electron
cordova build electron --debug

Сборки релизов

cordova build electron --release

Настройка параметров окна приложения

Electron предоставляет множество параметров для управления BrowserWindow. В этом разделе будут рассмотрены некоторые основные параметры. Полный список параметров см. в Документации Electron - Параметры BrowserWindow.

Работая с проектом Cordova, рекомендуется создать файл настроек Electron в корневом каталоге проекта и установить его относительный путь в параметре предпочтений ElectronSettingsFilePath, в файле config.xml.

Пример config.xml:

<platform name="electron">
    <preference name="ElectronSettingsFilePath" value="res/electron/settings.json" />
</platform>

Чтобы переопределить или установить любые параметры BrowserWindow, в этом файле параметры добавляются к свойству browserWindow.

Пример res/electron/settings.json:

{
    "browserWindow": { ... }
}

Как установить размеры окна по умолчанию

По умолчанию width установлено в 800, а height установлено в 600. Это можно изменить, установив свойства width и height.

Пример:

{
    "browserWindow": {
        "width": 1024,
        "height": 768
    }
}

Как заблокировать возможность изменения размера окна

Установив флаг свойства resizable, вы можете заблокировать возможность пользователя изменять размер окна вашего приложения.

Пример:

{
    "browserWindow": {
        "resizable": false
    }
}

Как сделать окно полноэкранным

Используя флаг свойства fullscreen, вы можете запустить приложение в полноэкранном режиме.

Пример:

{
    "browserWindow": {
        "fullscreen": true
    }
}

Как настроить поддержку Node.js и Electron API

Установите флаг свойства nodeIntegration в true. По умолчанию этот флаг свойства установлен в false для поддержки популярных библиотек, которые вставляют символы с такими же именами, которые уже используются Node.js и Electron.

Подробнее об этом можно прочитать в документации Electron: Не могу использовать jQuery/RequireJS/Meteor/AngularJS в Electron.

Пример:

{
    "browserWindow": {
        "webPreferences": {
            "nodeIntegration": false
        }
    }
}

Настройка основного процесса Electron

Если необходимо настроить основной процесс Electron вне рамок настроек Electron, можно добавить изменения непосредственно в файл cdv-electron-main.js, расположенный в {PROJECT_ROOT_DIR}/platform/electron/platform_www/. Это основной процесс приложения.

❗ Однако не рекомендуется изменять этот файл, поскольку процесс обновления cordova-electron заключается в удалении старой платформы перед добавлением новой версии.

DevTools

Флаги --release и --debug управляют отображением DevTools. DevTools отображаются по умолчанию в сборках отладки (without a flag или с --debug). Если вы хотите скрыть DevTools, передайте флаг --release при сборке или запуске приложения.

Примечание: DevTools можно закрыть или открыть вручную в сборке отладки.

Конфигурации сборки

Конфигурации сборки по умолчанию

По умолчанию, без дополнительных настроек, cordova build electron будет собирать пакеты по умолчанию для операционной системы (ОС), которая запускает команду. Ниже приведен список пакетов по умолчанию для каждой ОС.

Linux

Mac

Windows

Настройка конфигураций сборки

Если по какой-либо причине вам необходимо настроить конфигурации сборки, изменения вносятся в файл build.json, расположенный в корневом каталоге проекта. Например, {PROJECT_ROOT_DIR}/build.json. Этот файл содержит все конфигурации сборки для всех платформ (Android, Electron, iOS, Windows).

Пример структуры конфигурации

{
    "electron": {}
}

Поскольку фреймворк Electron предназначен для создания кроссплатформенных приложений, требуется несколько конфигураций для каждой сборки ОС. Узел electron в файле build.json содержит три свойства, которые разделяют конфигурации сборки для каждой ОС.

Пример структуры конфигурации с каждой платформой

{
    "electron": {
        "linux": {},
        "mac": {},
        "windows": {}
    }
}

Каждый узел ОС содержит свойства, используемые для определения генерируемого пакета и способа его подписи.

Свойства ОС:

• package — массив форматов пакетов, которые будут сгенерированы.
• arch — массив архитектур, для которых будет создан каждый пакет.
• signing — объект, содержащий информацию о подписи. См. Конфигурации подписи для получения дополнительной информации.

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

Добавление package

Свойство package — это список массивов пакетов, которые должны быть выведены. Если свойство определено, пакеты по умолчанию не используются, если их не добавить. Порядок пакетов не важен.

Пример конфигурации ниже сгенерирует пакеты tar.gz, dmg и zip для macOS.

{
    "electron": {
        "mac": {
            "package": [
                "dmg",
                "tar.gz",
                "zip"
            ]
        }
    }
}

Доступные пакеты по операционной системе

• [1] Только Windows 10 может создавать пакеты AppX.

Установка архитектуры пакета arch

Свойство arch — это список архитектур, для которых создан каждый пакет. Когда свойство определено, по умолчанию используется только default, если оно не добавлено.

❗ Не все архитектуры доступны для каждой операционной системы. Пожалуйста, ознакомьтесь с Выпусками Electron, чтобы определить допустимые комбинации. Например, macOS (Darwin) поддерживает только x64.

Доступные архитектуры

• ia32
• x64
• armv71
• arm64

Приведенный выше пример сгенерирует пакет x64 dmg.

{
    "electron": {
        "mac": {
            "package": [ "dmg" ],
            "arch": [ "x64" ]
        }
    }
}

Поддержка многоплатформенной сборки

❗ Не все платформы поддерживают эту функцию и могут иметь ограничения.

Сборка для нескольких платформ на одной операционной системе возможна, но имеет ограничения. Рекомендуется, чтобы операционная система сборщика (хост ОС) соответствовала платформе, для которой собирается приложение.

Ниже представлена матрица, показывающая каждую хост ОС и для каких платформ она способна собирать приложения.

Ограничения:

• [1] Если приложение содержит нативные зависимости, оно может быть скомпилировано только на целевой платформе.
• [2] Linux и macOS не могут собирать пакеты Windows Appx для Windows Store.
• [3] Все необходимые системные зависимости, кроме rpm, будут загружены автоматически по требованию. RPM можно установить с помощью brew. (macOS Sierra 10.12+)

Пример ниже включает многоплатформенную сборку для всех ОС и использует настройки сборки по умолчанию.

{
    "electron": {
        "linux": {},
        "mac": {},
        "windows": {}
    }
}

Настройки подписи

Подпись macOS

Существует три типа целевых подписей. (debug, release, и store). Каждый раздел имеет следующие свойства:

Пример конфигурации:

{
    "electron": {
        "mac": {
            "package": [
                "dmg",
                "mas",
                "mas-dev"
            ],
            "signing": {
                "release": {
                    "identity": "APACHE CORDOVA (TEAMID)",
                    "provisioningProfile": "release.mobileprovision"
                }
            }
        }
    }
}

Для подписи macOS есть несколько исключений из того, как используется информация о подписи. По умолчанию все пакеты, за исключением mas и mas-dev, используют настройки подписи debug и release.

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

Случай 1:

cordova build electron --debug

Команда выше:

• Сгенерирует сборку dmg и сборку mas-dev с использованием настроек подписи debug.
• Проигнорирует пакет цели mas.

Случай 2:

cordova build electron --release

Команда выше:

• Сгенерирует сборку dmg с использованием конфигурации release.
• Сгенерирует сборку mas с использованием конфигурации store.
• Проигнорирует пакет цели mas-dev.

Подпись Windows

Информация о подписи состоит из двух типов. (debug, release). Каждый раздел имеет следующие свойства:

Пример конфигурации:

{
    "electron": {
        "windows": {
            "package": [ "nsis" ],
            "signing": {
                "release": {
                    "certificateFile": "path_to_files",
                    "certificatePassword": "password"
                }
            }
        }
    }
}

Подпись Linux

Для сборок Linux требования к подписи отсутствуют.

Плагины

Все плагины на основе браузера могут использоваться с платформой Electron.

При добавлении плагина, если плагин поддерживает как платформу electron, так и платформу browser, то используется часть electron. Если плагин не содержит electron, но содержит реализацию browser, то используется реализация browser.

Внутри Electron используется Chromium (Chrome) в качестве веб-вью. Некоторые плагины могут иметь условия, написанные специально для каждого браузера. В этом случае это может повлиять на поведение, которое предполагалось. Поскольку Electron может поддерживать функции, которых нет в браузере, эти плагины, возможно, потребуется обновить для платформы electron.