|
|
@@ -0,0 +1,262 @@
|
|
|
+# `<webview>` tag
|
|
|
+
|
|
|
+Use the `webview` tag to embed 'guest' content (such as web pages) in your
|
|
|
+atom-shell 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
|
|
|
+between your app and embedded content will be asynchronous. This keeps your app
|
|
|
+safe from the embedded content.
|
|
|
+
|
|
|
+## Example
|
|
|
+
|
|
|
+To embed a web page in your app, add the `webview` tag to your app's embedder
|
|
|
+page (this is the app page that will display the guest content). In its simplest
|
|
|
+form, the `webview` tag includes the `src` of the web page and css styles that
|
|
|
+control the appearance of the `webview` container:
|
|
|
+
|
|
|
+```html
|
|
|
+<webview id="foo" src="https://www.github.com/" style="width:640px; height:480px"></webview>
|
|
|
+```
|
|
|
+
|
|
|
+If you want to control the guest content in any way, you can write JavaScript
|
|
|
+that listens for `webview` events and responds to those events using the
|
|
|
+`webview` methods. Here's sample code with two event listeners: one that listens
|
|
|
+for the web page to start loading, the other for the web page to stop loading,
|
|
|
+and displays a "loading..." message during the load time:
|
|
|
+
|
|
|
+```html
|
|
|
+<script>
|
|
|
+ onload = function() {
|
|
|
+ var webview = document.getElementById("foo");
|
|
|
+ var indicator = document.querySelector(".indicator");
|
|
|
+
|
|
|
+ var loadstart = function() {
|
|
|
+ indicator.innerText = "loading...";
|
|
|
+ }
|
|
|
+ var loadstop = function() {
|
|
|
+ indicator.innerText = "";
|
|
|
+ }
|
|
|
+ webview.addEventListener("did-start-loading", loadstart);
|
|
|
+ webview.addEventListener("id-stop-loading", loadstop);
|
|
|
+ }
|
|
|
+</script>
|
|
|
+```
|
|
|
+
|
|
|
+## Tag attributes
|
|
|
+
|
|
|
+### src
|
|
|
+
|
|
|
+```html
|
|
|
+<webview src="http://www.google.com/"></webview>
|
|
|
+```
|
|
|
+
|
|
|
+Returns the visible URL. Writing to this attribute initiates top-level
|
|
|
+navigation.
|
|
|
+
|
|
|
+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
|
|
|
+
|
|
|
+```html
|
|
|
+<webview src="http://www.google.com/" autosize="on" minwidth="576" minheight="432"></webview>
|
|
|
+```
|
|
|
+
|
|
|
+If "on", the `webview` will 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
|
|
|
+enabled. When `autosize` is enabled, the `webview` container size cannot be less
|
|
|
+than the minimum values or greater than the maximum.
|
|
|
+
|
|
|
+## Methods
|
|
|
+
|
|
|
+### `<webview>`.getUrl()
|
|
|
+
|
|
|
+Returns URL of guest page.
|
|
|
+
|
|
|
+### `<webview>`.getTitle()
|
|
|
+
|
|
|
+Returns the title of guest page.
|
|
|
+
|
|
|
+### `<webview>`.isLoading()
|
|
|
+
|
|
|
+Returns whether guest page is still loading resources.
|
|
|
+
|
|
|
+### `<webview>`.isWaitingForResponse()
|
|
|
+
|
|
|
+Returns whether guest page is waiting for a first-response for the main resource
|
|
|
+of the page.
|
|
|
+
|
|
|
+### `<webview>`.stop()
|
|
|
+
|
|
|
+Stops any pending navigation.
|
|
|
+
|
|
|
+### `<webview>`.reload()
|
|
|
+
|
|
|
+Reloads guest page.
|
|
|
+
|
|
|
+### `<webview>`.reloadIgnoringCache()
|
|
|
+
|
|
|
+Reloads guest page and ignores cache.
|
|
|
+
|
|
|
+### `<webview>`.canGoBack()
|
|
|
+
|
|
|
+Returns whether guest page can go back.
|
|
|
+
|
|
|
+### `<webview>`.canGoForward()
|
|
|
+
|
|
|
+Returns whether guest page can go forward.
|
|
|
+
|
|
|
+### `<webview>`.canGoToOffset(offset)
|
|
|
+
|
|
|
+* `offset` Integer
|
|
|
+
|
|
|
+Returns whether guest page can go to `offset`.
|
|
|
+
|
|
|
+### `<webview>`.goBack()
|
|
|
+
|
|
|
+Makes guest page go back.
|
|
|
+
|
|
|
+### `<webview>`.goForward()
|
|
|
+
|
|
|
+Makes guest page go forward.
|
|
|
+
|
|
|
+### `<webview>`.goToIndex(index)
|
|
|
+
|
|
|
+* `index` Integer
|
|
|
+
|
|
|
+Navigates to the specified absolute index.
|
|
|
+
|
|
|
+### `<webview>`.goToOffset(offset)
|
|
|
+
|
|
|
+* `offset` Integer
|
|
|
+
|
|
|
+Navigates to the specified offset from the "current entry".
|
|
|
+
|
|
|
+### `<webview>`.isCrashed()
|
|
|
+
|
|
|
+Whether the renderer process has crashed.
|
|
|
+
|
|
|
+### `<webview>`.setUserAgent(userAgent)
|
|
|
+
|
|
|
+* `userAgent` String
|
|
|
+
|
|
|
+Overrides the user agent for guest page.
|
|
|
+
|
|
|
+### `<webview>`.insertCSS(css)
|
|
|
+
|
|
|
+* `css` String
|
|
|
+
|
|
|
+Injects CSS into guest page.
|
|
|
+
|
|
|
+### `<webview>`.executeJavaScript(code)
|
|
|
+
|
|
|
+* `code` String
|
|
|
+
|
|
|
+Evaluate `code` in guest page.
|
|
|
+
|
|
|
+### `<webview>`.send(channel[, args...])
|
|
|
+
|
|
|
+* `channel` String
|
|
|
+
|
|
|
+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.
|
|
|
+
|
|
|
+See [WebContents.send](browser-window.md#webcontentssendchannel-args) for
|
|
|
+examples.
|
|
|
+
|
|
|
+## DOM events
|
|
|
+
|
|
|
+### 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.
|
|
|
+
|
|
|
+### did-fail-load
|
|
|
+
|
|
|
+* `errorCode` Integer
|
|
|
+* `errorDescription` String
|
|
|
+
|
|
|
+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
|
|
|
+
|
|
|
+* `isMainFrame` Boolean
|
|
|
+
|
|
|
+Fired when a frame has done navigation.
|
|
|
+
|
|
|
+### did-start-loading
|
|
|
+
|
|
|
+Corresponds to the points in time when the spinner of the tab starts spinning.
|
|
|
+
|
|
|
+### did-stop-loading
|
|
|
+
|
|
|
+Corresponds to the points in time when the spinner of the tab stops spinning.
|
|
|
+
|
|
|
+### did-get-redirect-request
|
|
|
+
|
|
|
+* `oldUrl` String
|
|
|
+* `newUrl` String
|
|
|
+* `isMainFrame` Boolean
|
|
|
+
|
|
|
+Fired when a redirect was received while requesting a resource.
|
|
|
+
|
|
|
+### console-message
|
|
|
+
|
|
|
+* `level` Integer
|
|
|
+* `message` String
|
|
|
+* `line` Integer
|
|
|
+* `sourceId` String
|
|
|
+
|
|
|
+Fired when the guest window logs a console message.
|
|
|
+
|
|
|
+The following example code forwards all log messages to the embedder's console
|
|
|
+without regard for log level or other properties.
|
|
|
+
|
|
|
+```javascript
|
|
|
+webview.addEventListener('console-message', function(e) {
|
|
|
+ console.log('Guest page logged a message: ', e.message);
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+### new-window
|
|
|
+
|
|
|
+* `url` String
|
|
|
+* `partitionId` String
|
|
|
+
|
|
|
+Fired when the guest page attempts to open a new browser window.
|
|
|
+
|
|
|
+The following example code opens the new url in system's default browser.
|
|
|
+
|
|
|
+```javascript
|
|
|
+webview.addEventListener('new-window', function(e) {
|
|
|
+ require('shell').openExternal(e.url);
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+### close
|
|
|
+
|
|
|
+Fired when the guest window attempts to close itself.
|
|
|
+
|
|
|
+The following example code navigates the `webview` to `about:blank` when the
|
|
|
+guest attempts to close itself.
|
|
|
+
|
|
|
+```javascript
|
|
|
+webview.addEventListener('close', function() {
|
|
|
+ webview.src = 'about:blank';
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+### crashed
|
|
|
+
|
|
|
+Fired when the renderer process is crashed.
|
|
|
+
|
|
|
+### destroyed
|
|
|
+
|
|
|
+Fired when the WebContents is destroyed.
|
Cheng Zhao