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

Standardize web-view-tag

Browse source
This commit is contained in:
Jessica Lord 2015-08-28 23:20:59 -07:00
parent 2c3ed90ff3
commit 8d40714f78
1 changed files with 129 additions and 98 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

227
docs/api/web-view-tag.md
View file

@ -1,12 +1,12 @@
# `<webview>` tag # The `<webview>` tag
Use the `webview` tag to embed 'guest' content (such as web pages) in your 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; 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 An embedder page within your app controls how the guest content is laid out and
rendered. rendered.
Different from the `iframe`, the `webview` runs in a separate process than your 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 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 between your app and embedded content will be asynchronous. This keeps your app
safe from the embedded content. safe from the embedded content.
@ -45,9 +45,11 @@ and displays a "loading..." message during the load time:
</script> </script>
``` ```
## Tag attributes ## Tag Attributes
### src The `webview` tag has the following attributes:
### `src`
```html ```html
<webview src="https://www.github.com/"></webview> <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 The `src` attribute can also accept data URLs, such as
`data:text/plain,Hello, world!`. `data:text/plain,Hello, world!`.
### autosize ### `autosize`
```html ```html
<webview src="https://www.github.com/" autosize="on" minwidth="576" minheight="432"></webview> <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 If "on", the `webview` container will automatically resize within the
bounds specified by the attributes `minwidth`, `minheight`, `maxwidth`, and 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 enabled. When `autosize` is enabled, the `webview` container size cannot be less
than the minimum values or greater than the maximum. than the minimum values or greater than the maximum.
### nodeintegration ### `nodeintegration`
```html ```html
<webview src="http://www.google.com/" nodeintegration></webview> <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 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. APIs like `require` and `process` to access low level system resources.
### plugins ### `plugins`
```html ```html
<webview src="https://www.github.com/" plugins></webview> <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. If "on", the guest page in `webview` will be able to use browser plugins.
### preload ### `preload`
```html ```html
<webview src="https://www.github.com/" preload="./test.js"></webview> <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 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 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 ```html
<webview src="https://www.github.com/" httpreferrer="http://cheng.guru"></webview> <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. Sets the referrer URL for the guest page.
### useragent ### `useragent`
```html ```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> <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 ```html
<webview src="https://www.github.com/" disablewebsecurity></webview> <webview src="https://www.github.com/" disablewebsecurity></webview>
@ -130,7 +133,10 @@ If "on", the guest page will have web security disabled.
## Methods ## 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** **Example**
```javascript ```javascript
webview.addEventListener("dom-ready", function() { webview.addEventListener("dom-ready", function() {
@ -138,194 +144,195 @@ webview.addEventListener("dom-ready", function() {
}); });
``` ```
### `<webview>`.getUrl() ### `<webview>.getUrl()`
Returns URL of guest page. Returns URL of guest page.
### `<webview>`.getTitle() ### `<webview>.getTitle()`
Returns the title of guest page. 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 Returns a boolean whether guest page is waiting for a first-response for the
of the page. main resource of the page.
### `<webview>`.stop() ### `<webview>.stop()`
Stops any pending navigation. Stops any pending navigation.
### `<webview>`.reload() ### `<webview>.reload()`
Reloads guest page. Reloads guest page.
### `<webview>`.reloadIgnoringCache() ### `<webview>.reloadIgnoringCache()`
Reloads guest page and ignores cache. 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 * `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. Clears the navigation history.
### `<webview>`.goBack() ### `<webview>.goBack()`
Makes guest page go back. Makes guest page go back.
### `<webview>`.goForward() ### `<webview>.goForward()`
Makes guest page go forward. Makes guest page go forward.
### `<webview>`.goToIndex(index) ### `<webview>.goToIndex(index)`
* `index` Integer * `index` Integer
Navigates to the specified absolute index. Navigates to the specified absolute index.
### `<webview>`.goToOffset(offset) ### `<webview>.goToOffset(offset)`
* `offset` Integer * `offset` Integer
Navigates to the specified offset from the "current entry". Navigates to the specified offset from the "current entry".
### `<webview>`.isCrashed() ### `<webview>.isCrashed()`
Whether the renderer process has crashed. Whether the renderer process has crashed.
### `<webview>`.setUserAgent(userAgent) ### `<webview>.setUserAgent(userAgent)`
* `userAgent` String * `userAgent` String
Overrides the user agent for guest page. 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 * `css` String
Injects CSS into guest page. Injects CSS into guest page.
### `<webview>`.executeJavaScript(code, userGesture) ### `<webview>.executeJavaScript(code, userGesture)`
* `code` String * `code` String
* `userGesture` Boolean - Default false * `userGesture` Boolean - Default `false`.
Evaluates `code` in page. If `userGesture` is set will create user gesture context, Evaluates `code` in page. If `userGesture` is set, it will create user gesture
HTML api like `requestFullScreen` which require user action can take advantage context. HTML API like `requestFullScreen` which require user action can take
of this option for automation. advantage of this option for automation.
### `<webview>`.openDevTools() ### `<webview>.openDevTools()`
Opens a devtools window for guest page. Opens a devtools window for guest page.
### `<webview>`.closeDevTools() ### `<webview>.closeDevTools()`
Closes the devtools window of guest page. 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 * `x` Integer
* `y` Integer * `y` Integer
Starts inspecting element at position (`x`, `y`) of guest page. 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. 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. Set guest page muted.
### `<webview>`.isAudioMuted() ### `<webview>.isAudioMuted()`
Returns whether guest page has been muted. Returns whether guest page has been muted.
### `<webview>`.undo() ### `<webview>.undo()`
Executes editing command `undo` in page. Executes editing command `undo` in page.
### `<webview>`.redo() ### `<webview>.redo()`
Executes editing command `redo` in page. Executes editing command `redo` in page.
### `<webview>`.cut() ### `<webview>.cut()`
Executes editing command `cut` in page. Executes editing command `cut` in page.
### `<webview>`.copy() ### `<webview>.copy()`
Executes editing command `copy` in page. Executes editing command `copy` in page.
### `<webview>`.paste() ### `<webview>.paste()`
Executes editing command `paste` in page. Executes editing command `paste` in page.
### `<webview>`.pasteAndMatchStyle() ### `<webview>.pasteAndMatchStyle()`
Executes editing command `pasteAndMatchStyle` in page. Executes editing command `pasteAndMatchStyle` in page.
### `<webview>`.delete() ### `<webview>.delete()`
Executes editing command `delete` in page. Executes editing command `delete` in page.
### `<webview>`.selectAll() ### `<webview>.selectAll()`
Executes editing command `selectAll` in page. Executes editing command `selectAll` in page.
### `<webview>`.unselect() ### `<webview>.unselect()`
Executes editing command `unselect` in page. Executes editing command `unselect` in page.
### `<webview>`.replace(text) ### `<webview.replace(text)`
* `text` String * `text` String
Executes editing command `replace` in page. Executes editing command `replace` in page.
### `<webview>`.replaceMisspelling(text) ### `<webview>.replaceMisspelling(text)`
* `text` String * `text` String
Executes editing command `replaceMisspelling` in page. 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)` Prints webview's web page as PDF, Same with `webContents.printToPDF(options, callback)`
### `<webview>`.send(channel[, args...]) ### `<webview>.send(channel[, args...])`
* `channel` String * `channel` String
* `arg` (optional)
Send `args..` to guest page via `channel` in asynchronous message, the guest 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. page can handle it by listening to the `channel` event of `ipc` module.
@ -335,7 +342,11 @@ examples.
## DOM events ## DOM events
### load-commit The following DOM events are available to the `webview` tag:
### Event: 'load-commit'
Returns:
* `url` String * `url` String
* `isMainFrame` Boolean * `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 document as well as subframe document-level loads, but does not include
asynchronous resource loads. 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 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 * `errorCode` Integer
* `errorDescription` String * `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 This event is like `did-finish-load`, but fired when the load failed or was
cancelled, e.g. `window.stop()` is invoked. cancelled, e.g. `window.stop()` is invoked.
### did-frame-finish-load ### Event: 'did-frame-finish-load'
Returns:
* `isMainFrame` Boolean * `isMainFrame` Boolean
Fired when a frame has done navigation. 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. 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. 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 * `status` Boolean
* `newUrl` String * `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. Fired when details regarding a requested resource is available.
`status` indicates socket connection to download the resource. `status` indicates socket connection to download the resource.
### did-get-redirect-request ### Event: 'did-get-redirect-request'
Returns:
* `oldUrl` String * `oldUrl` String
* `newUrl` 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. Fired when a redirect was received while requesting a resource.
### dom-ready ### Event: 'dom-ready'
Fired when document in the given frame is loaded. Fired when document in the given frame is loaded.
### page-title-set ### Event: 'page-title-set'
Returns:
* `title` String * `title` String
* `explicitSet` Boolean * `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 Fired when page title is set during navigation. `explicitSet` is false when title is synthesised from file
url. 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. 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 * `level` Integer
* `message` String * `message` String
@ -436,7 +461,9 @@ webview.addEventListener('console-message', function(e) {
}); });
``` ```
### new-window ### Event: 'new-window'
Returns:
* `url` String * `url` String
* `frameName` 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. 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 * `channel` String
* `args` Array * `args` Array
@ -493,21 +522,23 @@ ipc.on('ping', function() {
}); });
``` ```
### crashed ### Event: 'crashed'
Fired when the renderer process is crashed. Fired when the renderer process is crashed.
### gpu-crashed ### Event: 'gpu-crashed'
Fired when the gpu process is crashed. Fired when the gpu process is crashed.
### plugin-crashed ### Event: 'plugin-crashed'
Returns:
* `name` String * `name` String
* `version` String * `version` String
Fired when a plugin process is crashed. Fired when a plugin process is crashed.
### destroyed ### Event: 'destroyed'
Fired when the WebContents is destroyed. Fired when the WebContents is destroyed.