mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: revised the online-offline event detection feature page (#26017)

Browse source 
* docs: revised the online-offline event detection feature page

* docs: fixed text and grammar mentions
This commit is contained in:
Antonio 2020-10-21 09:46:56 +03:00 committed by GitHub
parent df1432a315
commit 5c6fa7e420
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 78 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

BIN
docs/images/online-event-detection.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 44 KiB

124
docs/tutorial/online-offline-events.md
View file

@ -1,14 +1,30 @@
# Online/Offline Event Detection
[Online and offline event](https://developer.mozilla.org/en-US/docs/Online_and_offline_events) detection can be implemented in the renderer process using the [`navigator.onLine`](http://html5index.org/Offline%20-%20NavigatorOnLine.html) attribute, part of standard HTML5 API.
The `navigator.onLine` attribute returns `false` if any network requests are guaranteed to fail i.e. definitely offline (disconnected from the network). It returns `true` in all other cases.
Since all other conditions return `true`, one has to be mindful of getting false positives, as we cannot assume `true` value necessarily means that Electron can access the internet. Such as in cases where the computer is running a virtualization software that has virtual ethernet adapters that are always “connected.”
Therefore, if you really want to determine the internet access status of Electron,
you should develop additional means for checking.
## Overview
Example:
[Online and offline event](https://developer.mozilla.org/en-US/docs/Online_and_offline_events)
detection can be implemented in the Renderer process using the
[`navigator.onLine`](http://html5index.org/Offline%20-%20NavigatorOnLine.html)
attribute, part of standard HTML5 API.
_main.js_
The `navigator.onLine` attribute returns:
* `false` if all network requests are guaranteed to fail (e.g. when disconnected from the network).
* `true` in all other cases.
Since many cases return `true`, you should treat with care situations of
getting false positives, as we cannot always assume that `true` value means
that Electron can access the Internet. For example, in cases when the computer
is running a virtualization software that has virtual Ethernet adapters in "always
connected" state. Therefore, if you want to determine the Internet access
status of Electron, you should develop additional means for this check.
## Example
### Event detection in the Renderer process
Starting with a working application from the
[Quick Start Guide](quick-start.md), update the `main.js` file
with the following lines:
```javascript
const { app, BrowserWindow } = require('electron')
@ -21,33 +37,39 @@ app.whenReady().then(() => {
})
```
_online-status.html_
create the `online-status.html` file and add the following line before the
closing `</body>` tag:
```html
<!DOCTYPE html>
<html>
<body>
<script>
const alertOnlineStatus = () => {
window.alert(navigator.onLine ? 'online' : 'offline')
}
window.addEventListener('online', alertOnlineStatus)
window.addEventListener('offline', alertOnlineStatus)
alertOnlineStatus()
</script>
</body>
</html>
<script src="renderer.js"></script>
```
There may be instances where you want to respond to these events in the
main process as well. The main process however does not have a
`navigator` object and thus cannot detect these events directly. Using
Electron's inter-process communication utilities, the events can be forwarded
to the main process and handled as needed, as shown in the following example.
and add the `renderer.js` file:
_main.js_
```javascript
const alertOnlineStatus = () => { window.alert(navigator.onLine ? 'online' : 'offline') }
window.addEventListener('online', alertOnlineStatus)
window.addEventListener('offline', alertOnlineStatus)
alertOnlineStatus()
```
After launching the Electron application, you should see the notification:
![Online-offline-event detection](../images/online-event-detection.png)
### Event detection in the Main process
There may be situations when you want to respond to online/offline events in
the Main process as well. The Main process, however, does not have a
`navigator` object and cannot detect these events directly. In this case, you
need to forward the events to the Main process using Electron's inter-process
communication (IPC) utilities.
Starting with a working application from the
[Quick Start Guide](quick-start.md), update the `main.js` file
with the following lines:
```javascript
const { app, BrowserWindow, ipcMain } = require('electron')
@ -63,23 +85,33 @@ ipcMain.on('online-status-changed', (event, status) => {
})
```
_online-status.html_
create the `online-status.html` file and add the following line before the
closing `</body>` tag:
```html
<!DOCTYPE html>
<html>
<body>
<script>
const { ipcRenderer } = require('electron')
const updateOnlineStatus = () => {
ipcRenderer.send('online-status-changed', navigator.onLine ? 'online' : 'offline')
}
window.addEventListener('online', updateOnlineStatus)
window.addEventListener('offline', updateOnlineStatus)
updateOnlineStatus()
</script>
</body>
</html>
<script src="renderer.js"></script>
```
and add the `renderer.js` file:
```javascript
const { ipcRenderer } = require('electron')
const updateOnlineStatus = () => { ipcRenderer.send('online-status-changed', navigator.onLine ? 'online' : 'offline') }
window.addEventListener('online', updateOnlineStatus)
window.addEventListener('offline', updateOnlineStatus)
updateOnlineStatus()
```
After launching the Electron application, you should see the notification in the
Console:
```sh
npm start
> electron@1.0.0 start /electron
> electron .
online
```