|
@@ -5,246 +5,18 @@ providing a runtime with rich native (operating system) APIs. You could see it
|
|
|
as a variant of the Node.js runtime that is focused on desktop applications
|
|
|
instead of web servers.
|
|
|
|
|
|
-This doesn't mean Electron is a JavaScript binding to graphical user interface
|
|
|
-(GUI) libraries. Instead, Electron uses web pages as its GUI, so you could also
|
|
|
-see it as a minimal Chromium browser, controlled by JavaScript.
|
|
|
+The old "Quick Start" document that used to live here has been split up into
|
|
|
+two documents:
|
|
|
|
|
|
-### Main Process
|
|
|
+* To check out how a simple Electron app is built, see
|
|
|
+[Writing Your First Electron App][first-app]
|
|
|
+* To check out the process architecture, see
|
|
|
+[Main and Renderer Processes][processes].
|
|
|
|
|
|
-In Electron, the process that runs `package.json`'s `main` script is called
|
|
|
-__the main process__. The script that runs in the main process can display a GUI
|
|
|
-by creating web pages.
|
|
|
+If you just came here to learn about Electron, check out the
|
|
|
+[official guides][readme].
|
|
|
|
|
|
-### Renderer Process
|
|
|
+[first-app]: ./first-app.md
|
|
|
+[processes]: ./electron-apis.md#main-and-renderer-processes
|
|
|
+[readme]: ../README.md
|
|
|
|
|
|
-Since Electron uses Chromium for displaying web pages, Chromium's
|
|
|
-multi-process architecture is also used. Each web page in Electron runs in
|
|
|
-its own process, which is called __the renderer process__.
|
|
|
-
|
|
|
-In normal browsers, web pages usually run in a sandboxed environment and are not
|
|
|
-allowed access to native resources. Electron users, however, have the power to
|
|
|
-use Node.js APIs in web pages allowing lower level operating system
|
|
|
-interactions.
|
|
|
-
|
|
|
-### Differences Between Main Process and Renderer Process
|
|
|
-
|
|
|
-The main process creates web pages by creating `BrowserWindow` instances. Each
|
|
|
-`BrowserWindow` instance runs the web page in its own renderer process. When a
|
|
|
-`BrowserWindow` instance is destroyed, the corresponding renderer process
|
|
|
-is also terminated.
|
|
|
-
|
|
|
-The main process manages all web pages and their corresponding renderer
|
|
|
-processes. Each renderer process is isolated and only cares about the web page
|
|
|
-running in it.
|
|
|
-
|
|
|
-In web pages, calling native GUI related APIs is not allowed because managing
|
|
|
-native GUI resources in web pages is very dangerous and it is easy to leak
|
|
|
-resources. If you want to perform GUI operations in a web page, the renderer
|
|
|
-process of the web page must communicate with the main process to request that
|
|
|
-the main process perform those operations.
|
|
|
-
|
|
|
-In Electron, we have several ways to communicate between the main process and
|
|
|
-renderer processes. Like [`ipcRenderer`](../api/ipc-renderer.md) and
|
|
|
-[`ipcMain`](../api/ipc-main.md) modules for sending messages, and the
|
|
|
-[remote](../api/remote.md) module for RPC style communication. There is also
|
|
|
-an FAQ entry on [how to share data between web pages][share-data].
|
|
|
-
|
|
|
-## Write your First Electron App
|
|
|
-
|
|
|
-Generally, an Electron app is structured like this:
|
|
|
-
|
|
|
-```text
|
|
|
-your-app/
|
|
|
-├── package.json
|
|
|
-├── main.js
|
|
|
-└── index.html
|
|
|
-```
|
|
|
-
|
|
|
-The format of `package.json` is exactly the same as that of Node's modules, and
|
|
|
-the script specified by the `main` field is the startup script of your app,
|
|
|
-which will run the main process. An example of your `package.json` might look
|
|
|
-like this:
|
|
|
-
|
|
|
-```json
|
|
|
-{
|
|
|
- "name" : "your-app",
|
|
|
- "version" : "0.1.0",
|
|
|
- "main" : "main.js"
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-__Note__: If the `main` field is not present in `package.json`, Electron will
|
|
|
-attempt to load an `index.js`.
|
|
|
-
|
|
|
-The `main.js` should create windows and handle system events, a typical
|
|
|
-example being:
|
|
|
-
|
|
|
-```javascript
|
|
|
-const {app, BrowserWindow} = require('electron')
|
|
|
-const path = require('path')
|
|
|
-const url = require('url')
|
|
|
-
|
|
|
-// Keep a global reference of the window object, if you don't, the window will
|
|
|
-// be closed automatically when the JavaScript object is garbage collected.
|
|
|
-let win
|
|
|
-
|
|
|
-function createWindow () {
|
|
|
- // Create the browser window.
|
|
|
- win = new BrowserWindow({width: 800, height: 600})
|
|
|
-
|
|
|
- // and load the index.html of the app.
|
|
|
- win.loadURL(url.format({
|
|
|
- pathname: path.join(__dirname, 'index.html'),
|
|
|
- protocol: 'file:',
|
|
|
- slashes: true
|
|
|
- }))
|
|
|
-
|
|
|
- // Open the DevTools.
|
|
|
- win.webContents.openDevTools()
|
|
|
-
|
|
|
- // Emitted when the window is closed.
|
|
|
- win.on('closed', () => {
|
|
|
- // Dereference the window object, usually you would store windows
|
|
|
- // in an array if your app supports multi windows, this is the time
|
|
|
- // when you should delete the corresponding element.
|
|
|
- win = null
|
|
|
- })
|
|
|
-}
|
|
|
-
|
|
|
-// 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.on('ready', createWindow)
|
|
|
-
|
|
|
-// Quit when all windows are closed.
|
|
|
-app.on('window-all-closed', () => {
|
|
|
- // On macOS it is common for applications and their menu bar
|
|
|
- // to stay active until the user quits explicitly with Cmd + Q
|
|
|
- if (process.platform !== 'darwin') {
|
|
|
- app.quit()
|
|
|
- }
|
|
|
-})
|
|
|
-
|
|
|
-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 (win === null) {
|
|
|
- createWindow()
|
|
|
- }
|
|
|
-})
|
|
|
-
|
|
|
-// 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.
|
|
|
-```
|
|
|
-
|
|
|
-Finally the `index.html` is the web page you want to show:
|
|
|
-
|
|
|
-```html
|
|
|
-<!DOCTYPE html>
|
|
|
-<html>
|
|
|
- <head>
|
|
|
- <meta charset="UTF-8">
|
|
|
- <title>Hello World!</title>
|
|
|
- </head>
|
|
|
- <body>
|
|
|
- <h1>Hello World!</h1>
|
|
|
- We are using node <script>document.write(process.versions.node)</script>,
|
|
|
- Chrome <script>document.write(process.versions.chrome)</script>,
|
|
|
- and Electron <script>document.write(process.versions.electron)</script>.
|
|
|
- </body>
|
|
|
-</html>
|
|
|
-```
|
|
|
-
|
|
|
-## Run your app
|
|
|
-
|
|
|
-Once you've created your initial `main.js`, `index.html`, and `package.json` files,
|
|
|
-you'll probably want to try running your app locally to test it and make sure it's
|
|
|
-working as expected.
|
|
|
-
|
|
|
-### `electron`
|
|
|
-
|
|
|
-[`electron`](https://github.com/electron-userland/electron-prebuilt) is
|
|
|
-an `npm` module that contains pre-compiled versions of Electron.
|
|
|
-
|
|
|
-If you've installed it globally with `npm`, then you will only need to run the
|
|
|
-following in your app's source directory:
|
|
|
-
|
|
|
-```sh
|
|
|
-electron .
|
|
|
-```
|
|
|
-
|
|
|
-If you've installed it locally, then run:
|
|
|
-
|
|
|
-#### macOS / Linux
|
|
|
-
|
|
|
-```sh
|
|
|
-$ ./node_modules/.bin/electron .
|
|
|
-```
|
|
|
-
|
|
|
-#### Windows
|
|
|
-
|
|
|
-```sh
|
|
|
-$ .\node_modules\.bin\electron .
|
|
|
-```
|
|
|
-
|
|
|
-#### Node v8.2.0 and later
|
|
|
-
|
|
|
-```sh
|
|
|
-$ npx electron .
|
|
|
-```
|
|
|
-
|
|
|
-### Manually Downloaded Electron Binary
|
|
|
-
|
|
|
-If you downloaded Electron manually, you can also use the included
|
|
|
-binary to execute your app directly.
|
|
|
-
|
|
|
-#### macOS
|
|
|
-
|
|
|
-```sh
|
|
|
-$ ./Electron.app/Contents/MacOS/Electron your-app/
|
|
|
-```
|
|
|
-
|
|
|
-#### Linux
|
|
|
-
|
|
|
-```sh
|
|
|
-$ ./electron/electron your-app/
|
|
|
-```
|
|
|
-
|
|
|
-#### Windows
|
|
|
-
|
|
|
-```sh
|
|
|
-$ .\electron\electron.exe your-app\
|
|
|
-```
|
|
|
-
|
|
|
-`Electron.app` here is part of the Electron's release package, you can download
|
|
|
-it from [here](https://github.com/electron/electron/releases).
|
|
|
-
|
|
|
-### Run as a distribution
|
|
|
-
|
|
|
-After you're done writing your app, you can create a distribution by
|
|
|
-following the [Application Distribution](./application-distribution.md) guide
|
|
|
-and then executing the packaged app.
|
|
|
-
|
|
|
-### Try this Example
|
|
|
-
|
|
|
-Clone and run the code in this tutorial by using the [`electron/electron-quick-start`](https://github.com/electron/electron-quick-start)
|
|
|
-repository.
|
|
|
-
|
|
|
-**Note**: Running this requires [Git](https://git-scm.com) and [Node.js](https://nodejs.org/en/download/) (which includes [npm](https://npmjs.org)) on your system.
|
|
|
-
|
|
|
-```sh
|
|
|
-# Clone the repository
|
|
|
-$ git clone https://github.com/electron/electron-quick-start
|
|
|
-# Go into the repository
|
|
|
-$ cd electron-quick-start
|
|
|
-# Install dependencies
|
|
|
-$ npm install
|
|
|
-# Run the app
|
|
|
-$ npm start
|
|
|
-```
|
|
|
-
|
|
|
-For more example apps, see the
|
|
|
-[list of boilerplates](https://electronjs.org/community#boilerplates)
|
|
|
-created by the awesome electron community.
|
|
|
-
|
|
|
-[share-data]: ../faq.md#how-to-share-data-between-web-pages
|