Standardize web-view-tag
This commit is contained in:
Jessica Lord
parent
2c3ed90ff3
commit
8d40714f78
1 changed files with 129 additions and 98 deletions
|
|
@ -1,12 +1,12 @@
|
|||
# `<webview>` tag
|
||||
# The `<webview>` tag
|
||||
|
||||
Use the `webview` tag to embed 'guest' content (such as web pages) in your
|
||||
Electron app. The guest content is contained within the `webview` container;
|
||||
an embedder page within your app controls how the guest content is laid out and
|
||||
Electron app. The guest content is contained within the `webview` container.
|
||||
An embedder page within your app controls how the guest content is laid out and
|
||||
rendered.
|
||||
|
||||
Different from the `iframe`, the `webview` runs in a separate process than your
|
||||
app; it doesn't have the same permissions as your web page and all interactions
|
||||
Different from an `iframe`, the `webview` runs in a separate process than your
|
||||
app. It doesn't have the same permissions as your web page and all interactions
|
||||
between your app and embedded content will be asynchronous. This keeps your app
|
||||
safe from the embedded content.
|
||||
|
||||
|
|
@ -45,9 +45,11 @@ and displays a "loading..." message during the load time:
|
|||
</script>
|
||||
```
|
||||
|
||||
## Tag attributes
|
||||
## Tag Attributes
|
||||
|
||||
### src
|
||||
The `webview` tag has the following attributes:
|
||||
|
||||
### `src`
|
||||
|
||||
```html
|
||||
<webview src="https://www.github.com/"></webview>
|
||||
|
|
@ -61,7 +63,7 @@ Assigning `src` its own value will reload the current page.
|
|||
The `src` attribute can also accept data URLs, such as
|
||||
`data:text/plain,Hello, world!`.
|
||||
|
||||
### autosize
|
||||
### `autosize`
|
||||
|
||||
```html
|
||||
<webview src="https://www.github.com/" autosize="on" minwidth="576" minheight="432"></webview>
|
||||
|
|
@ -69,11 +71,11 @@ The `src` attribute can also accept data URLs, such as
|
|||
|
||||
If "on", the `webview` container will automatically resize within the
|
||||
bounds specified by the attributes `minwidth`, `minheight`, `maxwidth`, and
|
||||
`maxheight`. These contraints do not impact the `webview` UNLESS `autosize` is
|
||||
`maxheight`. These constraints do not impact the `webview` UNLESS `autosize` is
|
||||
enabled. When `autosize` is enabled, the `webview` container size cannot be less
|
||||
than the minimum values or greater than the maximum.
|
||||
|
||||
### nodeintegration
|
||||
### `nodeintegration`
|
||||
|
||||
```html
|
||||
<webview src="http://www.google.com/" nodeintegration></webview>
|
||||
|
|
@ -82,7 +84,7 @@ than the minimum values or greater than the maximum.
|
|||
If "on", the guest page in `webview` will have node integration and can use node
|
||||
APIs like `require` and `process` to access low level system resources.
|
||||
|
||||
### plugins
|
||||
### `plugins`
|
||||
|
||||
```html
|
||||
<webview src="https://www.github.com/" plugins></webview>
|
||||
|
|
@ -90,7 +92,7 @@ APIs like `require` and `process` to access low level system resources.
|
|||
|
||||
If "on", the guest page in `webview` will be able to use browser plugins.
|
||||
|
||||
### preload
|
||||
### `preload`
|
||||
|
||||
```html
|
||||
<webview src="https://www.github.com/" preload="./test.js"></webview>
|
||||
|
|
@ -102,9 +104,9 @@ will be loaded by `require` in guest page under the hood.
|
|||
|
||||
When the guest page doesn't have node integration this script will still have
|
||||
access to all Node APIs, but global objects injected by Node will be deleted
|
||||
after this script has done execution.
|
||||
after this script has completed execution.
|
||||
|
||||
### httpreferrer
|
||||
### `httpreferrer`
|
||||
|
||||
```html
|
||||
<webview src="https://www.github.com/" httpreferrer="http://cheng.guru"></webview>
|
||||
|
|
@ -112,15 +114,16 @@ after this script has done execution.
|
|||
|
||||
Sets the referrer URL for the guest page.
|
||||
|
||||
### useragent
|
||||
### `useragent`
|
||||
|
||||
```html
|
||||
<webview src="https://www.github.com/" useragent="Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; AS; rv:11.0) like Gecko"></webview>
|
||||
```
|
||||
|
||||
Sets the user agent for the guest page before the page is navigated to. Once the page is loaded, use the `setUserAgent` method to change the user agent.
|
||||
Sets the user agent for the guest page before the page is navigated to. Once the
|
||||
page is loaded, use the `setUserAgent` method to change the user agent.
|
||||
|
||||
### disablewebsecurity
|
||||
### `disablewebsecurity`
|
||||
|
||||
```html
|
||||
<webview src="https://www.github.com/" disablewebsecurity></webview>
|
||||
|
|
@ -130,7 +133,10 @@ If "on", the guest page will have web security disabled.
|
|||
|
||||
## Methods
|
||||
|
||||
The webview element must be loaded before using the methods.
|
||||
The `webview` tag has the following methods:
|
||||
|
||||
**Note**: The webview element must be loaded before using the methods.
|
||||
|
||||
**Example**
|
||||
```javascript
|
||||
webview.addEventListener("dom-ready", function() {
|
||||
|
|
@ -138,194 +144,195 @@ webview.addEventListener("dom-ready", function() {
|
|||
});
|
||||
```
|
||||
|
||||
### `<webview>`.getUrl()
|
||||
### `<webview>.getUrl()`
|
||||
|
||||
Returns URL of guest page.
|
||||
|
||||
### `<webview>`.getTitle()
|
||||
### `<webview>.getTitle()`
|
||||
|
||||
Returns the title of guest page.
|
||||
|
||||
### `<webview>`.isLoading()
|
||||
### `<webview>.isLoading()`
|
||||
|
||||
Returns whether guest page is still loading resources.
|
||||
Returns a boolean whether guest page is still loading resources.
|
||||
|
||||
### `<webview>`.isWaitingForResponse()
|
||||
### `<webview>.isWaitingForResponse()`
|
||||
|
||||
Returns whether guest page is waiting for a first-response for the main resource
|
||||
of the page.
|
||||
Returns a boolean whether guest page is waiting for a first-response for the
|
||||
main resource of the page.
|
||||
|
||||
### `<webview>`.stop()
|
||||
### `<webview>.stop()`
|
||||
|
||||
Stops any pending navigation.
|
||||
|
||||
### `<webview>`.reload()
|
||||
### `<webview>.reload()`
|
||||
|
||||
Reloads guest page.
|
||||
|
||||
### `<webview>`.reloadIgnoringCache()
|
||||
### `<webview>.reloadIgnoringCache()`
|
||||
|
||||
Reloads guest page and ignores cache.
|
||||
|
||||
### `<webview>`.canGoBack()
|
||||
### `<webview>.canGoBack()`
|
||||
|
||||
Returns whether guest page can go back.
|
||||
Returns a boolean whether guest page can go back.
|
||||
|
||||
### `<webview>`.canGoForward()
|
||||
### `<webview>.canGoForward()`
|
||||
|
||||
Returns whether guest page can go forward.
|
||||
Returns a boolean whether guest page can go forward.
|
||||
|
||||
### `<webview>`.canGoToOffset(offset)
|
||||
### `<webview>.canGoToOffset(offset)`
|
||||
|
||||
* `offset` Integer
|
||||
|
||||
Returns whether guest page can go to `offset`.
|
||||
Returns a boolean whether guest page can go to `offset`.
|
||||
|
||||
### `<webview>`.clearHistory()
|
||||
### `<webview>.clearHistory()`
|
||||
|
||||
Clears the navigation history.
|
||||
|
||||
### `<webview>`.goBack()
|
||||
### `<webview>.goBack()`
|
||||
|
||||
Makes guest page go back.
|
||||
|
||||
### `<webview>`.goForward()
|
||||
### `<webview>.goForward()`
|
||||
|
||||
Makes guest page go forward.
|
||||
|
||||
### `<webview>`.goToIndex(index)
|
||||
### `<webview>.goToIndex(index)`
|
||||
|
||||
* `index` Integer
|
||||
|
||||
Navigates to the specified absolute index.
|
||||
|
||||
### `<webview>`.goToOffset(offset)
|
||||
### `<webview>.goToOffset(offset)`
|
||||
|
||||
* `offset` Integer
|
||||
|
||||
Navigates to the specified offset from the "current entry".
|
||||
|
||||
### `<webview>`.isCrashed()
|
||||
### `<webview>.isCrashed()`
|
||||
|
||||
Whether the renderer process has crashed.
|
||||
|
||||
### `<webview>`.setUserAgent(userAgent)
|
||||
### `<webview>.setUserAgent(userAgent)`
|
||||
|
||||
* `userAgent` String
|
||||
|
||||
Overrides the user agent for guest page.
|
||||
|
||||
### `<webview>`.getUserAgent()
|
||||
### `<webview>.getUserAgent()`
|
||||
|
||||
Returns a `String` represents the user agent for guest page.
|
||||
Returns a `String` representing the user agent for guest page.
|
||||
|
||||
### `<webview>`.insertCSS(css)
|
||||
### `<webview>.insertCSS(css)`
|
||||
|
||||
* `css` String
|
||||
|
||||
Injects CSS into guest page.
|
||||
|
||||
### `<webview>`.executeJavaScript(code, userGesture)
|
||||
### `<webview>.executeJavaScript(code, userGesture)`
|
||||
|
||||
* `code` String
|
||||
* `userGesture` Boolean - Default false
|
||||
* `userGesture` Boolean - Default `false`.
|
||||
|
||||
Evaluates `code` in page. If `userGesture` is set will create user gesture context,
|
||||
HTML api like `requestFullScreen` which require user action can take advantage
|
||||
of this option for automation.
|
||||
Evaluates `code` in page. If `userGesture` is set, it will create user gesture
|
||||
context. HTML API like `requestFullScreen` which require user action can take
|
||||
advantage of this option for automation.
|
||||
|
||||
### `<webview>`.openDevTools()
|
||||
### `<webview>.openDevTools()`
|
||||
|
||||
Opens a devtools window for guest page.
|
||||
|
||||
### `<webview>`.closeDevTools()
|
||||
### `<webview>.closeDevTools()`
|
||||
|
||||
Closes the devtools window of guest page.
|
||||
|
||||
### `<webview>`.isDevToolsOpened()
|
||||
### `<webview>.isDevToolsOpened()`
|
||||
|
||||
Returns whether guest page has a devtools window attached.
|
||||
Returns a boolean whether guest page has a devtools window attached.
|
||||
|
||||
### `<webview>`.inspectElement(x, y)
|
||||
### `<webview>.inspectElement(x, y)`
|
||||
|
||||
* `x` Integer
|
||||
* `y` Integer
|
||||
|
||||
Starts inspecting element at position (`x`, `y`) of guest page.
|
||||
|
||||
### `<webview>`.inspectServiceWorker()
|
||||
### `<webview>.inspectServiceWorker()`
|
||||
|
||||
Opens the devtools for the service worker context present in the guest page.
|
||||
|
||||
### `<webview>`.setAudioMuted(muted)
|
||||
### `<webview>.setAudioMuted(muted)`
|
||||
|
||||
+ `muted` Boolean
|
||||
* `muted` Boolean
|
||||
|
||||
Set guest page muted.
|
||||
|
||||
### `<webview>`.isAudioMuted()
|
||||
### `<webview>.isAudioMuted()`
|
||||
|
||||
Returns whether guest page has been muted.
|
||||
|
||||
### `<webview>`.undo()
|
||||
### `<webview>.undo()`
|
||||
|
||||
Executes editing command `undo` in page.
|
||||
|
||||
### `<webview>`.redo()
|
||||
### `<webview>.redo()`
|
||||
|
||||
Executes editing command `redo` in page.
|
||||
|
||||
### `<webview>`.cut()
|
||||
### `<webview>.cut()`
|
||||
|
||||
Executes editing command `cut` in page.
|
||||
|
||||
### `<webview>`.copy()
|
||||
### `<webview>.copy()`
|
||||
|
||||
Executes editing command `copy` in page.
|
||||
|
||||
### `<webview>`.paste()
|
||||
### `<webview>.paste()`
|
||||
|
||||
Executes editing command `paste` in page.
|
||||
|
||||
### `<webview>`.pasteAndMatchStyle()
|
||||
### `<webview>.pasteAndMatchStyle()`
|
||||
|
||||
Executes editing command `pasteAndMatchStyle` in page.
|
||||
|
||||
### `<webview>`.delete()
|
||||
### `<webview>.delete()`
|
||||
|
||||
Executes editing command `delete` in page.
|
||||
|
||||
### `<webview>`.selectAll()
|
||||
### `<webview>.selectAll()`
|
||||
|
||||
Executes editing command `selectAll` in page.
|
||||
|
||||
### `<webview>`.unselect()
|
||||
### `<webview>.unselect()`
|
||||
|
||||
Executes editing command `unselect` in page.
|
||||
|
||||
### `<webview>`.replace(text)
|
||||
### `<webview.replace(text)`
|
||||
|
||||
* `text` String
|
||||
|
||||
Executes editing command `replace` in page.
|
||||
|
||||
### `<webview>`.replaceMisspelling(text)
|
||||
### `<webview>.replaceMisspelling(text)`
|
||||
|
||||
* `text` String
|
||||
|
||||
Executes editing command `replaceMisspelling` in page.
|
||||
|
||||
### `<webview>`.print([options])
|
||||
### `<webview>.print([options])`
|
||||
|
||||
Prints webview's web page. Same with `webContents.print([options])`.
|
||||
Prints `webview`'s web page. Same with `webContents.print([options])`.
|
||||
|
||||
### `<webview>`.printToPDF(options, callback)
|
||||
### `<webview>.printToPDF(options, callback)`
|
||||
|
||||
Prints webview's web page as PDF, Same with `webContents.printToPDF(options, callback)`
|
||||
|
||||
### `<webview>`.send(channel[, args...])
|
||||
### `<webview>.send(channel[, args...])`
|
||||
|
||||
* `channel` String
|
||||
* `arg` (optional)
|
||||
|
||||
Send `args..` to guest page via `channel` in asynchronous message, the guest
|
||||
page can handle it by listening to the `channel` event of `ipc` module.
|
||||
|
|
@ -335,7 +342,11 @@ examples.
|
|||
|
||||
## DOM events
|
||||
|
||||
### load-commit
|
||||
The following DOM events are available to the `webview` tag:
|
||||
|
||||
### Event: 'load-commit'
|
||||
|
||||
Returns:
|
||||
|
||||
* `url` String
|
||||
* `isMainFrame` Boolean
|
||||
|
|
@ -344,12 +355,14 @@ Fired when a load has committed. This includes navigation within the current
|
|||
document as well as subframe document-level loads, but does not include
|
||||
asynchronous resource loads.
|
||||
|
||||
### did-finish-load
|
||||
### Event: 'did-finish-load'
|
||||
|
||||
Fired when the navigation is done, i.e. the spinner of the tab will stop
|
||||
spinning, and the `onload` event was dispatched.
|
||||
spinning, and the `onload` event is dispatched.
|
||||
|
||||
### did-fail-load
|
||||
### Event: 'did-fail-load'
|
||||
|
||||
Returns:
|
||||
|
||||
* `errorCode` Integer
|
||||
* `errorDescription` String
|
||||
|
|
@ -357,21 +370,25 @@ spinning, and the `onload` event was dispatched.
|
|||
This event is like `did-finish-load`, but fired when the load failed or was
|
||||
cancelled, e.g. `window.stop()` is invoked.
|
||||
|
||||
### did-frame-finish-load
|
||||
### Event: 'did-frame-finish-load'
|
||||
|
||||
Returns:
|
||||
|
||||
* `isMainFrame` Boolean
|
||||
|
||||
Fired when a frame has done navigation.
|
||||
|
||||
### did-start-loading
|
||||
### Event: 'did-start-loading'
|
||||
|
||||
Corresponds to the points in time when the spinner of the tab starts spinning.
|
||||
|
||||
### did-stop-loading
|
||||
### Event: 'did-stop-loading'
|
||||
|
||||
Corresponds to the points in time when the spinner of the tab stops spinning.
|
||||
|
||||
### did-get-response-details
|
||||
### Event: 'did-get-response-details'
|
||||
|
||||
Returns:
|
||||
|
||||
* `status` Boolean
|
||||
* `newUrl` String
|
||||
|
|
@ -384,7 +401,9 @@ Corresponds to the points in time when the spinner of the tab stops spinning.
|
|||
Fired when details regarding a requested resource is available.
|
||||
`status` indicates socket connection to download the resource.
|
||||
|
||||
### did-get-redirect-request
|
||||
### Event: 'did-get-redirect-request'
|
||||
|
||||
Returns:
|
||||
|
||||
* `oldUrl` String
|
||||
* `newUrl` String
|
||||
|
|
@ -392,11 +411,13 @@ Fired when details regarding a requested resource is available.
|
|||
|
||||
Fired when a redirect was received while requesting a resource.
|
||||
|
||||
### dom-ready
|
||||
### Event: 'dom-ready'
|
||||
|
||||
Fired when document in the given frame is loaded.
|
||||
|
||||
### page-title-set
|
||||
### Event: 'page-title-set'
|
||||
|
||||
Returns:
|
||||
|
||||
* `title` String
|
||||
* `explicitSet` Boolean
|
||||
|
|
@ -404,21 +425,25 @@ Fired when document in the given frame is loaded.
|
|||
Fired when page title is set during navigation. `explicitSet` is false when title is synthesised from file
|
||||
url.
|
||||
|
||||
### page-favicon-updated
|
||||
### Event: 'page-favicon-updated'
|
||||
|
||||
* `favicons` Array - Array of Urls
|
||||
Returns:
|
||||
|
||||
* `favicons` Array - Array of Urls.
|
||||
|
||||
Fired when page receives favicon urls.
|
||||
|
||||
### enter-html-full-screen
|
||||
### Event: 'enter-html-full-screen'
|
||||
|
||||
Fired when page enters fullscreen triggered by html api.
|
||||
Fired when page enters fullscreen triggered by HTML API.
|
||||
|
||||
### leave-html-full-screen
|
||||
### Event: 'leave-html-full-screen'
|
||||
|
||||
Fired when page leaves fullscreen triggered by html api.
|
||||
Fired when page leaves fullscreen triggered by HTML API.
|
||||
|
||||
### console-message
|
||||
### Event: 'console-message'
|
||||
|
||||
Returns:
|
||||
|
||||
* `level` Integer
|
||||
* `message` String
|
||||
|
|
@ -436,7 +461,9 @@ webview.addEventListener('console-message', function(e) {
|
|||
});
|
||||
```
|
||||
|
||||
### new-window
|
||||
### Event: 'new-window'
|
||||
|
||||
Returns:
|
||||
|
||||
* `url` String
|
||||
* `frameName` String
|
||||
|
|
@ -453,7 +480,7 @@ webview.addEventListener('new-window', function(e) {
|
|||
});
|
||||
```
|
||||
|
||||
### close
|
||||
### Event: 'close'
|
||||
|
||||
Fired when the guest page attempts to close itself.
|
||||
|
||||
|
|
@ -466,7 +493,9 @@ webview.addEventListener('close', function() {
|
|||
});
|
||||
```
|
||||
|
||||
### ipc-message
|
||||
### Event: 'ipc-message'
|
||||
|
||||
Returns:
|
||||
|
||||
* `channel` String
|
||||
* `args` Array
|
||||
|
|
@ -493,21 +522,23 @@ ipc.on('ping', function() {
|
|||
});
|
||||
```
|
||||
|
||||
### crashed
|
||||
### Event: 'crashed'
|
||||
|
||||
Fired when the renderer process is crashed.
|
||||
|
||||
### gpu-crashed
|
||||
### Event: 'gpu-crashed'
|
||||
|
||||
Fired when the gpu process is crashed.
|
||||
|
||||
### plugin-crashed
|
||||
### Event: 'plugin-crashed'
|
||||
|
||||
Returns:
|
||||
|
||||
* `name` String
|
||||
* `version` String
|
||||
|
||||
Fired when a plugin process is crashed.
|
||||
|
||||
### destroyed
|
||||
### Event: 'destroyed'
|
||||
|
||||
Fired when the WebContents is destroyed.
|
||||
|
|
|
|||
Loading…
Reference in a new issue