Merge pull request #7969 from electron/one-file-per-api
move each API doc into its own file
This commit is contained in:
Zeke Sikelianos
GitHub
commit
1b5b29901c
21 changed files with 807 additions and 818 deletions
53
docs/api/browser-window-proxy.md
Normal file
53
docs/api/browser-window-proxy.md
Normal file
|
|
@ -0,0 +1,53 @@
|
||||||
|
## Class: BrowserWindowProxy
|
||||||
|
|
||||||
|
> Manipulate the child browser window
|
||||||
|
|
||||||
|
Process: [Renderer](../tutorial/quick-start.md#renderer-process)
|
||||||
|
|
||||||
|
The `BrowserWindowProxy` object is returned from `window.open` and provides
|
||||||
|
limited functionality with the child window.
|
||||||
|
|
||||||
|
### Instance Methods
|
||||||
|
|
||||||
|
The `BrowserWindowProxy` object has the following instance methods:
|
||||||
|
|
||||||
|
#### `win.blur()`
|
||||||
|
|
||||||
|
Removes focus from the child window.
|
||||||
|
|
||||||
|
#### `win.close()`
|
||||||
|
|
||||||
|
Forcefully closes the child window without calling its unload event.
|
||||||
|
|
||||||
|
#### `win.eval(code)`
|
||||||
|
|
||||||
|
* `code` String
|
||||||
|
|
||||||
|
Evaluates the code in the child window.
|
||||||
|
|
||||||
|
#### `win.focus()`
|
||||||
|
|
||||||
|
Focuses the child window (brings the window to front).
|
||||||
|
|
||||||
|
#### `win.print()`
|
||||||
|
|
||||||
|
Invokes the print dialog on the child window.
|
||||||
|
|
||||||
|
#### `win.postMessage(message, targetOrigin)`
|
||||||
|
|
||||||
|
* `message` String
|
||||||
|
* `targetOrigin` String
|
||||||
|
|
||||||
|
Sends a message to the child window with the specified origin or `*` for no
|
||||||
|
origin preference.
|
||||||
|
|
||||||
|
In addition to these methods, the child window implements `window.opener` object
|
||||||
|
with no properties and a single method.
|
||||||
|
|
||||||
|
### Instance Properties
|
||||||
|
|
||||||
|
The `BrowserWindowProxy` object has the following instance properties:
|
||||||
|
|
||||||
|
#### `win.closed`
|
||||||
|
|
||||||
|
A Boolean that is set to true after the child window gets closed.
|
||||||
|
|
@ -109,6 +109,10 @@ child.once('ready-to-show', () => {
|
||||||
|
|
||||||
## Class: BrowserWindow
|
## Class: BrowserWindow
|
||||||
|
|
||||||
|
> Create and control browser windows.
|
||||||
|
|
||||||
|
Process: [Main](../tutorial/quick-start.md#main-process)
|
||||||
|
|
||||||
`BrowserWindow` is an
|
`BrowserWindow` is an
|
||||||
[EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter).
|
[EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter).
|
||||||
|
|
||||||
|
|
|
||||||
192
docs/api/client-request.md
Normal file
192
docs/api/client-request.md
Normal file
|
|
@ -0,0 +1,192 @@
|
||||||
|
## Class: ClientRequest
|
||||||
|
|
||||||
|
> Make HTTP/HTTPS requests.
|
||||||
|
|
||||||
|
Process: [Main](../tutorial/quick-start.md#main-process)
|
||||||
|
|
||||||
|
`ClientRequest` implements the [Writable Stream](https://nodejs.org/api/stream.html#stream_writable_streams)
|
||||||
|
interface and is therefore an [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter).
|
||||||
|
|
||||||
|
### `new ClientRequest(options)`
|
||||||
|
|
||||||
|
* `options` (Object | String) - If `options` is a String, it is interpreted as
|
||||||
|
the request URL. If it is an object, it is expected to fully specify an HTTP request via the
|
||||||
|
following properties:
|
||||||
|
* `method` String (optional) - The HTTP request method. Defaults to the GET
|
||||||
|
method.
|
||||||
|
* `url` String (optional) - The request URL. Must be provided in the absolute
|
||||||
|
form with the protocol scheme specified as http or https.
|
||||||
|
* `session` Object (optional) - The [`Session`](session.md) instance with
|
||||||
|
which the request is associated.
|
||||||
|
* `partition` String (optional) - The name of the [`partition`](session.md)
|
||||||
|
with which the request is associated. Defaults to the empty string. The
|
||||||
|
`session` option prevails on `partition`. Thus if a `session` is explicitly
|
||||||
|
specified, `partition` is ignored.
|
||||||
|
* `protocol` String (optional) - The protocol scheme in the form 'scheme:'.
|
||||||
|
Currently supported values are 'http:' or 'https:'. Defaults to 'http:'.
|
||||||
|
* `host` String (optional) - The server host provided as a concatenation of
|
||||||
|
the hostname and the port number 'hostname:port'
|
||||||
|
* `hostname` String (optional) - The server host name.
|
||||||
|
* `port` Integer (optional) - The server's listening port number.
|
||||||
|
* `path` String (optional) - The path part of the request URL.
|
||||||
|
|
||||||
|
`options` properties such as `protocol`, `host`, `hostname`, `port` and `path`
|
||||||
|
strictly follow the Node.js model as described in the
|
||||||
|
[URL](https://nodejs.org/api/url.html) module.
|
||||||
|
|
||||||
|
For instance, we could have created the same request to 'github.com' as follows:
|
||||||
|
|
||||||
|
```JavaScript
|
||||||
|
const request = net.request({
|
||||||
|
method: 'GET',
|
||||||
|
protocol: 'https:',
|
||||||
|
hostname: 'github.com',
|
||||||
|
port: 443,
|
||||||
|
path: '/'
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
### Instance Events
|
||||||
|
|
||||||
|
#### Event: 'response'
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
|
||||||
|
* `response` IncomingMessage - An object representing the HTTP response message.
|
||||||
|
|
||||||
|
#### Event: 'login'
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
|
||||||
|
* `authInfo` Object
|
||||||
|
* `isProxy` Boolean
|
||||||
|
* `scheme` String
|
||||||
|
* `host` String
|
||||||
|
* `port` Integer
|
||||||
|
* `realm` String
|
||||||
|
* `callback` Function
|
||||||
|
|
||||||
|
Emitted when an authenticating proxy is asking for user credentials.
|
||||||
|
|
||||||
|
The `callback` function is expected to be called back with user credentials:
|
||||||
|
|
||||||
|
* `username` String
|
||||||
|
* `password` String
|
||||||
|
|
||||||
|
```JavaScript
|
||||||
|
request.on('login', (authInfo, callback) => {
|
||||||
|
callback('username', 'password')
|
||||||
|
})
|
||||||
|
```
|
||||||
|
Providing empty credentials will cancel the request and report an authentication
|
||||||
|
error on the response object:
|
||||||
|
|
||||||
|
```JavaScript
|
||||||
|
request.on('response', (response) => {
|
||||||
|
console.log(`STATUS: ${response.statusCode}`);
|
||||||
|
response.on('error', (error) => {
|
||||||
|
console.log(`ERROR: ${JSON.stringify(error)}`)
|
||||||
|
})
|
||||||
|
})
|
||||||
|
request.on('login', (authInfo, callback) => {
|
||||||
|
callback()
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Event: 'finish'
|
||||||
|
|
||||||
|
Emitted just after the last chunk of the `request`'s data has been written into
|
||||||
|
the `request` object.
|
||||||
|
|
||||||
|
#### Event: 'abort'
|
||||||
|
|
||||||
|
Emitted when the `request` is aborted. The `abort` event will not be fired if
|
||||||
|
the `request` is already closed.
|
||||||
|
|
||||||
|
#### Event: 'error'
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
|
||||||
|
* `error` Error - an error object providing some information about the failure.
|
||||||
|
|
||||||
|
Emitted when the `net` module fails to issue a network request. Typically when
|
||||||
|
the `request` object emits an `error` event, a `close` event will subsequently
|
||||||
|
follow and no response object will be provided.
|
||||||
|
|
||||||
|
#### Event: 'close'
|
||||||
|
|
||||||
|
Emitted as the last event in the HTTP request-response transaction. The `close`
|
||||||
|
event indicates that no more events will be emitted on either the `request` or
|
||||||
|
`response` objects.
|
||||||
|
|
||||||
|
### Instance Properties
|
||||||
|
|
||||||
|
#### `request.chunkedEncoding`
|
||||||
|
|
||||||
|
A Boolean specifying whether the request will use HTTP chunked transfer encoding
|
||||||
|
or not. Defaults to false. The property is readable and writable, however it can
|
||||||
|
be set only before the first write operation as the HTTP headers are not yet put
|
||||||
|
on the wire. Trying to set the `chunkedEncoding` property after the first write
|
||||||
|
will throw an error.
|
||||||
|
|
||||||
|
Using chunked encoding is strongly recommended if you need to send a large
|
||||||
|
request body as data will be streamed in small chunks instead of being
|
||||||
|
internally buffered inside Electron process memory.
|
||||||
|
|
||||||
|
### Instance Methods
|
||||||
|
|
||||||
|
#### `request.setHeader(name, value)`
|
||||||
|
|
||||||
|
* `name` String - An extra HTTP header name.
|
||||||
|
* `value` String - An extra HTTP header value.
|
||||||
|
|
||||||
|
Adds an extra HTTP header. The header name will issued as it is without
|
||||||
|
lowercasing. It can be called only before first write. Calling this method after
|
||||||
|
the first write will throw an error.
|
||||||
|
|
||||||
|
#### `request.getHeader(name)`
|
||||||
|
|
||||||
|
* `name` String - Specify an extra header name.
|
||||||
|
|
||||||
|
Returns String - The value of a previously set extra header name.
|
||||||
|
|
||||||
|
#### `request.removeHeader(name)`
|
||||||
|
|
||||||
|
* `name` String - Specify an extra header name.
|
||||||
|
|
||||||
|
Removes a previously set extra header name. This method can be called only
|
||||||
|
before first write. Trying to call it after the first write will throw an error.
|
||||||
|
|
||||||
|
#### `request.write(chunk[, encoding][, callback])`
|
||||||
|
|
||||||
|
* `chunk` (String | Buffer) - A chunk of the request body's data. If it is a
|
||||||
|
string, it is converted into a Buffer using the specified encoding.
|
||||||
|
* `encoding` String (optional) - Used to convert string chunks into Buffer
|
||||||
|
objects. Defaults to 'utf-8'.
|
||||||
|
* `callback` Function (optional) - Called after the write operation ends.
|
||||||
|
|
||||||
|
`callback` is essentially a dummy function introduced in the purpose of keeping
|
||||||
|
similarity with the Node.js API. It is called asynchronously in the next tick
|
||||||
|
after `chunk` content have been delivered to the Chromium networking layer.
|
||||||
|
Contrary to the Node.js implementation, it is not guaranteed that `chunk`
|
||||||
|
content have been flushed on the wire before `callback` is called.
|
||||||
|
|
||||||
|
Adds a chunk of data to the request body. The first write operation may cause
|
||||||
|
the request headers to be issued on the wire. After the first write operation,
|
||||||
|
it is not allowed to add or remove a custom header.
|
||||||
|
|
||||||
|
#### `request.end([chunk][, encoding][, callback])`
|
||||||
|
|
||||||
|
* `chunk` (String | Buffer) (optional)
|
||||||
|
* `encoding` String (optional)
|
||||||
|
* `callback` Function (optional)
|
||||||
|
|
||||||
|
Sends the last chunk of the request data. Subsequent write or end operations
|
||||||
|
will not be allowed. The `finish` event is emitted just after the end operation.
|
||||||
|
|
||||||
|
#### `request.abort()`
|
||||||
|
|
||||||
|
Cancels an ongoing HTTP transaction. If the request has already emitted the
|
||||||
|
`close` event, the abort operation will have no effect. Otherwise an ongoing
|
||||||
|
event will emit `abort` and `close` events. Additionally, if there is an ongoing
|
||||||
|
response object,it will emit the `aborted` event.
|
||||||
106
docs/api/cookies.md
Normal file
106
docs/api/cookies.md
Normal file
|
|
@ -0,0 +1,106 @@
|
||||||
|
## Class: Cookies
|
||||||
|
|
||||||
|
> Query and modify a session's cookies.
|
||||||
|
|
||||||
|
Process: [Main](../tutorial/quick-start.md#main-process)
|
||||||
|
|
||||||
|
Instances of the `Cookies` class are accessed by using `cookies` property of
|
||||||
|
a `Session`.
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
const {session} = require('electron')
|
||||||
|
|
||||||
|
// Query all cookies.
|
||||||
|
session.defaultSession.cookies.get({}, (error, cookies) => {
|
||||||
|
console.log(error, cookies)
|
||||||
|
})
|
||||||
|
|
||||||
|
// Query all cookies associated with a specific url.
|
||||||
|
session.defaultSession.cookies.get({url: 'http://www.github.com'}, (error, cookies) => {
|
||||||
|
console.log(error, cookies)
|
||||||
|
})
|
||||||
|
|
||||||
|
// Set a cookie with the given cookie data;
|
||||||
|
// may overwrite equivalent cookies if they exist.
|
||||||
|
const cookie = {url: 'http://www.github.com', name: 'dummy_name', value: 'dummy'}
|
||||||
|
session.defaultSession.cookies.set(cookie, (error) => {
|
||||||
|
if (error) console.error(error)
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
### Instance Events
|
||||||
|
|
||||||
|
The following events are available on instances of `Cookies`:
|
||||||
|
|
||||||
|
#### Event: 'changed'
|
||||||
|
|
||||||
|
* `event` Event
|
||||||
|
* `cookie` [Cookie](structures/cookie.md) - The cookie that was changed
|
||||||
|
* `cause` String - The cause of the change with one of the following values:
|
||||||
|
* `explicit` - The cookie was changed directly by a consumer's action.
|
||||||
|
* `overwrite` - The cookie was automatically removed due to an insert
|
||||||
|
operation that overwrote it.
|
||||||
|
* `expired` - The cookie was automatically removed as it expired.
|
||||||
|
* `evicted` - The cookie was automatically evicted during garbage collection.
|
||||||
|
* `expired-overwrite` - The cookie was overwritten with an already-expired
|
||||||
|
expiration date.
|
||||||
|
* `removed` Boolean - `true` if the cookie was removed, `false` otherwise.
|
||||||
|
|
||||||
|
Emitted when a cookie is changed because it was added, edited, removed, or
|
||||||
|
expired.
|
||||||
|
|
||||||
|
### Instance Methods
|
||||||
|
|
||||||
|
The following methods are available on instances of `Cookies`:
|
||||||
|
|
||||||
|
#### `cookies.get(filter, callback)`
|
||||||
|
|
||||||
|
* `filter` Object
|
||||||
|
* `url` String (optional) - Retrieves cookies which are associated with
|
||||||
|
`url`. Empty implies retrieving cookies of all urls.
|
||||||
|
* `name` String (optional) - Filters cookies by name.
|
||||||
|
* `domain` String (optional) - Retrieves cookies whose domains match or are
|
||||||
|
subdomains of `domains`
|
||||||
|
* `path` String (optional) - Retrieves cookies whose path matches `path`.
|
||||||
|
* `secure` Boolean (optional) - Filters cookies by their Secure property.
|
||||||
|
* `session` Boolean (optional) - Filters out session or persistent cookies.
|
||||||
|
* `callback` Function
|
||||||
|
* `error` Error
|
||||||
|
* `cookies` Cookies[]
|
||||||
|
|
||||||
|
Sends a request to get all cookies matching `details`, `callback` will be called
|
||||||
|
with `callback(error, cookies)` on complete.
|
||||||
|
|
||||||
|
`cookies` is an Array of [`cookie`](structures/cookie.md) objects.
|
||||||
|
|
||||||
|
#### `cookies.set(details, callback)`
|
||||||
|
|
||||||
|
* `details` Object
|
||||||
|
* `url` String - The url to associate the cookie with.
|
||||||
|
* `name` String - The name of the cookie. Empty by default if omitted.
|
||||||
|
* `value` String - The value of the cookie. Empty by default if omitted.
|
||||||
|
* `domain` String - The domain of the cookie. Empty by default if omitted.
|
||||||
|
* `path` String - The path of the cookie. Empty by default if omitted.
|
||||||
|
* `secure` Boolean - Whether the cookie should be marked as Secure. Defaults to
|
||||||
|
false.
|
||||||
|
* `httpOnly` Boolean - Whether the cookie should be marked as HTTP only.
|
||||||
|
Defaults to false.
|
||||||
|
* `expirationDate` Double - The expiration date of the cookie as the number of
|
||||||
|
seconds since the UNIX epoch. If omitted then the cookie becomes a session
|
||||||
|
cookie and will not be retained between sessions.
|
||||||
|
* `callback` Function
|
||||||
|
* `error` Error
|
||||||
|
|
||||||
|
Sets a cookie with `details`, `callback` will be called with `callback(error)`
|
||||||
|
on complete.
|
||||||
|
|
||||||
|
#### `cookies.remove(url, name, callback)`
|
||||||
|
|
||||||
|
* `url` String - The URL associated with the cookie.
|
||||||
|
* `name` String - The name of cookie to remove.
|
||||||
|
* `callback` Function
|
||||||
|
|
||||||
|
Removes the cookies matching `url` and `name`, `callback` will called with
|
||||||
|
`callback()` on complete.
|
||||||
83
docs/api/debugger.md
Normal file
83
docs/api/debugger.md
Normal file
|
|
@ -0,0 +1,83 @@
|
||||||
|
## Class: Debugger
|
||||||
|
|
||||||
|
> An alternate transport for Chrome's remote debugging protocol.
|
||||||
|
|
||||||
|
Process: [Main](../tutorial/quick-start.md#main-process)
|
||||||
|
|
||||||
|
Chrome Developer Tools has a [special binding][rdp] available at JavaScript
|
||||||
|
runtime that allows interacting with pages and instrumenting them.
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
const {BrowserWindow} = require('electron')
|
||||||
|
let win = new BrowserWindow()
|
||||||
|
|
||||||
|
try {
|
||||||
|
win.webContents.debugger.attach('1.1')
|
||||||
|
} catch (err) {
|
||||||
|
console.log('Debugger attach failed : ', err)
|
||||||
|
}
|
||||||
|
|
||||||
|
win.webContents.debugger.on('detach', (event, reason) => {
|
||||||
|
console.log('Debugger detached due to : ', reason)
|
||||||
|
})
|
||||||
|
|
||||||
|
win.webContents.debugger.on('message', (event, method, params) => {
|
||||||
|
if (method === 'Network.requestWillBeSent') {
|
||||||
|
if (params.request.url === 'https://www.github.com') {
|
||||||
|
win.webContents.debugger.detach()
|
||||||
|
}
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
win.webContents.debugger.sendCommand('Network.enable')
|
||||||
|
```
|
||||||
|
|
||||||
|
### Instance Methods
|
||||||
|
|
||||||
|
#### `debugger.attach([protocolVersion])`
|
||||||
|
|
||||||
|
* `protocolVersion` String (optional) - Requested debugging protocol version.
|
||||||
|
|
||||||
|
Attaches the debugger to the `webContents`.
|
||||||
|
|
||||||
|
#### `debugger.isAttached()`
|
||||||
|
|
||||||
|
Returns `Boolean` - Whether a debugger is attached to the `webContents`.
|
||||||
|
|
||||||
|
#### `debugger.detach()`
|
||||||
|
|
||||||
|
Detaches the debugger from the `webContents`.
|
||||||
|
|
||||||
|
#### `debugger.sendCommand(method[, commandParams, callback])`
|
||||||
|
|
||||||
|
* `method` String - Method name, should be one of the methods defined by the
|
||||||
|
remote debugging protocol.
|
||||||
|
* `commandParams` Object (optional) - JSON object with request parameters.
|
||||||
|
* `callback` Function (optional) - Response
|
||||||
|
* `error` Object - Error message indicating the failure of the command.
|
||||||
|
* `result` Any - Response defined by the 'returns' attribute of
|
||||||
|
the command description in the remote debugging protocol.
|
||||||
|
|
||||||
|
Send given command to the debugging target.
|
||||||
|
|
||||||
|
### Instance Events
|
||||||
|
|
||||||
|
#### Event: 'detach'
|
||||||
|
|
||||||
|
* `event` Event
|
||||||
|
* `reason` String - Reason for detaching debugger.
|
||||||
|
|
||||||
|
Emitted when debugging session is terminated. This happens either when
|
||||||
|
`webContents` is closed or devtools is invoked for the attached `webContents`.
|
||||||
|
|
||||||
|
#### Event: 'message'
|
||||||
|
|
||||||
|
* `event` Event
|
||||||
|
* `method` String - Method name.
|
||||||
|
* `params` Object - Event parameters defined by the 'parameters'
|
||||||
|
attribute in the remote debugging protocol.
|
||||||
|
|
||||||
|
Emitted whenever debugging target issues instrumentation event.
|
||||||
|
|
||||||
|
[rdp]: https://developer.chrome.com/devtools/docs/debugger-protocol
|
||||||
|
[`webContents.findInPage`]: web-contents.md#contentsfindinpagetext-options
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
# DownloadItem
|
## Class: DownloadItem
|
||||||
|
|
||||||
> Control file downloads from remote sources.
|
> Control file downloads from remote sources.
|
||||||
|
|
||||||
|
|
@ -37,8 +37,6 @@ win.webContents.session.on('will-download', (event, item, webContents) => {
|
||||||
})
|
})
|
||||||
```
|
```
|
||||||
|
|
||||||
## Class: DownloadItem
|
|
||||||
|
|
||||||
### Instance Events
|
### Instance Events
|
||||||
|
|
||||||
#### Event: 'updated'
|
#### Event: 'updated'
|
||||||
|
|
|
||||||
66
docs/api/incoming-message.md
Normal file
66
docs/api/incoming-message.md
Normal file
|
|
@ -0,0 +1,66 @@
|
||||||
|
## Class: IncomingMessage
|
||||||
|
|
||||||
|
> Handle responses to HTTP/HTTPS requests.
|
||||||
|
|
||||||
|
Process: [Main](../tutorial/quick-start.md#main-process)
|
||||||
|
|
||||||
|
`IncomingMessage` implements the [Readable Stream](https://nodejs.org/api/stream.html#stream_readable_streams)
|
||||||
|
interface and is therefore an [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter).
|
||||||
|
|
||||||
|
### Instance Events
|
||||||
|
|
||||||
|
#### Event: 'data'
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
|
||||||
|
* `chunk` Buffer - A chunk of response body's data.
|
||||||
|
|
||||||
|
The `data` event is the usual method of transferring response data into
|
||||||
|
applicative code.
|
||||||
|
|
||||||
|
#### Event: 'end'
|
||||||
|
|
||||||
|
Indicates that response body has ended.
|
||||||
|
|
||||||
|
#### Event: 'aborted'
|
||||||
|
|
||||||
|
Emitted when a request has been canceled during an ongoing HTTP transaction.
|
||||||
|
|
||||||
|
#### Event: 'error'
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
|
||||||
|
`error` Error - Typically holds an error string identifying failure root cause.
|
||||||
|
|
||||||
|
Emitted when an error was encountered while streaming response data events. For
|
||||||
|
instance, if the server closes the underlying while the response is still
|
||||||
|
streaming, an `error` event will be emitted on the response object and a `close`
|
||||||
|
event will subsequently follow on the request object.
|
||||||
|
|
||||||
|
### Instance Properties
|
||||||
|
|
||||||
|
An `IncomingMessage` instance has the following readable properties:
|
||||||
|
|
||||||
|
#### `response.statusCode`
|
||||||
|
|
||||||
|
An Integer indicating the HTTP response status code.
|
||||||
|
|
||||||
|
#### `response.statusMessage`
|
||||||
|
|
||||||
|
A String representing the HTTP status message.
|
||||||
|
|
||||||
|
#### `response.headers`
|
||||||
|
|
||||||
|
An Object representing the response HTTP headers. The `headers` object is
|
||||||
|
formatted as follows:
|
||||||
|
|
||||||
|
* All header names are lowercased.
|
||||||
|
* Each header name produces an array-valued property on the headers object.
|
||||||
|
* Each header value is pushed into the array associated with its header name.
|
||||||
|
|
||||||
|
#### `response.httpVersion`
|
||||||
|
|
||||||
|
A String indicating the HTTP protocol version number. Typical values are '1.0'
|
||||||
|
or '1.1'. Additionally `httpVersionMajor` and `httpVersionMinor` are two
|
||||||
|
Integer-valued readable properties that return respectively the HTTP major and
|
||||||
|
minor version numbers.
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
# MenuItem
|
## Class: MenuItem
|
||||||
|
|
||||||
> Add items to native application menus and context menus.
|
> Add items to native application menus and context menus.
|
||||||
|
|
||||||
|
|
@ -6,10 +6,6 @@ Process: [Main](../tutorial/quick-start.md#main-process)
|
||||||
|
|
||||||
See [`Menu`](menu.md) for examples.
|
See [`Menu`](menu.md) for examples.
|
||||||
|
|
||||||
## Class: MenuItem
|
|
||||||
|
|
||||||
Create a new `MenuItem` with the following method:
|
|
||||||
|
|
||||||
### `new MenuItem(options)`
|
### `new MenuItem(options)`
|
||||||
|
|
||||||
* `options` Object
|
* `options` Object
|
||||||
|
|
|
||||||
163
docs/api/menu.md
163
docs/api/menu.md
|
|
@ -1,9 +1,89 @@
|
||||||
# Menu
|
## Class: Menu
|
||||||
|
|
||||||
> Create native application menus and context menus.
|
> Create native application menus and context menus.
|
||||||
|
|
||||||
Process: [Main](../tutorial/quick-start.md#main-process)
|
Process: [Main](../tutorial/quick-start.md#main-process)
|
||||||
|
|
||||||
|
### `new Menu()`
|
||||||
|
|
||||||
|
Creates a new menu.
|
||||||
|
|
||||||
|
### Static Methods
|
||||||
|
|
||||||
|
The `menu` class has the following static methods:
|
||||||
|
|
||||||
|
#### `Menu.setApplicationMenu(menu)`
|
||||||
|
|
||||||
|
* `menu` Menu
|
||||||
|
|
||||||
|
Sets `menu` as the application menu on macOS. On Windows and Linux, the `menu`
|
||||||
|
will be set as each window's top menu.
|
||||||
|
|
||||||
|
**Note:** This API has to be called after the `ready` event of `app` module.
|
||||||
|
|
||||||
|
#### `Menu.getApplicationMenu()`
|
||||||
|
|
||||||
|
Returns `Menu` - The application menu, if set, or `null`, if not set.
|
||||||
|
|
||||||
|
#### `Menu.sendActionToFirstResponder(action)` _macOS_
|
||||||
|
|
||||||
|
* `action` String
|
||||||
|
|
||||||
|
Sends the `action` to the first responder of application. This is used for
|
||||||
|
emulating default Cocoa menu behaviors, usually you would just use the
|
||||||
|
`role` property of `MenuItem`.
|
||||||
|
|
||||||
|
See the [macOS Cocoa Event Handling Guide](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/EventOverview/EventArchitecture/EventArchitecture.html#//apple_ref/doc/uid/10000060i-CH3-SW7)
|
||||||
|
for more information on macOS' native actions.
|
||||||
|
|
||||||
|
#### `Menu.buildFromTemplate(template)`
|
||||||
|
|
||||||
|
* `template` MenuItemConstructorOptions[]
|
||||||
|
|
||||||
|
Returns `Menu`
|
||||||
|
|
||||||
|
Generally, the `template` is just an array of `options` for constructing a
|
||||||
|
[MenuItem](menu-item.md). The usage can be referenced above.
|
||||||
|
|
||||||
|
You can also attach other fields to the element of the `template` and they
|
||||||
|
will become properties of the constructed menu items.
|
||||||
|
|
||||||
|
### Instance Methods
|
||||||
|
|
||||||
|
The `menu` object has the following instance methods:
|
||||||
|
|
||||||
|
#### `menu.popup([browserWindow, x, y, positioningItem])`
|
||||||
|
|
||||||
|
* `browserWindow` BrowserWindow (optional) - Default is `BrowserWindow.getFocusedWindow()`.
|
||||||
|
* `x` Number (optional) - Default is the current mouse cursor position.
|
||||||
|
* `y` Number (**required** if `x` is used) - Default is the current mouse cursor position.
|
||||||
|
* `positioningItem` Number (optional) _macOS_ - The index of the menu item to
|
||||||
|
be positioned under the mouse cursor at the specified coordinates. Default is
|
||||||
|
-1.
|
||||||
|
|
||||||
|
Pops up this menu as a context menu in the `browserWindow`.
|
||||||
|
|
||||||
|
#### `menu.append(menuItem)`
|
||||||
|
|
||||||
|
* `menuItem` MenuItem
|
||||||
|
|
||||||
|
Appends the `menuItem` to the menu.
|
||||||
|
|
||||||
|
#### `menu.insert(pos, menuItem)`
|
||||||
|
|
||||||
|
* `pos` Integer
|
||||||
|
* `menuItem` MenuItem
|
||||||
|
|
||||||
|
Inserts the `menuItem` to the `pos` position of the menu.
|
||||||
|
|
||||||
|
### Instance Properties
|
||||||
|
|
||||||
|
`menu` objects also have the following properties:
|
||||||
|
|
||||||
|
#### `menu.items`
|
||||||
|
|
||||||
|
A MenuItem[] array containing the menu's items.
|
||||||
|
|
||||||
Each `Menu` consists of multiple [`MenuItem`](menu-item.md)s and each `MenuItem`
|
Each `Menu` consists of multiple [`MenuItem`](menu-item.md)s and each `MenuItem`
|
||||||
can have a submenu.
|
can have a submenu.
|
||||||
|
|
||||||
|
|
@ -217,87 +297,6 @@ window.addEventListener('contextmenu', (e) => {
|
||||||
</script>
|
</script>
|
||||||
```
|
```
|
||||||
|
|
||||||
## Class: Menu
|
|
||||||
|
|
||||||
### `new Menu()`
|
|
||||||
|
|
||||||
Creates a new menu.
|
|
||||||
|
|
||||||
### Static Methods
|
|
||||||
|
|
||||||
The `menu` class has the following static methods:
|
|
||||||
|
|
||||||
#### `Menu.setApplicationMenu(menu)`
|
|
||||||
|
|
||||||
* `menu` Menu
|
|
||||||
|
|
||||||
Sets `menu` as the application menu on macOS. On Windows and Linux, the `menu`
|
|
||||||
will be set as each window's top menu.
|
|
||||||
|
|
||||||
**Note:** This API has to be called after the `ready` event of `app` module.
|
|
||||||
|
|
||||||
#### `Menu.getApplicationMenu()`
|
|
||||||
|
|
||||||
Returns `Menu` - The application menu, if set, or `null`, if not set.
|
|
||||||
|
|
||||||
#### `Menu.sendActionToFirstResponder(action)` _macOS_
|
|
||||||
|
|
||||||
* `action` String
|
|
||||||
|
|
||||||
Sends the `action` to the first responder of application. This is used for
|
|
||||||
emulating default Cocoa menu behaviors, usually you would just use the
|
|
||||||
`role` property of `MenuItem`.
|
|
||||||
|
|
||||||
See the [macOS Cocoa Event Handling Guide](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/EventOverview/EventArchitecture/EventArchitecture.html#//apple_ref/doc/uid/10000060i-CH3-SW7)
|
|
||||||
for more information on macOS' native actions.
|
|
||||||
|
|
||||||
#### `Menu.buildFromTemplate(template)`
|
|
||||||
|
|
||||||
* `template` MenuItemConstructorOptions[]
|
|
||||||
|
|
||||||
Returns `Menu`
|
|
||||||
|
|
||||||
Generally, the `template` is just an array of `options` for constructing a
|
|
||||||
[MenuItem](menu-item.md). The usage can be referenced above.
|
|
||||||
|
|
||||||
You can also attach other fields to the element of the `template` and they
|
|
||||||
will become properties of the constructed menu items.
|
|
||||||
|
|
||||||
### Instance Methods
|
|
||||||
|
|
||||||
The `menu` object has the following instance methods:
|
|
||||||
|
|
||||||
#### `menu.popup([browserWindow, x, y, positioningItem])`
|
|
||||||
|
|
||||||
* `browserWindow` BrowserWindow (optional) - Default is `BrowserWindow.getFocusedWindow()`.
|
|
||||||
* `x` Number (optional) - Default is the current mouse cursor position.
|
|
||||||
* `y` Number (**required** if `x` is used) - Default is the current mouse cursor position.
|
|
||||||
* `positioningItem` Number (optional) _macOS_ - The index of the menu item to
|
|
||||||
be positioned under the mouse cursor at the specified coordinates. Default is
|
|
||||||
-1.
|
|
||||||
|
|
||||||
Pops up this menu as a context menu in the `browserWindow`.
|
|
||||||
|
|
||||||
#### `menu.append(menuItem)`
|
|
||||||
|
|
||||||
* `menuItem` MenuItem
|
|
||||||
|
|
||||||
Appends the `menuItem` to the menu.
|
|
||||||
|
|
||||||
#### `menu.insert(pos, menuItem)`
|
|
||||||
|
|
||||||
* `pos` Integer
|
|
||||||
* `menuItem` MenuItem
|
|
||||||
|
|
||||||
Inserts the `menuItem` to the `pos` position of the menu.
|
|
||||||
|
|
||||||
### Instance Properties
|
|
||||||
|
|
||||||
`menu` objects also have the following properties:
|
|
||||||
|
|
||||||
#### `menu.items`
|
|
||||||
|
|
||||||
A MenuItem[] array containing the menu's items.
|
|
||||||
|
|
||||||
## Notes on macOS Application Menu
|
## Notes on macOS Application Menu
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -18,7 +18,7 @@ let win = new BrowserWindow({icon: '/Users/somebody/images/window.png'})
|
||||||
console.log(appIcon, win)
|
console.log(appIcon, win)
|
||||||
```
|
```
|
||||||
|
|
||||||
Or read the image from the clipboard which returns a `nativeImage`:
|
Or read the image from the clipboard which returns a `NativeImage`:
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
const {clipboard, Tray} = require('electron')
|
const {clipboard, Tray} = require('electron')
|
||||||
|
|
|
||||||
269
docs/api/net.md
269
docs/api/net.md
|
|
@ -65,268 +65,7 @@ The `net` module has the following methods:
|
||||||
|
|
||||||
Returns `ClientRequest`
|
Returns `ClientRequest`
|
||||||
|
|
||||||
Creates a `ClientRequest` instance using the provided `options` which are
|
Creates a [`ClientRequest`](./client-request.md) instance using the provided
|
||||||
directly forwarded to the `ClientRequest` constructor. The `net.request` method
|
`options` which are directly forwarded to the `ClientRequest` constructor.
|
||||||
would be used to issue both secure and insecure HTTP requests according to the
|
The `net.request` method would be used to issue both secure and insecure HTTP
|
||||||
specified protocol scheme in the `options` object.
|
requests according to the specified protocol scheme in the `options` object.
|
||||||
|
|
||||||
## Class: ClientRequest
|
|
||||||
|
|
||||||
> Make HTTP/HTTPS requests.
|
|
||||||
|
|
||||||
Process: [Main](../tutorial/quick-start.md#main-process)
|
|
||||||
|
|
||||||
`ClientRequest` implements the [Writable Stream](https://nodejs.org/api/stream.html#stream_writable_streams)
|
|
||||||
interface and is therefore an [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter).
|
|
||||||
|
|
||||||
### `new ClientRequest(options)`
|
|
||||||
|
|
||||||
* `options` (Object | String) - If `options` is a String, it is interpreted as
|
|
||||||
the request URL. If it is an object, it is expected to fully specify an HTTP
|
|
||||||
request via the following properties:
|
|
||||||
* `method` String (optional) - The HTTP request method. Defaults to the GET
|
|
||||||
method.
|
|
||||||
* `url` String (optional) - The request URL. Must be provided in the absolute
|
|
||||||
form with the protocol scheme specified as http or https.
|
|
||||||
* `session` Object (optional) - The [`Session`](session.md) instance with
|
|
||||||
which the request is associated.
|
|
||||||
* `partition` String (optional) - The name of the [`partition`](session.md)
|
|
||||||
with which the request is associated. Defaults to the empty string. The
|
|
||||||
`session` option prevails on `partition`. Thus if a `session` is explicitly
|
|
||||||
specified, `partition` is ignored.
|
|
||||||
* `protocol` String (optional) - The protocol scheme in the form 'scheme:'.
|
|
||||||
Currently supported values are 'http:' or 'https:'. Defaults to 'http:'.
|
|
||||||
* `host` String (optional) - The server host provided as a concatenation of
|
|
||||||
the hostname and the port number 'hostname:port'
|
|
||||||
* `hostname` String (optional) - The server host name.
|
|
||||||
* `port` Integer (optional) - The server's listening port number.
|
|
||||||
* `path` String (optional) - The path part of the request URL.
|
|
||||||
|
|
||||||
`options` properties such as `protocol`, `host`, `hostname`, `port` and `path`
|
|
||||||
strictly follow the Node.js model as described in the
|
|
||||||
[URL](https://nodejs.org/api/url.html) module.
|
|
||||||
|
|
||||||
For instance, we could have created the same request to 'github.com' as follows:
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
const request = net.request({
|
|
||||||
method: 'GET',
|
|
||||||
protocol: 'https:',
|
|
||||||
hostname: 'github.com',
|
|
||||||
port: 443,
|
|
||||||
path: '/'
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
### Instance Events
|
|
||||||
|
|
||||||
#### Event: 'response'
|
|
||||||
|
|
||||||
Returns:
|
|
||||||
|
|
||||||
* `response` IncomingMessage - An object representing the HTTP response message.
|
|
||||||
|
|
||||||
#### Event: 'login'
|
|
||||||
|
|
||||||
Returns:
|
|
||||||
|
|
||||||
* `authInfo` Object
|
|
||||||
* `isProxy` Boolean
|
|
||||||
* `scheme` String
|
|
||||||
* `host` String
|
|
||||||
* `port` Integer
|
|
||||||
* `realm` String
|
|
||||||
* `callback` Function
|
|
||||||
|
|
||||||
Emitted when an authenticating proxy is asking for user credentials.
|
|
||||||
|
|
||||||
The `callback` function is expected to be called back with user credentials:
|
|
||||||
|
|
||||||
* `username` String
|
|
||||||
* `password` String
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
request.on('login', (authInfo, callback) => {
|
|
||||||
callback('username', 'password')
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
Providing empty credentials will cancel the request and report an authentication
|
|
||||||
error on the response object:
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
request.on('response', (response) => {
|
|
||||||
console.log(`STATUS: ${response.statusCode}`)
|
|
||||||
response.on('error', (error) => {
|
|
||||||
console.log(`ERROR: ${JSON.stringify(error)}`)
|
|
||||||
})
|
|
||||||
})
|
|
||||||
request.on('login', (authInfo, callback) => {
|
|
||||||
callback()
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Event: 'finish'
|
|
||||||
|
|
||||||
Emitted just after the last chunk of the `request`'s data has been written into
|
|
||||||
the `request` object.
|
|
||||||
|
|
||||||
#### Event: 'abort'
|
|
||||||
|
|
||||||
Emitted when the `request` is aborted. The `abort` event will not be fired if
|
|
||||||
the `request` is already closed.
|
|
||||||
|
|
||||||
#### Event: 'error'
|
|
||||||
|
|
||||||
Returns:
|
|
||||||
|
|
||||||
* `error` Error - an error object providing some information about the failure.
|
|
||||||
|
|
||||||
Emitted when the `net` module fails to issue a network request. Typically when
|
|
||||||
the `request` object emits an `error` event, a `close` event will subsequently
|
|
||||||
follow and no response object will be provided.
|
|
||||||
|
|
||||||
#### Event: 'close'
|
|
||||||
|
|
||||||
Emitted as the last event in the HTTP request-response transaction. The `close`
|
|
||||||
event indicates that no more events will be emitted on either the `request` or
|
|
||||||
`response` objects.
|
|
||||||
|
|
||||||
### Instance Properties
|
|
||||||
|
|
||||||
#### `request.chunkedEncoding`
|
|
||||||
|
|
||||||
A Boolean specifying whether the request will use HTTP chunked transfer encoding
|
|
||||||
or not. Defaults to false. The property is readable and writable, however it can
|
|
||||||
be set only before the first write operation as the HTTP headers are not yet put
|
|
||||||
on the wire. Trying to set the `chunkedEncoding` property after the first write
|
|
||||||
will throw an error.
|
|
||||||
|
|
||||||
Using chunked encoding is strongly recommended if you need to send a large
|
|
||||||
request body as data will be streamed in small chunks instead of being
|
|
||||||
internally buffered inside Electron process memory.
|
|
||||||
|
|
||||||
### Instance Methods
|
|
||||||
|
|
||||||
#### `request.setHeader(name, value)`
|
|
||||||
|
|
||||||
* `name` String - An extra HTTP header name.
|
|
||||||
* `value` String - An extra HTTP header value.
|
|
||||||
|
|
||||||
Adds an extra HTTP header. The header name will issued as it is without
|
|
||||||
lowercasing. It can be called only before first write. Calling this method after
|
|
||||||
the first write will throw an error.
|
|
||||||
|
|
||||||
#### `request.getHeader(name)`
|
|
||||||
|
|
||||||
* `name` String - Specify an extra header name.
|
|
||||||
|
|
||||||
Returns String - The value of a previously set extra header name.
|
|
||||||
|
|
||||||
#### `request.removeHeader(name)`
|
|
||||||
|
|
||||||
* `name` String - Specify an extra header name.
|
|
||||||
|
|
||||||
Removes a previously set extra header name. This method can be called only
|
|
||||||
before first write. Trying to call it after the first write will throw an error.
|
|
||||||
|
|
||||||
#### `request.write(chunk[, encoding][, callback])`
|
|
||||||
|
|
||||||
* `chunk` (String | Buffer) - A chunk of the request body's data. If it is a
|
|
||||||
string, it is converted into a Buffer using the specified encoding.
|
|
||||||
* `encoding` String (optional) - Used to convert string chunks into Buffer
|
|
||||||
objects. Defaults to 'utf-8'.
|
|
||||||
* `callback` Function (optional) - Called after the write operation ends.
|
|
||||||
|
|
||||||
`callback` is essentially a dummy function introduced in the purpose of keeping
|
|
||||||
similarity with the Node.js API. It is called asynchronously in the next tick
|
|
||||||
after `chunk` content have been delivered to the Chromium networking layer.
|
|
||||||
Contrary to the Node.js implementation, it is not guaranteed that `chunk`
|
|
||||||
content have been flushed on the wire before `callback` is called.
|
|
||||||
|
|
||||||
Adds a chunk of data to the request body. The first write operation may cause
|
|
||||||
the request headers to be issued on the wire. After the first write operation,
|
|
||||||
it is not allowed to add or remove a custom header.
|
|
||||||
|
|
||||||
#### `request.end([chunk][, encoding][, callback])`
|
|
||||||
|
|
||||||
* `chunk` (String | Buffer) (optional)
|
|
||||||
* `encoding` String (optional)
|
|
||||||
* `callback` Function (optional)
|
|
||||||
|
|
||||||
Sends the last chunk of the request data. Subsequent write or end operations
|
|
||||||
will not be allowed. The `finish` event is emitted just after the end operation.
|
|
||||||
|
|
||||||
#### `request.abort()`
|
|
||||||
|
|
||||||
Cancels an ongoing HTTP transaction. If the request has already emitted the
|
|
||||||
`close` event, the abort operation will have no effect. Otherwise an ongoing
|
|
||||||
event will emit `abort` and `close` events. Additionally, if there is an ongoing
|
|
||||||
response object,it will emit the `aborted` event.
|
|
||||||
|
|
||||||
## Class: IncomingMessage
|
|
||||||
|
|
||||||
> Handle responses to HTTP/HTTPS requests.
|
|
||||||
|
|
||||||
Process: [Main](../tutorial/quick-start.md#main-process)
|
|
||||||
|
|
||||||
`IncomingMessage` implements the [Readable Stream](https://nodejs.org/api/stream.html#stream_readable_streams)
|
|
||||||
interface and is therefore an [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter).
|
|
||||||
|
|
||||||
### Instance Events
|
|
||||||
|
|
||||||
#### Event: 'data'
|
|
||||||
|
|
||||||
Returns:
|
|
||||||
|
|
||||||
* `chunk` Buffer - A chunk of response body's data.
|
|
||||||
|
|
||||||
The `data` event is the usual method of transferring response data into
|
|
||||||
applicative code.
|
|
||||||
|
|
||||||
#### Event: 'end'
|
|
||||||
|
|
||||||
Indicates that response body has ended.
|
|
||||||
|
|
||||||
#### Event: 'aborted'
|
|
||||||
|
|
||||||
Emitted when a request has been canceled during an ongoing HTTP transaction.
|
|
||||||
|
|
||||||
#### Event: 'error'
|
|
||||||
|
|
||||||
Returns:
|
|
||||||
|
|
||||||
`error` Error - Typically holds an error string identifying failure root cause.
|
|
||||||
|
|
||||||
Emitted when an error was encountered while streaming response data events. For
|
|
||||||
instance, if the server closes the underlying while the response is still
|
|
||||||
streaming, an `error` event will be emitted on the response object and a `close`
|
|
||||||
event will subsequently follow on the request object.
|
|
||||||
|
|
||||||
### Instance Properties
|
|
||||||
|
|
||||||
An `IncomingMessage` instance has the following readable properties:
|
|
||||||
|
|
||||||
#### `response.statusCode`
|
|
||||||
|
|
||||||
An Integer indicating the HTTP response status code.
|
|
||||||
|
|
||||||
#### `response.statusMessage`
|
|
||||||
|
|
||||||
A String representing the HTTP status message.
|
|
||||||
|
|
||||||
#### `response.headers`
|
|
||||||
|
|
||||||
An Object representing the response HTTP headers. The `headers` object is
|
|
||||||
formatted as follows:
|
|
||||||
|
|
||||||
* All header names are lowercased.
|
|
||||||
* Each header name produces an array-valued property on the headers object.
|
|
||||||
* Each header value is pushed into the array associated with its header name.
|
|
||||||
|
|
||||||
#### `response.httpVersion`
|
|
||||||
|
|
||||||
A String indicating the HTTP protocol version number. Typical values are '1.0'
|
|
||||||
or '1.1'. Additionally `httpVersionMajor` and `httpVersionMinor` are two
|
|
||||||
Integer-valued readable properties that return respectively the HTTP major and
|
|
||||||
minor version numbers.
|
|
||||||
|
|
|
||||||
|
|
@ -374,316 +374,3 @@ app.on('ready', function () {
|
||||||
})
|
})
|
||||||
})
|
})
|
||||||
```
|
```
|
||||||
|
|
||||||
## Class: Cookies
|
|
||||||
|
|
||||||
> Query and modify a session's cookies.
|
|
||||||
|
|
||||||
Process: [Main](../tutorial/quick-start.md#main-process)
|
|
||||||
|
|
||||||
Instances of the `Cookies` class are accessed by using `cookies` property of
|
|
||||||
a `Session`.
|
|
||||||
|
|
||||||
For example:
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
const {session} = require('electron')
|
|
||||||
|
|
||||||
// Query all cookies.
|
|
||||||
session.defaultSession.cookies.get({}, (error, cookies) => {
|
|
||||||
console.log(error, cookies)
|
|
||||||
})
|
|
||||||
|
|
||||||
// Query all cookies associated with a specific url.
|
|
||||||
session.defaultSession.cookies.get({url: 'http://www.github.com'}, (error, cookies) => {
|
|
||||||
console.log(error, cookies)
|
|
||||||
})
|
|
||||||
|
|
||||||
// Set a cookie with the given cookie data;
|
|
||||||
// may overwrite equivalent cookies if they exist.
|
|
||||||
const cookie = {url: 'http://www.github.com', name: 'dummy_name', value: 'dummy'}
|
|
||||||
session.defaultSession.cookies.set(cookie, (error) => {
|
|
||||||
if (error) console.error(error)
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
### Instance Events
|
|
||||||
|
|
||||||
The following events are available on instances of `Cookies`:
|
|
||||||
|
|
||||||
#### Event: 'changed'
|
|
||||||
|
|
||||||
* `event` Event
|
|
||||||
* `cookie` [Cookie](structures/cookie.md) - The cookie that was changed
|
|
||||||
* `cause` String - The cause of the change with one of the following values:
|
|
||||||
* `explicit` - The cookie was changed directly by a consumer's action.
|
|
||||||
* `overwrite` - The cookie was automatically removed due to an insert
|
|
||||||
operation that overwrote it.
|
|
||||||
* `expired` - The cookie was automatically removed as it expired.
|
|
||||||
* `evicted` - The cookie was automatically evicted during garbage collection.
|
|
||||||
* `expired-overwrite` - The cookie was overwritten with an already-expired
|
|
||||||
expiration date.
|
|
||||||
* `removed` Boolean - `true` if the cookie was removed, `false` otherwise.
|
|
||||||
|
|
||||||
Emitted when a cookie is changed because it was added, edited, removed, or
|
|
||||||
expired.
|
|
||||||
|
|
||||||
### Instance Methods
|
|
||||||
|
|
||||||
The following methods are available on instances of `Cookies`:
|
|
||||||
|
|
||||||
#### `cookies.get(filter, callback)`
|
|
||||||
|
|
||||||
* `filter` Object
|
|
||||||
* `url` String (optional) - Retrieves cookies which are associated with
|
|
||||||
`url`. Empty implies retrieving cookies of all urls.
|
|
||||||
* `name` String (optional) - Filters cookies by name.
|
|
||||||
* `domain` String (optional) - Retrieves cookies whose domains match or are
|
|
||||||
subdomains of `domains`
|
|
||||||
* `path` String (optional) - Retrieves cookies whose path matches `path`.
|
|
||||||
* `secure` Boolean (optional) - Filters cookies by their Secure property.
|
|
||||||
* `session` Boolean (optional) - Filters out session or persistent cookies.
|
|
||||||
* `callback` Function
|
|
||||||
* `error` Error
|
|
||||||
* `cookies` Cookies[]
|
|
||||||
|
|
||||||
Sends a request to get all cookies matching `details`, `callback` will be called
|
|
||||||
with `callback(error, cookies)` on complete.
|
|
||||||
|
|
||||||
`cookies` is an Array of [`cookie`](structures/cookie.md) objects.
|
|
||||||
|
|
||||||
#### `cookies.set(details, callback)`
|
|
||||||
|
|
||||||
* `details` Object
|
|
||||||
* `url` String - The url to associate the cookie with.
|
|
||||||
* `name` String - The name of the cookie. Empty by default if omitted.
|
|
||||||
* `value` String - The value of the cookie. Empty by default if omitted.
|
|
||||||
* `domain` String - The domain of the cookie. Empty by default if omitted.
|
|
||||||
* `path` String - The path of the cookie. Empty by default if omitted.
|
|
||||||
* `secure` Boolean - Whether the cookie should be marked as Secure. Defaults to
|
|
||||||
false.
|
|
||||||
* `httpOnly` Boolean - Whether the cookie should be marked as HTTP only.
|
|
||||||
Defaults to false.
|
|
||||||
* `expirationDate` Double - The expiration date of the cookie as the number of
|
|
||||||
seconds since the UNIX epoch. If omitted then the cookie becomes a session
|
|
||||||
cookie and will not be retained between sessions.
|
|
||||||
* `callback` Function
|
|
||||||
* `error` Error
|
|
||||||
|
|
||||||
Sets a cookie with `details`, `callback` will be called with `callback(error)`
|
|
||||||
on complete.
|
|
||||||
|
|
||||||
#### `cookies.remove(url, name, callback)`
|
|
||||||
|
|
||||||
* `url` String - The URL associated with the cookie.
|
|
||||||
* `name` String - The name of cookie to remove.
|
|
||||||
* `callback` Function
|
|
||||||
|
|
||||||
Removes the cookies matching `url` and `name`, `callback` will called with
|
|
||||||
`callback()` on complete.
|
|
||||||
|
|
||||||
## Class: WebRequest
|
|
||||||
|
|
||||||
> Intercept and modify the contents of a request at various stages of its lifetime.
|
|
||||||
|
|
||||||
Process: [Main](../tutorial/quick-start.md#main-process)
|
|
||||||
|
|
||||||
Instances of the `WebRequest` class are accessed by using the `webRequest`
|
|
||||||
property of a `Session`.
|
|
||||||
|
|
||||||
The methods of `WebRequest` accept an optional `filter` and a `listener`. The
|
|
||||||
`listener` will be called with `listener(details)` when the API's event has
|
|
||||||
happened. The `details` object describes the request. Passing `null`
|
|
||||||
as `listener` will unsubscribe from the event.
|
|
||||||
|
|
||||||
The `filter` object has a `urls` property which is an Array of URL
|
|
||||||
patterns that will be used to filter out the requests that do not match the URL
|
|
||||||
patterns. If the `filter` is omitted then all requests will be matched.
|
|
||||||
|
|
||||||
For certain events the `listener` is passed with a `callback`, which should be
|
|
||||||
called with a `response` object when `listener` has done its work.
|
|
||||||
|
|
||||||
An example of adding `User-Agent` header for requests:
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
const {session} = require('electron')
|
|
||||||
|
|
||||||
// Modify the user agent for all requests to the following urls.
|
|
||||||
const filter = {
|
|
||||||
urls: ['https://*.github.com/*', '*://electron.github.io']
|
|
||||||
}
|
|
||||||
|
|
||||||
session.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {
|
|
||||||
details.requestHeaders['User-Agent'] = 'MyAgent'
|
|
||||||
callback({cancel: false, requestHeaders: details.requestHeaders})
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
### Instance Methods
|
|
||||||
|
|
||||||
The following methods are available on instances of `WebRequest`:
|
|
||||||
|
|
||||||
#### `webRequest.onBeforeRequest([filter, ]listener)`
|
|
||||||
|
|
||||||
* `filter` Object
|
|
||||||
* `listener` Function
|
|
||||||
* `details` Object
|
|
||||||
* `id` Integer
|
|
||||||
* `url` String
|
|
||||||
* `method` String
|
|
||||||
* `resourceType` String
|
|
||||||
* `timestamp` Double
|
|
||||||
* `uploadData` [UploadData[]](structures/upload-data.md)
|
|
||||||
* `callback` Function
|
|
||||||
* `response` Object
|
|
||||||
* `cancel` Boolean (optional)
|
|
||||||
* `redirectURL` String (optional) - The original request is prevented from
|
|
||||||
being sent or completed and is instead redirected to the given URL.
|
|
||||||
|
|
||||||
The `listener` will be called with `listener(details, callback)` when a request
|
|
||||||
is about to occur.
|
|
||||||
|
|
||||||
The `uploadData` is an array of `UploadData` objects.
|
|
||||||
|
|
||||||
The `callback` has to be called with an `response` object.
|
|
||||||
|
|
||||||
#### `webRequest.onBeforeSendHeaders([filter, ]listener)`
|
|
||||||
|
|
||||||
* `filter` Object
|
|
||||||
* `listener` Function
|
|
||||||
|
|
||||||
The `listener` will be called with `listener(details, callback)` before sending
|
|
||||||
an HTTP request, once the request headers are available. This may occur after a
|
|
||||||
TCP connection is made to the server, but before any http data is sent.
|
|
||||||
|
|
||||||
* `details` Object
|
|
||||||
* `id` Integer
|
|
||||||
* `url` String
|
|
||||||
* `method` String
|
|
||||||
* `resourceType` String
|
|
||||||
* `timestamp` Double
|
|
||||||
* `requestHeaders` Object
|
|
||||||
* `callback` Function
|
|
||||||
* `response` Object
|
|
||||||
* `cancel` Boolean (optional)
|
|
||||||
* `requestHeaders` Object (optional) - When provided, request will be made
|
|
||||||
with these headers.
|
|
||||||
|
|
||||||
The `callback` has to be called with an `response` object.
|
|
||||||
|
|
||||||
#### `webRequest.onSendHeaders([filter, ]listener)`
|
|
||||||
|
|
||||||
* `filter` Object
|
|
||||||
* `listener` Function
|
|
||||||
* `details` Object
|
|
||||||
* `id` Integer
|
|
||||||
* `url` String
|
|
||||||
* `method` String
|
|
||||||
* `resourceType` String
|
|
||||||
* `timestamp` Double
|
|
||||||
* `requestHeaders` Object
|
|
||||||
|
|
||||||
The `listener` will be called with `listener(details)` just before a request is
|
|
||||||
going to be sent to the server, modifications of previous `onBeforeSendHeaders`
|
|
||||||
response are visible by the time this listener is fired.
|
|
||||||
|
|
||||||
#### `webRequest.onHeadersReceived([filter, ]listener)`
|
|
||||||
|
|
||||||
* `filter` Object
|
|
||||||
* `listener` Function
|
|
||||||
|
|
||||||
The `listener` will be called with `listener(details, callback)` when HTTP
|
|
||||||
response headers of a request have been received.
|
|
||||||
|
|
||||||
* `details` Object
|
|
||||||
* `id` String
|
|
||||||
* `url` String
|
|
||||||
* `method` String
|
|
||||||
* `resourceType` String
|
|
||||||
* `timestamp` Double
|
|
||||||
* `statusLine` String
|
|
||||||
* `statusCode` Integer
|
|
||||||
* `responseHeaders` Object
|
|
||||||
* `callback` Function
|
|
||||||
* `response` Object
|
|
||||||
* `cancel` Boolean
|
|
||||||
* `responseHeaders` Object (optional) - When provided, the server is assumed
|
|
||||||
to have responded with these headers.
|
|
||||||
* `statusLine` String (optional) - Should be provided when overriding
|
|
||||||
`responseHeaders` to change header status otherwise original response
|
|
||||||
header's status will be used.
|
|
||||||
|
|
||||||
The `callback` has to be called with an `response` object.
|
|
||||||
|
|
||||||
#### `webRequest.onResponseStarted([filter, ]listener)`
|
|
||||||
|
|
||||||
* `filter` Object
|
|
||||||
* `listener` Function
|
|
||||||
* `details` Object
|
|
||||||
* `id` Integer
|
|
||||||
* `url` String
|
|
||||||
* `method` String
|
|
||||||
* `resourceType` String
|
|
||||||
* `timestamp` Double
|
|
||||||
* `responseHeaders` Object
|
|
||||||
* `fromCache` Boolean - Indicates whether the response was fetched from disk
|
|
||||||
cache.
|
|
||||||
* `statusCode` Integer
|
|
||||||
* `statusLine` String
|
|
||||||
|
|
||||||
The `listener` will be called with `listener(details)` when first byte of the
|
|
||||||
response body is received. For HTTP requests, this means that the status line
|
|
||||||
and response headers are available.
|
|
||||||
|
|
||||||
#### `webRequest.onBeforeRedirect([filter, ]listener)`
|
|
||||||
|
|
||||||
* `filter` Object
|
|
||||||
* `listener` Function
|
|
||||||
* `details` Object
|
|
||||||
* `id` String
|
|
||||||
* `url` String
|
|
||||||
* `method` String
|
|
||||||
* `resourceType` String
|
|
||||||
* `timestamp` Double
|
|
||||||
* `redirectURL` String
|
|
||||||
* `statusCode` Integer
|
|
||||||
* `ip` String (optional) - The server IP address that the request was
|
|
||||||
actually sent to.
|
|
||||||
* `fromCache` Boolean
|
|
||||||
* `responseHeaders` Object
|
|
||||||
|
|
||||||
The `listener` will be called with `listener(details)` when a server initiated
|
|
||||||
redirect is about to occur.
|
|
||||||
|
|
||||||
#### `webRequest.onCompleted([filter, ]listener)`
|
|
||||||
|
|
||||||
* `filter` Object
|
|
||||||
* `listener` Function
|
|
||||||
* `details` Object
|
|
||||||
* `id` Integer
|
|
||||||
* `url` String
|
|
||||||
* `method` String
|
|
||||||
* `resourceType` String
|
|
||||||
* `timestamp` Double
|
|
||||||
* `responseHeaders` Object
|
|
||||||
* `fromCache` Boolean
|
|
||||||
* `statusCode` Integer
|
|
||||||
* `statusLine` String
|
|
||||||
|
|
||||||
The `listener` will be called with `listener(details)` when a request is
|
|
||||||
completed.
|
|
||||||
|
|
||||||
#### `webRequest.onErrorOccurred([filter, ]listener)`
|
|
||||||
|
|
||||||
* `filter` Object
|
|
||||||
* `listener` Function
|
|
||||||
* `details` Object
|
|
||||||
* `id` Integer
|
|
||||||
* `url` String
|
|
||||||
* `method` String
|
|
||||||
* `resourceType` String
|
|
||||||
* `timestamp` Double
|
|
||||||
* `fromCache` Boolean
|
|
||||||
* `error` String - The error description.
|
|
||||||
|
|
||||||
The `listener` will be called with `listener(details)` when an error occurs.
|
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
# Upload Blob Object
|
# UploadBlob Object
|
||||||
|
|
||||||
* `type` String - `blob`.
|
* `type` String - `blob`.
|
||||||
* `blobUUID` String - UUID of blob data to upload.
|
* `blobUUID` String - UUID of blob data to upload.
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
# Upload FileSystem Object
|
# UploadFileSystem Object
|
||||||
|
|
||||||
* `type` String - `fileSystem`.
|
* `type` String - `fileSystem`.
|
||||||
* `filsSystemURL` String - FileSystem url to read data for upload.
|
* `filsSystemURL` String - FileSystem url to read data for upload.
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
# Upload File Object
|
# UploadFile Object
|
||||||
|
|
||||||
* `type` String - `file`.
|
* `type` String - `file`.
|
||||||
* `filePath` String - Path of file to be uploaded.
|
* `filePath` String - Path of file to be uploaded.
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
# Upload RawData Object
|
# UploadRawData Object
|
||||||
|
|
||||||
* `type` String - `rawData`.
|
* `type` String - `rawData`.
|
||||||
* `bytes` Buffer - Data to be uploaded.
|
* `bytes` Buffer - Data to be uploaded.
|
||||||
|
|
|
||||||
|
|
@ -1,9 +1,11 @@
|
||||||
# Tray
|
## Class: Tray
|
||||||
|
|
||||||
> Add icons and context menus to the system's notification area.
|
> Add icons and context menus to the system's notification area.
|
||||||
|
|
||||||
Process: [Main](../tutorial/quick-start.md#main-process)
|
Process: [Main](../tutorial/quick-start.md#main-process)
|
||||||
|
|
||||||
|
`Tray` is an [EventEmitter][event-emitter].
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
const {app, Menu, Tray} = require('electron')
|
const {app, Menu, Tray} = require('electron')
|
||||||
|
|
||||||
|
|
@ -55,9 +57,6 @@ app.on('ready', () => {
|
||||||
If you want to keep exact same behaviors on all platforms, you should not
|
If you want to keep exact same behaviors on all platforms, you should not
|
||||||
rely on the `click` event and always attach a context menu to the tray icon.
|
rely on the `click` event and always attach a context menu to the tray icon.
|
||||||
|
|
||||||
## Class: Tray
|
|
||||||
|
|
||||||
`Tray` is an [EventEmitter][event-emitter].
|
|
||||||
|
|
||||||
### `new Tray(image)`
|
### `new Tray(image)`
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1186,7 +1186,7 @@ A Session object ([session](session.md)) used by this webContents.
|
||||||
|
|
||||||
#### `contents.hostWebContents`
|
#### `contents.hostWebContents`
|
||||||
|
|
||||||
A `WebContents` that might own this `WebContents`.
|
A [`WebContents`](web-contents.md) instance that might own this `WebContents`.
|
||||||
|
|
||||||
#### `contents.devToolsWebContents`
|
#### `contents.devToolsWebContents`
|
||||||
|
|
||||||
|
|
@ -1197,88 +1197,4 @@ when the DevTools has been closed.
|
||||||
|
|
||||||
#### `contents.debugger`
|
#### `contents.debugger`
|
||||||
|
|
||||||
A Debugger instance for this webContents.
|
A [Debugger](debugger.md) instance for this webContents.
|
||||||
|
|
||||||
## Class: Debugger
|
|
||||||
|
|
||||||
> An alternate transport for Chrome's remote debugging protocol.
|
|
||||||
|
|
||||||
Process: [Main](../tutorial/quick-start.md#main-process)
|
|
||||||
|
|
||||||
Chrome Developer Tools has a [special binding][rdp] available at JavaScript
|
|
||||||
runtime that allows interacting with pages and instrumenting them.
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
const {BrowserWindow} = require('electron')
|
|
||||||
let win = new BrowserWindow()
|
|
||||||
|
|
||||||
try {
|
|
||||||
win.webContents.debugger.attach('1.1')
|
|
||||||
} catch (err) {
|
|
||||||
console.log('Debugger attach failed : ', err)
|
|
||||||
}
|
|
||||||
|
|
||||||
win.webContents.debugger.on('detach', (event, reason) => {
|
|
||||||
console.log('Debugger detached due to : ', reason)
|
|
||||||
})
|
|
||||||
|
|
||||||
win.webContents.debugger.on('message', (event, method, params) => {
|
|
||||||
if (method === 'Network.requestWillBeSent') {
|
|
||||||
if (params.request.url === 'https://www.github.com') {
|
|
||||||
win.webContents.debugger.detach()
|
|
||||||
}
|
|
||||||
}
|
|
||||||
})
|
|
||||||
|
|
||||||
win.webContents.debugger.sendCommand('Network.enable')
|
|
||||||
```
|
|
||||||
|
|
||||||
### Instance Methods
|
|
||||||
|
|
||||||
#### `debugger.attach([protocolVersion])`
|
|
||||||
|
|
||||||
* `protocolVersion` String (optional) - Requested debugging protocol version.
|
|
||||||
|
|
||||||
Attaches the debugger to the `webContents`.
|
|
||||||
|
|
||||||
#### `debugger.isAttached()`
|
|
||||||
|
|
||||||
Returns `Boolean` - Whether a debugger is attached to the `webContents`.
|
|
||||||
|
|
||||||
#### `debugger.detach()`
|
|
||||||
|
|
||||||
Detaches the debugger from the `webContents`.
|
|
||||||
|
|
||||||
#### `debugger.sendCommand(method[, commandParams, callback])`
|
|
||||||
|
|
||||||
* `method` String - Method name, should be one of the methods defined by the
|
|
||||||
remote debugging protocol.
|
|
||||||
* `commandParams` Object (optional) - JSON object with request parameters.
|
|
||||||
* `callback` Function (optional) - Response
|
|
||||||
* `error` Object - Error message indicating the failure of the command.
|
|
||||||
* `result` Any - Response defined by the 'returns' attribute of
|
|
||||||
the command description in the remote debugging protocol.
|
|
||||||
|
|
||||||
Send given command to the debugging target.
|
|
||||||
|
|
||||||
### Instance Events
|
|
||||||
|
|
||||||
#### Event: 'detach'
|
|
||||||
|
|
||||||
* `event` Event
|
|
||||||
* `reason` String - Reason for detaching debugger.
|
|
||||||
|
|
||||||
Emitted when debugging session is terminated. This happens either when
|
|
||||||
`webContents` is closed or devtools is invoked for the attached `webContents`.
|
|
||||||
|
|
||||||
#### Event: 'message'
|
|
||||||
|
|
||||||
* `event` Event
|
|
||||||
* `method` String - Method name.
|
|
||||||
* `params` Object - Event parameters defined by the 'parameters'
|
|
||||||
attribute in the remote debugging protocol.
|
|
||||||
|
|
||||||
Emitted whenever debugging target issues instrumentation event.
|
|
||||||
|
|
||||||
[rdp]: https://developer.chrome.com/devtools/docs/debugger-protocol
|
|
||||||
[`webContents.findInPage`]: web-contents.md#contentsfindinpagetext-options
|
|
||||||
|
|
|
||||||
205
docs/api/web-request.md
Normal file
205
docs/api/web-request.md
Normal file
|
|
@ -0,0 +1,205 @@
|
||||||
|
## Class: WebRequest
|
||||||
|
|
||||||
|
> Intercept and modify the contents of a request at various stages of its lifetime.
|
||||||
|
|
||||||
|
Process: [Main](../tutorial/quick-start.md#main-process)
|
||||||
|
|
||||||
|
Instances of the `WebRequest` class are accessed by using the `webRequest`
|
||||||
|
property of a `Session`.
|
||||||
|
|
||||||
|
The methods of `WebRequest` accept an optional `filter` and a `listener`. The
|
||||||
|
`listener` will be called with `listener(details)` when the API's event has
|
||||||
|
happened. The `details` object describes the request. Passing `null`
|
||||||
|
as `listener` will unsubscribe from the event.
|
||||||
|
|
||||||
|
The `filter` object has a `urls` property which is an Array of URL
|
||||||
|
patterns that will be used to filter out the requests that do not match the URL
|
||||||
|
patterns. If the `filter` is omitted then all requests will be matched.
|
||||||
|
|
||||||
|
For certain events the `listener` is passed with a `callback`, which should be
|
||||||
|
called with a `response` object when `listener` has done its work.
|
||||||
|
|
||||||
|
An example of adding `User-Agent` header for requests:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
const {session} = require('electron')
|
||||||
|
|
||||||
|
// Modify the user agent for all requests to the following urls.
|
||||||
|
const filter = {
|
||||||
|
urls: ['https://*.github.com/*', '*://electron.github.io']
|
||||||
|
}
|
||||||
|
|
||||||
|
session.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {
|
||||||
|
details.requestHeaders['User-Agent'] = 'MyAgent'
|
||||||
|
callback({cancel: false, requestHeaders: details.requestHeaders})
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
### Instance Methods
|
||||||
|
|
||||||
|
The following methods are available on instances of `WebRequest`:
|
||||||
|
|
||||||
|
#### `webRequest.onBeforeRequest([filter, ]listener)`
|
||||||
|
|
||||||
|
* `filter` Object
|
||||||
|
* `listener` Function
|
||||||
|
* `details` Object
|
||||||
|
* `id` Integer
|
||||||
|
* `url` String
|
||||||
|
* `method` String
|
||||||
|
* `resourceType` String
|
||||||
|
* `timestamp` Double
|
||||||
|
* `uploadData` [UploadData[]](structures/upload-data.md)
|
||||||
|
* `callback` Function
|
||||||
|
* `response` Object
|
||||||
|
* `cancel` Boolean (optional)
|
||||||
|
* `redirectURL` String (optional) - The original request is prevented from
|
||||||
|
being sent or completed and is instead redirected to the given URL.
|
||||||
|
|
||||||
|
The `listener` will be called with `listener(details, callback)` when a request
|
||||||
|
is about to occur.
|
||||||
|
|
||||||
|
The `uploadData` is an array of `UploadData` objects.
|
||||||
|
|
||||||
|
The `callback` has to be called with an `response` object.
|
||||||
|
|
||||||
|
#### `webRequest.onBeforeSendHeaders([filter, ]listener)`
|
||||||
|
|
||||||
|
* `filter` Object
|
||||||
|
* `listener` Function
|
||||||
|
|
||||||
|
The `listener` will be called with `listener(details, callback)` before sending
|
||||||
|
an HTTP request, once the request headers are available. This may occur after a
|
||||||
|
TCP connection is made to the server, but before any http data is sent.
|
||||||
|
|
||||||
|
* `details` Object
|
||||||
|
* `id` Integer
|
||||||
|
* `url` String
|
||||||
|
* `method` String
|
||||||
|
* `resourceType` String
|
||||||
|
* `timestamp` Double
|
||||||
|
* `requestHeaders` Object
|
||||||
|
* `callback` Function
|
||||||
|
* `response` Object
|
||||||
|
* `cancel` Boolean (optional)
|
||||||
|
* `requestHeaders` Object (optional) - When provided, request will be made
|
||||||
|
with these headers.
|
||||||
|
|
||||||
|
The `callback` has to be called with an `response` object.
|
||||||
|
|
||||||
|
#### `webRequest.onSendHeaders([filter, ]listener)`
|
||||||
|
|
||||||
|
* `filter` Object
|
||||||
|
* `listener` Function
|
||||||
|
* `details` Object
|
||||||
|
* `id` Integer
|
||||||
|
* `url` String
|
||||||
|
* `method` String
|
||||||
|
* `resourceType` String
|
||||||
|
* `timestamp` Double
|
||||||
|
* `requestHeaders` Object
|
||||||
|
|
||||||
|
The `listener` will be called with `listener(details)` just before a request is
|
||||||
|
going to be sent to the server, modifications of previous `onBeforeSendHeaders`
|
||||||
|
response are visible by the time this listener is fired.
|
||||||
|
|
||||||
|
#### `webRequest.onHeadersReceived([filter, ]listener)`
|
||||||
|
|
||||||
|
* `filter` Object
|
||||||
|
* `listener` Function
|
||||||
|
|
||||||
|
The `listener` will be called with `listener(details, callback)` when HTTP
|
||||||
|
response headers of a request have been received.
|
||||||
|
|
||||||
|
* `details` Object
|
||||||
|
* `id` String
|
||||||
|
* `url` String
|
||||||
|
* `method` String
|
||||||
|
* `resourceType` String
|
||||||
|
* `timestamp` Double
|
||||||
|
* `statusLine` String
|
||||||
|
* `statusCode` Integer
|
||||||
|
* `responseHeaders` Object
|
||||||
|
* `callback` Function
|
||||||
|
* `response` Object
|
||||||
|
* `cancel` Boolean
|
||||||
|
* `responseHeaders` Object (optional) - When provided, the server is assumed
|
||||||
|
to have responded with these headers.
|
||||||
|
* `statusLine` String (optional) - Should be provided when overriding
|
||||||
|
`responseHeaders` to change header status otherwise original response
|
||||||
|
header's status will be used.
|
||||||
|
|
||||||
|
The `callback` has to be called with an `response` object.
|
||||||
|
|
||||||
|
#### `webRequest.onResponseStarted([filter, ]listener)`
|
||||||
|
|
||||||
|
* `filter` Object
|
||||||
|
* `listener` Function
|
||||||
|
* `details` Object
|
||||||
|
* `id` Integer
|
||||||
|
* `url` String
|
||||||
|
* `method` String
|
||||||
|
* `resourceType` String
|
||||||
|
* `timestamp` Double
|
||||||
|
* `responseHeaders` Object
|
||||||
|
* `fromCache` Boolean - Indicates whether the response was fetched from disk
|
||||||
|
cache.
|
||||||
|
* `statusCode` Integer
|
||||||
|
* `statusLine` String
|
||||||
|
|
||||||
|
The `listener` will be called with `listener(details)` when first byte of the
|
||||||
|
response body is received. For HTTP requests, this means that the status line
|
||||||
|
and response headers are available.
|
||||||
|
|
||||||
|
#### `webRequest.onBeforeRedirect([filter, ]listener)`
|
||||||
|
|
||||||
|
* `filter` Object
|
||||||
|
* `listener` Function
|
||||||
|
* `details` Object
|
||||||
|
* `id` String
|
||||||
|
* `url` String
|
||||||
|
* `method` String
|
||||||
|
* `resourceType` String
|
||||||
|
* `timestamp` Double
|
||||||
|
* `redirectURL` String
|
||||||
|
* `statusCode` Integer
|
||||||
|
* `ip` String (optional) - The server IP address that the request was
|
||||||
|
actually sent to.
|
||||||
|
* `fromCache` Boolean
|
||||||
|
* `responseHeaders` Object
|
||||||
|
|
||||||
|
The `listener` will be called with `listener(details)` when a server initiated
|
||||||
|
redirect is about to occur.
|
||||||
|
|
||||||
|
#### `webRequest.onCompleted([filter, ]listener)`
|
||||||
|
|
||||||
|
* `filter` Object
|
||||||
|
* `listener` Function
|
||||||
|
* `details` Object
|
||||||
|
* `id` Integer
|
||||||
|
* `url` String
|
||||||
|
* `method` String
|
||||||
|
* `resourceType` String
|
||||||
|
* `timestamp` Double
|
||||||
|
* `responseHeaders` Object
|
||||||
|
* `fromCache` Boolean
|
||||||
|
* `statusCode` Integer
|
||||||
|
* `statusLine` String
|
||||||
|
|
||||||
|
The `listener` will be called with `listener(details)` when a request is
|
||||||
|
completed.
|
||||||
|
|
||||||
|
#### `webRequest.onErrorOccurred([filter, ]listener)`
|
||||||
|
|
||||||
|
* `filter` Object
|
||||||
|
* `listener` Function
|
||||||
|
* `details` Object
|
||||||
|
* `id` Integer
|
||||||
|
* `url` String
|
||||||
|
* `method` String
|
||||||
|
* `resourceType` String
|
||||||
|
* `timestamp` Double
|
||||||
|
* `fromCache` Boolean
|
||||||
|
* `error` String - The error description.
|
||||||
|
|
||||||
|
The `listener` will be called with `listener(details)` when an error occurs.
|
||||||
|
|
@ -40,57 +40,3 @@ has to be a field of `BrowserWindow`'s options.
|
||||||
|
|
||||||
Sends a message to the parent window with the specified origin or `*` for no
|
Sends a message to the parent window with the specified origin or `*` for no
|
||||||
origin preference.
|
origin preference.
|
||||||
|
|
||||||
## Class: BrowserWindowProxy
|
|
||||||
|
|
||||||
> Manipulate the child browser window
|
|
||||||
|
|
||||||
Process: [Renderer](../tutorial/quick-start.md#renderer-process)
|
|
||||||
|
|
||||||
The `BrowserWindowProxy` object is returned from `window.open` and provides
|
|
||||||
limited functionality with the child window.
|
|
||||||
|
|
||||||
### Instance Methods
|
|
||||||
|
|
||||||
The `BrowserWindowProxy` object has the following instance methods:
|
|
||||||
|
|
||||||
#### `win.blur()`
|
|
||||||
|
|
||||||
Removes focus from the child window.
|
|
||||||
|
|
||||||
#### `win.close()`
|
|
||||||
|
|
||||||
Forcefully closes the child window without calling its unload event.
|
|
||||||
|
|
||||||
#### `win.eval(code)`
|
|
||||||
|
|
||||||
* `code` String
|
|
||||||
|
|
||||||
Evaluates the code in the child window.
|
|
||||||
|
|
||||||
#### `win.focus()`
|
|
||||||
|
|
||||||
Focuses the child window (brings the window to front).
|
|
||||||
|
|
||||||
#### `win.print()`
|
|
||||||
|
|
||||||
Invokes the print dialog on the child window.
|
|
||||||
|
|
||||||
#### `win.postMessage(message, targetOrigin)`
|
|
||||||
|
|
||||||
* `message` String
|
|
||||||
* `targetOrigin` String
|
|
||||||
|
|
||||||
Sends a message to the child window with the specified origin or `*` for no
|
|
||||||
origin preference.
|
|
||||||
|
|
||||||
In addition to these methods, the child window implements `window.opener` object
|
|
||||||
with no properties and a single method.
|
|
||||||
|
|
||||||
### Instance Properties
|
|
||||||
|
|
||||||
The `BrowserWindowProxy` object has the following instance properties:
|
|
||||||
|
|
||||||
#### `win.closed`
|
|
||||||
|
|
||||||
A Boolean that is set to true after the child window gets closed.
|
|
||||||
|
|
|
||||||
|
|
@ -5,7 +5,7 @@
|
||||||
"asar": "^0.11.0",
|
"asar": "^0.11.0",
|
||||||
"browserify": "^13.1.0",
|
"browserify": "^13.1.0",
|
||||||
"electabul": "~0.0.4",
|
"electabul": "~0.0.4",
|
||||||
"electron-docs-linter": "1.14.1",
|
"electron-docs-linter": "^1.15.0",
|
||||||
"request": "*",
|
"request": "*",
|
||||||
"standard": "^8.4.0",
|
"standard": "^8.4.0",
|
||||||
"standard-markdown": "^2.1.1"
|
"standard-markdown": "^2.1.1"
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue