docs: revised the online-offline event detection feature page (#26017)
* docs: revised the online-offline event detection feature page * docs: fixed text and grammar mentions
This commit is contained in:
parent
df1432a315
commit
5c6fa7e420
2 changed files with 78 additions and 46 deletions
BIN
docs/images/online-event-detection.png
Normal file
BIN
docs/images/online-event-detection.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 44 KiB |
|
@ -1,14 +1,30 @@
|
||||||
# Online/Offline Event Detection
|
# 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.
|
## Overview
|
||||||
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.
|
|
||||||
|
|
||||||
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
|
```javascript
|
||||||
const { app, BrowserWindow } = require('electron')
|
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
|
```html
|
||||||
<!DOCTYPE html>
|
<script src="renderer.js"></script>
|
||||||
<html>
|
|
||||||
<body>
|
|
||||||
<script>
|
|
||||||
const alertOnlineStatus = () => {
|
|
||||||
window.alert(navigator.onLine ? 'online' : 'offline')
|
|
||||||
}
|
|
||||||
|
|
||||||
window.addEventListener('online', alertOnlineStatus)
|
|
||||||
window.addEventListener('offline', alertOnlineStatus)
|
|
||||||
|
|
||||||
alertOnlineStatus()
|
|
||||||
</script>
|
|
||||||
</body>
|
|
||||||
</html>
|
|
||||||
```
|
```
|
||||||
|
|
||||||
There may be instances where you want to respond to these events in the
|
and add the `renderer.js` file:
|
||||||
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.
|
|
||||||
|
|
||||||
_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
|
```javascript
|
||||||
const { app, BrowserWindow, ipcMain } = require('electron')
|
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
|
```html
|
||||||
<!DOCTYPE html>
|
<script src="renderer.js"></script>
|
||||||
<html>
|
```
|
||||||
<body>
|
|
||||||
<script>
|
and add the `renderer.js` file:
|
||||||
const { ipcRenderer } = require('electron')
|
|
||||||
const updateOnlineStatus = () => {
|
```javascript
|
||||||
ipcRenderer.send('online-status-changed', navigator.onLine ? 'online' : 'offline')
|
const { ipcRenderer } = require('electron')
|
||||||
}
|
const updateOnlineStatus = () => { ipcRenderer.send('online-status-changed', navigator.onLine ? 'online' : 'offline') }
|
||||||
|
|
||||||
window.addEventListener('online', updateOnlineStatus)
|
window.addEventListener('online', updateOnlineStatus)
|
||||||
window.addEventListener('offline', updateOnlineStatus)
|
window.addEventListener('offline', updateOnlineStatus)
|
||||||
|
|
||||||
updateOnlineStatus()
|
updateOnlineStatus()
|
||||||
</script>
|
```
|
||||||
</body>
|
|
||||||
</html>
|
After launching the Electron application, you should see the notification in the
|
||||||
|
Console:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
npm start
|
||||||
|
|
||||||
|
> electron@1.0.0 start /electron
|
||||||
|
> electron .
|
||||||
|
|
||||||
|
online
|
||||||
```
|
```
|
||||||
|
|
Loading…
Reference in a new issue