docs: Improved documentation (#13403)
This commit is contained in:
Tiago Danin
Shelley Vohr
parent
2440d03595
commit
1fd6d38a0a
18 changed files with 79 additions and 79 deletions
|
|
@ -881,7 +881,7 @@ Changes the [Application User Model ID][app-user-model-id] to `id`.
|
|||
|
||||
Imports the certificate in pkcs12 format into the platform certificate store.
|
||||
`callback` is called with the `result` of import operation, a value of `0`
|
||||
indicates success while any other value indicates failure according to chromium [net_error_list](https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h).
|
||||
indicates success while any other value indicates failure according to Chromium [net_error_list](https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h).
|
||||
|
||||
### `app.disableHardwareAcceleration()`
|
||||
|
||||
|
|
@ -1033,7 +1033,7 @@ const stopAccessingSecurityScopedResource = app.startAccessingSecurityScopedReso
|
|||
stopAccessingSecurityScopedResource()
|
||||
```
|
||||
|
||||
Start accessing a security scoped resource. With this method electron applications that are packaged for the Mac App Store may reach outside their sandbox to access files chosen by the user. See [Apple's documentation](https://developer.apple.com/library/content/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW16) for a description of how this system works.
|
||||
Start accessing a security scoped resource. With this method Electron applications that are packaged for the Mac App Store may reach outside their sandbox to access files chosen by the user. See [Apple's documentation](https://developer.apple.com/library/content/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW16) for a description of how this system works.
|
||||
|
||||
### `app.commandLine.appendSwitch(switch[, value])`
|
||||
|
||||
|
|
|
|||
|
|
@ -59,11 +59,11 @@ The `role` property can have following values:
|
|||
* `delete`
|
||||
* `minimize` - Minimize current window.
|
||||
* `close` - Close current window.
|
||||
* `quit`- Quit the application.
|
||||
* `quit` - Quit the application.
|
||||
* `reload` - Reload the current window.
|
||||
* `forceReload` - Reload the current window ignoring the cache.
|
||||
* `toggleDevTools` - Toggle developer tools in the current window.
|
||||
* `toggleFullScreen`- Toggle full screen mode on the current window.
|
||||
* `toggleFullScreen` - Toggle full screen mode on the current window.
|
||||
* `resetZoom` - Reset the focused page's zoom level to the original size.
|
||||
* `zoomIn` - Zoom in the focused page by 10%.
|
||||
* `zoomOut` - Zoom out the focused page by 10%.
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
> Create a browser window with a renderer that can run inside Chromium OS sandbox. With this
|
||||
option enabled, the renderer must communicate via IPC to the main process in order to access node APIs.
|
||||
However, in order to enable the Chromium OS sandbox, electron must be run with the `--enable-sandbox`
|
||||
However, in order to enable the Chromium OS sandbox, Electron must be run with the `--enable-sandbox`
|
||||
command line argument.
|
||||
|
||||
One of the key security features of Chromium is that all blink rendering/JavaScript
|
||||
|
|
@ -14,26 +14,26 @@ to the system by delegating tasks to the main process via IPC.
|
|||
[Here's](https://www.chromium.org/developers/design-documents/sandbox) more
|
||||
information about the sandbox.
|
||||
|
||||
Since a major feature in electron is the ability to run node.js in the
|
||||
Since a major feature in Electron is the ability to run Node.js in the
|
||||
renderer process (making it easier to develop desktop applications using web
|
||||
technologies), the sandbox is disabled by electron. This is because
|
||||
most node.js APIs require system access. `require()` for example, is not
|
||||
most Node.js APIs require system access. `require()` for example, is not
|
||||
possible without file system permissions, which are not available in a sandboxed
|
||||
environment.
|
||||
|
||||
Usually this is not a problem for desktop applications since the code is always
|
||||
trusted, but it makes electron less secure than chromium for displaying
|
||||
trusted, but it makes Electron less secure than Chromium for displaying
|
||||
untrusted web content. For applications that require more security, the
|
||||
`sandbox` flag will force electron to spawn a classic chromium renderer that is
|
||||
`sandbox` flag will force Electron to spawn a classic Chromium renderer that is
|
||||
compatible with the sandbox.
|
||||
|
||||
A sandboxed renderer doesn't have a node.js environment running and doesn't
|
||||
expose node.js JavaScript APIs to client code. The only exception is the preload script,
|
||||
which has access to a subset of the electron renderer API.
|
||||
A sandboxed renderer doesn't have a Node.js environment running and doesn't
|
||||
expose Node.js JavaScript APIs to client code. The only exception is the preload script,
|
||||
which has access to a subset of the Electron renderer API.
|
||||
|
||||
Another difference is that sandboxed renderers don't modify any of the default
|
||||
JavaScript APIs. Consequently, some APIs such as `window.open` will work as they
|
||||
do in chromium (i.e. they do not return a [`BrowserWindowProxy`](browser-window-proxy.md)).
|
||||
do in Chromium (i.e. they do not return a [`BrowserWindowProxy`](browser-window-proxy.md)).
|
||||
|
||||
## Example
|
||||
|
||||
|
|
@ -51,9 +51,9 @@ app.on('ready', () => {
|
|||
})
|
||||
```
|
||||
|
||||
In the above code the [`BrowserWindow`](browser-window.md) that was created has node.js disabled and can communicate
|
||||
only via IPC. The use of this option stops electron from creating a node.js runtime in the renderer. Also,
|
||||
within this new window `window.open` follows the native behaviour (by default electron creates a [`BrowserWindow`](browser-window.md)
|
||||
In the above code the [`BrowserWindow`](browser-window.md) that was created has Node.js disabled and can communicate
|
||||
only via IPC. The use of this option stops Electron from creating a Node.js runtime in the renderer. Also,
|
||||
within this new window `window.open` follows the native behaviour (by default Electron creates a [`BrowserWindow`](browser-window.md)
|
||||
and returns a proxy to this via `window.open`).
|
||||
|
||||
It is important to note that this option alone won't enable the OS-enforced sandbox. To enable this feature, the
|
||||
|
|
@ -75,19 +75,19 @@ app.on('ready', () => {
|
|||
|
||||
Note that it is not enough to call
|
||||
`app.commandLine.appendSwitch('--enable-sandbox')`, as electron/node startup
|
||||
code runs after it is possible to make changes to chromium sandbox settings. The
|
||||
switch must be passed to electron on the command-line:
|
||||
code runs after it is possible to make changes to Chromium sandbox settings. The
|
||||
switch must be passed to Electron on the command-line:
|
||||
|
||||
```sh
|
||||
electron --enable-sandbox app.js
|
||||
```
|
||||
|
||||
It is not possible to have the OS sandbox active only for some renderers, if
|
||||
`--enable-sandbox` is enabled, normal electron windows cannot be created.
|
||||
`--enable-sandbox` is enabled, normal Electron windows cannot be created.
|
||||
|
||||
If you need to mix sandboxed and non-sandboxed renderers in one application,
|
||||
omit the `--enable-sandbox` argument. Without this argument, windows
|
||||
created with `sandbox: true` will still have node.js disabled and communicate
|
||||
created with `sandbox: true` will still have Node.js disabled and communicate
|
||||
only via IPC, which by itself is already a gain from security POV.
|
||||
|
||||
## Preload
|
||||
|
|
@ -112,7 +112,7 @@ and preload.js:
|
|||
|
||||
```js
|
||||
// This file is loaded whenever a javascript context is created. It runs in a
|
||||
// private scope that can access a subset of electron renderer APIs. We must be
|
||||
// private scope that can access a subset of Electron renderer APIs. We must be
|
||||
// careful to not leak any objects into the global scope!
|
||||
const fs = require('fs')
|
||||
const {ipcRenderer} = require('electron')
|
||||
|
|
@ -136,7 +136,7 @@ window.open = customWindowOpen
|
|||
|
||||
Important things to notice in the preload script:
|
||||
|
||||
- Even though the sandboxed renderer doesn't have node.js running, it still has
|
||||
- Even though the sandboxed renderer doesn't have Node.js running, it still has
|
||||
access to a limited node-like environment: `Buffer`, `process`, `setImmediate`
|
||||
and `require` are available.
|
||||
- The preload script can indirectly access all APIs from the main process through the
|
||||
|
|
@ -146,7 +146,7 @@ Important things to notice in the preload script:
|
|||
- The preload script must be contained in a single script, but it is possible to have
|
||||
complex preload code composed with multiple modules by using a tool like
|
||||
browserify, as explained below. In fact, browserify is already used by
|
||||
electron to provide a node-like environment to the preload script.
|
||||
Electron to provide a node-like environment to the preload script.
|
||||
|
||||
To create a browserify bundle and use it as a preload script, something like
|
||||
the following should be used:
|
||||
|
|
@ -178,7 +178,7 @@ following modules:
|
|||
- `timers`
|
||||
- `url`
|
||||
|
||||
More may be added as needed to expose more electron APIs in the sandbox, but any
|
||||
More may be added as needed to expose more Electron APIs in the sandbox, but any
|
||||
module in the main process can already be used through
|
||||
`electron.remote.require`.
|
||||
|
||||
|
|
@ -186,7 +186,7 @@ module in the main process can already be used through
|
|||
|
||||
Please use the `sandbox` option with care, as it is still an experimental
|
||||
feature. We are still not aware of the security implications of exposing some
|
||||
electron renderer APIs to the preload script, but here are some things to
|
||||
Electron renderer APIs to the preload script, but here are some things to
|
||||
consider before rendering untrusted content:
|
||||
|
||||
- A preload script can accidentally leak privileged APIs to untrusted code.
|
||||
|
|
@ -194,9 +194,9 @@ consider before rendering untrusted content:
|
|||
APIs, effectively granting full access to the system through the `remote`
|
||||
module.
|
||||
|
||||
Since rendering untrusted content in electron is still uncharted territory,
|
||||
Since rendering untrusted content in Electron is still uncharted territory,
|
||||
the APIs exposed to the sandbox preload script should be considered more
|
||||
unstable than the rest of electron APIs, and may have breaking changes to fix
|
||||
unstable than the rest of Electron APIs, and may have breaking changes to fix
|
||||
security issues.
|
||||
|
||||
One planned enhancement that should greatly increase security is to block IPC
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
# CertificatePrincipal Object
|
||||
|
||||
* `commonName` String - Common Name
|
||||
* `organizations` String[] - Organization names
|
||||
* `organizationUnits` String[] - Organization Unit names
|
||||
* `locality` String - Locality
|
||||
* `state` String - State or province
|
||||
* `country` String - Country or region
|
||||
* `commonName` String - Common Name.
|
||||
* `organizations` String[] - Organization names.
|
||||
* `organizationUnits` String[] - Organization Unit names.
|
||||
* `locality` String - Locality.
|
||||
* `state` String - State or province.
|
||||
* `country` String - Country or region.
|
||||
|
|
|
|||
|
|
@ -1,18 +1,18 @@
|
|||
# GPUFeatureStatus Object
|
||||
|
||||
* `2d_canvas` String - Canvas
|
||||
* `flash_3d` String - Flash
|
||||
* `flash_stage3d` String - Flash Stage3D
|
||||
* `flash_stage3d_baseline` String - Flash Stage3D Baseline profile
|
||||
* `gpu_compositing` String - Compositing
|
||||
* `multiple_raster_threads` String - Multiple Raster Threads
|
||||
* `native_gpu_memory_buffers` String - Native GpuMemoryBuffers
|
||||
* `rasterization` String - Rasterization
|
||||
* `video_decode` String - Video Decode
|
||||
* `video_encode` String - Video Encode
|
||||
* `vpx_decode` String - VPx Video Decode
|
||||
* `webgl` String - WebGL
|
||||
* `webgl2` String - WebGL2
|
||||
* `2d_canvas` String - Canvas.
|
||||
* `flash_3d` String - Flash.
|
||||
* `flash_stage3d` String - Flash Stage3D.
|
||||
* `flash_stage3d_baseline` String - Flash Stage3D Baseline profile.
|
||||
* `gpu_compositing` String - Compositing.
|
||||
* `multiple_raster_threads` String - Multiple Raster Threads.
|
||||
* `native_gpu_memory_buffers` String - Native GpuMemoryBuffers.
|
||||
* `rasterization` String - Rasterization.
|
||||
* `video_decode` String - Video Decode.
|
||||
* `video_encode` String - Video Encode.
|
||||
* `vpx_decode` String - VPx Video Decode.
|
||||
* `webgl` String - WebGL.
|
||||
* `webgl2` String - WebGL2.
|
||||
|
||||
Possible values:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# MimeTypedBuffer Object
|
||||
|
||||
* `mimeType` String - The mimeType of the Buffer that you are sending
|
||||
* `data` Buffer - The actual Buffer content
|
||||
* `mimeType` String - The mimeType of the Buffer that you are sending.
|
||||
* `data` Buffer - The actual Buffer content.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Rectangle Object
|
||||
|
||||
* `x` Number - The x coordinate of the origin of the rectangle (must be an integer)
|
||||
* `y` Number - The y coordinate of the origin of the rectangle (must be an integer)
|
||||
* `width` Number - The width of the rectangle (must be an integer)
|
||||
* `height` Number - The height of the rectangle (must be an integer)
|
||||
* `x` Number - The x coordinate of the origin of the rectangle (must be an integer).
|
||||
* `y` Number - The y coordinate of the origin of the rectangle (must be an integer).
|
||||
* `width` Number - The width of the rectangle (must be an integer).
|
||||
* `height` Number - The height of the rectangle (must be an integer).
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# ScrubberItem Object
|
||||
|
||||
* `label` String (optional) - The text to appear in this item
|
||||
* `icon` NativeImage (optional) - The image to appear in this item
|
||||
* `label` String (optional) - The text to appear in this item.
|
||||
* `icon` NativeImage (optional) - The image to appear in this item.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
# SegmentedControlSegment Object
|
||||
|
||||
* `label` String (optional) - The text to appear in this segment
|
||||
* `icon` NativeImage (optional) - The image to appear in this segment
|
||||
* `enabled` Boolean (optional) - Whether this segment is selectable. Default: true
|
||||
* `label` String (optional) - The text to appear in this segment.
|
||||
* `icon` NativeImage (optional) - The image to appear in this segment.
|
||||
* `enabled` Boolean (optional) - Whether this segment is selectable. Default: true.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
# StreamProtocolResponse Object
|
||||
|
||||
* `statusCode` Number - The HTTP response code
|
||||
* `headers` Object - An object containing the response headers
|
||||
* `data` ReadableStream - A Node.js readable stream representing the response body
|
||||
* `statusCode` Number - The HTTP response code.
|
||||
* `headers` Object - An object containing the response headers.
|
||||
* `data` ReadableStream - A Node.js readable stream representing the response body.
|
||||
|
|
|
|||
|
|
@ -1468,7 +1468,7 @@ process.
|
|||
|
||||
#### `contents.getProcessId()`
|
||||
|
||||
Returns `Integer` - The chromium internal `pid` of the associated renderer. Can
|
||||
Returns `Integer` - The Chromium internal `pid` of the associated renderer. Can
|
||||
be compared to the `frameProcessId` passed by frame specific navigation events
|
||||
(e.g. `did-frame-navigate`)
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
Process: [Renderer](../glossary.md#renderer-process)
|
||||
|
||||
`webFrame` export of the electron module is an instance of the `WebFrame`
|
||||
`webFrame` export of the Electron module is an instance of the `WebFrame`
|
||||
class representing the top frame of the current `BrowserWindow`. Sub-frames can
|
||||
be retrieved by certain properties and methods (e.g. `webFrame.firstChild`).
|
||||
|
||||
|
|
|
|||
|
|
@ -87,7 +87,7 @@ this document :)
|
|||
## Tests
|
||||
|
||||
To run the tests, you'll first need to build the test modules against the
|
||||
same version of node.js that was built as part of the build process.
|
||||
same version of Node.js that was built as part of the build process.
|
||||
|
||||
```sh
|
||||
$ (cd electron/spec && npm i --nodedir=../../third_party/electron_node)
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ etc.
|
|||
|
||||
## Documentation
|
||||
|
||||
* Write [remark](https://github.com/remarkjs/remark) markdown style
|
||||
* Write [remark](https://github.com/remarkjs/remark) markdown style.
|
||||
|
||||
You can run `npm run lint-docs` to ensure that your documentation changes are
|
||||
formatted correctly.
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
## Debugging with XCode
|
||||
|
||||
### Build Debug Electron with Release libchromiumcontent
|
||||
You can create a debug build of electron by following [build instructions for macOS](build-instructions-osx.md).
|
||||
You can create a debug build of Electron by following [build instructions for macOS](build-instructions-osx.md).
|
||||
The bootstrap process will download Release version of libchromiumcontent by default,
|
||||
so you will not be able to step through the chromium source.
|
||||
so you will not be able to step through the Chromium source.
|
||||
|
||||
### Build Debug Electron with Debug libchromiumcontent
|
||||
If you want to debug and step through libchromiumcontent, you will have to run the
|
||||
|
|
@ -25,7 +25,7 @@ Electron debug builds will use this shared library to link against.
|
|||
```sh
|
||||
$ ./script/build.py -c D --libcc
|
||||
```
|
||||
This will build debug electron with debug version of libchromiumcontent.
|
||||
This will build debug Electron with debug version of libchromiumcontent.
|
||||
|
||||
### Generate xcode project for debugging sources (cannot build code from xcode)
|
||||
Run the update script with the --xcode argument.
|
||||
|
|
@ -37,14 +37,14 @@ to set breakpoints and inspect.
|
|||
|
||||
### Debugging and breakpoints
|
||||
|
||||
Launch electron app after build.
|
||||
You can now open the xcode workspace created above and attach to the electron process
|
||||
Launch Electron app after build.
|
||||
You can now open the xcode workspace created above and attach to the Electron process
|
||||
through the Debug > Attach To Process > Electron debug menu. [Note: If you want to debug
|
||||
the renderer process, you need to attach to the Electron Helper as well.]
|
||||
|
||||
You can now set breakpoints in any of the indexed files. However, you will not be able
|
||||
to set breakpoints directly in the chromium source.
|
||||
To set break points in the chromium source, you can choose Debug > Breakpoints > Create
|
||||
to set breakpoints directly in the Chromium source.
|
||||
To set break points in the Chromium source, you can choose Debug > Breakpoints > Create
|
||||
Symbolic Breakpoint and set any function name as the symbol. This will set the breakpoint
|
||||
for all functions with that name, from all the classes if there are more than one.
|
||||
You can also do this step of setting break points prior to attaching the debugger,
|
||||
|
|
|
|||
|
|
@ -141,7 +141,7 @@ we appreciate your help.
|
|||
2. Create a new S3 bucket and create the following empty directory structure:
|
||||
|
||||
```sh
|
||||
- atom-shell/
|
||||
- electron/
|
||||
- symbols/
|
||||
- dist/
|
||||
```
|
||||
|
|
@ -150,7 +150,7 @@ we appreciate your help.
|
|||
|
||||
* `ELECTRON_GITHUB_TOKEN` - a token that can create releases on GitHub
|
||||
* `ELECTRON_S3_ACCESS_KEY`, `ELECTRON_S3_BUCKET`, `ELECTRON_S3_SECRET_KEY` -
|
||||
the place where you'll upload node.js headers as well as symbols
|
||||
the place where you'll upload Node.js headers as well as symbols
|
||||
* `ELECTRON_RELEASE` - Set to `true` and the upload part will run, leave unset
|
||||
and `surf-build` will do CI-type checks, appropriate to run for every
|
||||
pull request.
|
||||
|
|
|
|||
|
|
@ -49,7 +49,7 @@ Below is a table explicitly mapping types of changes to their corresponding cate
|
|||
| Chromium version updates | | fix-related chromium patches |
|
||||
|
||||
|
||||
Note that most chromium updates will be considered breaking. Fixes that can be backported will likely be cherry-picked as patches.
|
||||
Note that most Chromium updates will be considered breaking. Fixes that can be backported will likely be cherry-picked as patches.
|
||||
|
||||
# Stabilization Branches
|
||||
|
||||
|
|
|
|||
|
|
@ -164,7 +164,7 @@ To test your application without rebuilding Electron,
|
|||
[place](https://github.com/electron/electron/blob/master/docs/tutorial/application-distribution.md)
|
||||
your app source into Electron's resource directory.
|
||||
|
||||
Alternatively, pass an argument to run with your electron binary that points to
|
||||
Alternatively, pass an argument to run with your Electron binary that points to
|
||||
your app's folder. This eliminates the need to copy-paste your app into
|
||||
Electron's resource directory.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue