-# `<webview>` Tag\r
-\r
-> Display external web content in an isolated frame and process.\r
-\r
-Use the `webview` tag to embed 'guest' content (such as web pages) in your\r
-Electron app. The guest content is contained within the `webview` container.\r
-An embedded page within your app controls how the guest content is laid out and\r
-rendered.\r
-\r
-Unlike an `iframe`, the `webview` runs in a separate process than your\r
-app. It doesn't have the same permissions as your web page and all interactions\r
-between your app and embedded content will be asynchronous. This keeps your app\r
-safe from the embedded content.\r
-\r
-For security purposes, `webview` can only be used in `BrowserWindow`s that have\r
-`nodeIntegration` enabled.\r
-\r
-## Example\r
-\r
-To embed a web page in your app, add the `webview` tag to your app's embedder\r
-page (this is the app page that will display the guest content). In its simplest\r
-form, the `webview` tag includes the `src` of the web page and css styles that\r
-control the appearance of the `webview` container:\r
-\r
-```html\r
-<webview id="foo" src="https://www.github.com/" style="display:inline-flex; width:640px; height:480px"></webview>\r
-```\r
-\r
-If you want to control the guest content in any way, you can write JavaScript\r
-that listens for `webview` events and responds to those events using the\r
-`webview` methods. Here's sample code with two event listeners: one that listens\r
-for the web page to start loading, the other for the web page to stop loading,\r
-and displays a "loading..." message during the load time:\r
-\r
-```html\r
-<script>\r
- onload = () => {\r
- const webview = document.getElementById('foo')\r
- const indicator = document.querySelector('.indicator')\r
-\r
- const loadstart = () => {\r
- indicator.innerText = 'loading...'\r
- }\r
-\r
- const loadstop = () => {\r
- indicator.innerText = ''\r
- }\r
-\r
- webview.addEventListener('did-start-loading', loadstart)\r
- webview.addEventListener('did-stop-loading', loadstop)\r
- }\r
-</script>\r
-```\r
-\r
-## CSS Styling Notes\r
-\r
-Please note that the `webview` tag's style uses `display:flex;` internally to\r
-ensure the child `object` element fills the full height and width of its `webview`\r
-container when used with traditional and flexbox layouts (since v0.36.11). Please\r
-do not overwrite the default `display:flex;` CSS property, unless specifying\r
-`display:inline-flex;` for inline layout.\r
-\r
-`webview` has issues being hidden using the `hidden` attribute or using `display: none;`.\r
-It can cause unusual rendering behaviour within its child `browserplugin` object\r
-and the web page is reloaded, when the `webview` is un-hidden, as opposed to just\r
-becoming visible again. The recommended approach is to hide the `webview` using\r
-CSS by zeroing the `width` & `height` and allowing the element to shrink to the 0px\r
-dimensions via `flex`.\r
-\r
-```html\r
-<style>\r
- webview {\r
- display:inline-flex;\r
- width:640px;\r
- height:480px;\r
- }\r
- webview.hide {\r
- flex: 0 1;\r
- width: 0px;\r
- height: 0px;\r
- }\r
-</style>\r
-```\r
-\r
-## Tag Attributes\r
-\r
-The `webview` tag has the following attributes:\r
-\r
-### `src`\r
-\r
-```html\r
-<webview src="https://www.github.com/"></webview>\r
-```\r
-\r
-Returns the visible URL. Writing to this attribute initiates top-level\r
-navigation.\r
-\r
-Assigning `src` its own value will reload the current page.\r
-\r
-The `src` attribute can also accept data URLs, such as\r
-`data:text/plain,Hello, world!`.\r
-\r
-### `autosize`\r
-\r
-```html\r
-<webview src="https://www.github.com/" autosize="on" minwidth="576" minheight="432"></webview>\r
-```\r
-\r
-If "on", the `webview` container will automatically resize within the\r
-bounds specified by the attributes `minwidth`, `minheight`, `maxwidth`, and\r
-`maxheight`. These constraints do not impact the `webview` unless `autosize` is\r
-enabled. When `autosize` is enabled, the `webview` container size cannot be less\r
-than the minimum values or greater than the maximum.\r
-\r
-### `nodeintegration`\r
-\r
-```html\r
-<webview src="http://www.google.com/" nodeintegration></webview>\r
-```\r
-\r
-If "on", the guest page in `webview` will have node integration and can use node\r
-APIs like `require` and `process` to access low level system resources.\r
-\r
-### `plugins`\r
-\r
-```html\r
-<webview src="https://www.github.com/" plugins></webview>\r
-```\r
-\r
-If "on", the guest page in `webview` will be able to use browser plugins.\r
-\r
-### `preload`\r
-\r
-```html\r
-<webview src="https://www.github.com/" preload="./test.js"></webview>\r
-```\r
-\r
-Specifies a script that will be loaded before other scripts run in the guest\r
-page. The protocol of script's URL must be either `file:` or `asar:`, because it\r
-will be loaded by `require` in guest page under the hood.\r
-\r
-When the guest page doesn't have node integration this script will still have\r
-access to all Node APIs, but global objects injected by Node will be deleted\r
-after this script has finished executing.\r
-\r
-### `httpreferrer`\r
-\r
-```html\r
-<webview src="https://www.github.com/" httpreferrer="http://cheng.guru"></webview>\r
-```\r
-\r
-Sets the referrer URL for the guest page.\r
-\r
-### `useragent`\r
-\r
-```html\r
-<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>\r
-```\r
-\r
-Sets the user agent for the guest page before the page is navigated to. Once the\r
-page is loaded, use the `setUserAgent` method to change the user agent.\r
-\r
-### `disablewebsecurity`\r
-\r
-```html\r
-<webview src="https://www.github.com/" disablewebsecurity></webview>\r
-```\r
-\r
-If "on", the guest page will have web security disabled.\r
-\r
-### `partition`\r
-\r
-```html\r
-<webview src="https://github.com" partition="persist:github"></webview>\r
-<webview src="http://electron.atom.io" partition="electron"></webview>\r
-```\r
-\r
-Sets the session used by the page. If `partition` starts with `persist:`, the\r
-page will use a persistent session available to all pages in the app with the\r
-same `partition`. if there is no `persist:` prefix, the page will use an\r
-in-memory session. By assigning the same `partition`, multiple pages can share\r
-the same session. If the `partition` is unset then default session of the app\r
-will be used.\r
-\r
-This value can only be modified before the first navigation, since the session\r
-of an active renderer process cannot change. Subsequent attempts to modify the\r
-value will fail with a DOM exception.\r
-\r
-### `allowpopups`\r
-\r
-```html\r
-<webview src="https://www.github.com/" allowpopups></webview>\r
-```\r
-\r
-If "on", the guest page will be allowed to open new windows.\r
-\r
-### `blinkfeatures`\r
-\r
-```html\r
-<webview src="https://www.github.com/" blinkfeatures="PreciseMemoryInfo, CSSVariables"></webview>\r
-```\r
-\r
-A list of strings which specifies the blink features to be enabled separated by `,`.\r
-The full list of supported feature strings can be found in the\r
-[RuntimeEnabledFeatures.in][blink-feature-string] file.\r
-\r
-### `disableblinkfeatures`\r
-\r
-```html\r
-<webview src="https://www.github.com/" disableblinkfeatures="PreciseMemoryInfo, CSSVariables"></webview>\r
-```\r
-\r
-A list of strings which specifies the blink features to be disabled separated by `,`.\r
-The full list of supported feature strings can be found in the\r
-[RuntimeEnabledFeatures.in][blink-feature-string] file.\r
-\r
-## Methods\r
-\r
-The `webview` tag has the following methods:\r
-\r
-**Note:** The webview element must be loaded before using the methods.\r
-\r
-**Example**\r
-\r
-```javascript\r
-const webview = document.getElementById('foo')\r
-webview.addEventListener('dom-ready', () => {\r
- webview.openDevTools()\r
-})\r
-```\r
-\r
-### `<webview>.loadURL(url[, options])`\r
-\r
-* `url` URL\r
-* `options` Object (optional)\r
- * `httpReferrer` String - A HTTP Referrer url.\r
- * `userAgent` String - A user agent originating the request.\r
- * `extraHeaders` String - Extra headers separated by "\n"\r
-\r
-Loads the `url` in the webview, the `url` must contain the protocol prefix,\r
-e.g. the `http://` or `file://`.\r
-\r
-### `<webview>.getURL()`\r
-\r
-Returns URL of guest page.\r
-\r
-### `<webview>.getTitle()`\r
-\r
-Returns the title of guest page.\r
-\r
-### `<webview>.isLoading()`\r
-\r
-Returns a boolean whether guest page is still loading resources.\r
-\r
-### `<webview>.isWaitingForResponse()`\r
-\r
-Returns a boolean whether the guest page is waiting for a first-response for the\r
-main resource of the page.\r
-\r
-### `<webview>.stop()`\r
-\r
-Stops any pending navigation.\r
-\r
-### `<webview>.reload()`\r
-\r
-Reloads the guest page.\r
-\r
-### `<webview>.reloadIgnoringCache()`\r
-\r
-Reloads the guest page and ignores cache.\r
-\r
-### `<webview>.canGoBack()`\r
-\r
-Returns a boolean whether the guest page can go back.\r
-\r
-### `<webview>.canGoForward()`\r
-\r
-Returns a boolean whether the guest page can go forward.\r
-\r
-### `<webview>.canGoToOffset(offset)`\r
-\r
-* `offset` Integer\r
-\r
-Returns a boolean whether the guest page can go to `offset`.\r
-\r
-### `<webview>.clearHistory()`\r
-\r
-Clears the navigation history.\r
-\r
-### `<webview>.goBack()`\r
-\r
-Makes the guest page go back.\r
-\r
-### `<webview>.goForward()`\r
-\r
-Makes the guest page go forward.\r
-\r
-### `<webview>.goToIndex(index)`\r
-\r
-* `index` Integer\r
-\r
-Navigates to the specified absolute index.\r
-\r
-### `<webview>.goToOffset(offset)`\r
-\r
-* `offset` Integer\r
-\r
-Navigates to the specified offset from the "current entry".\r
-\r
-### `<webview>.isCrashed()`\r
-\r
-Whether the renderer process has crashed.\r
-\r
-### `<webview>.setUserAgent(userAgent)`\r
-\r
-* `userAgent` String\r
-\r
-Overrides the user agent for the guest page.\r
-\r
-### `<webview>.getUserAgent()`\r
-\r
-Returns a `String` representing the user agent for guest page.\r
-\r
-### `<webview>.insertCSS(css)`\r
-\r
-* `css` String\r
-\r
-Injects CSS into the guest page.\r
-\r
-### `<webview>.executeJavaScript(code, userGesture, callback)`\r
-\r
-* `code` String\r
-* `userGesture` Boolean - Default `false`.\r
-* `callback` Function (optional) - Called after script has been executed.\r
- * `result`\r
-\r
-Evaluates `code` in page. If `userGesture` is set, it will create the user\r
-gesture context in the page. HTML APIs like `requestFullScreen`, which require\r
-user action, can take advantage of this option for automation.\r
-\r
-### `<webview>.openDevTools()`\r
-\r
-Opens a DevTools window for guest page.\r
-\r
-### `<webview>.closeDevTools()`\r
-\r
-Closes the DevTools window of guest page.\r
-\r
-### `<webview>.isDevToolsOpened()`\r
-\r
-Returns a boolean whether guest page has a DevTools window attached.\r
-\r
-### `<webview>.isDevToolsFocused()`\r
-\r
-Returns a boolean whether DevTools window of guest page is focused.\r
-\r
-### `<webview>.inspectElement(x, y)`\r
-\r
-* `x` Integer\r
-* `y` Integer\r
-\r
-Starts inspecting element at position (`x`, `y`) of guest page.\r
-\r
-### `<webview>.inspectServiceWorker()`\r
-\r
-Opens the DevTools for the service worker context present in the guest page.\r
-\r
-### `<webview>.setAudioMuted(muted)`\r
-\r
-* `muted` Boolean\r
-\r
-Set guest page muted.\r
-\r
-### `<webview>.isAudioMuted()`\r
-\r
-Returns whether guest page has been muted.\r
-\r
-### `<webview>.undo()`\r
-\r
-Executes editing command `undo` in page.\r
-\r
-### `<webview>.redo()`\r
-\r
-Executes editing command `redo` in page.\r
-\r
-### `<webview>.cut()`\r
-\r
-Executes editing command `cut` in page.\r
-\r
-### `<webview>.copy()`\r
-\r
-Executes editing command `copy` in page.\r
-\r
-### `<webview>.paste()`\r
-\r
-Executes editing command `paste` in page.\r
-\r
-### `<webview>.pasteAndMatchStyle()`\r
-\r
-Executes editing command `pasteAndMatchStyle` in page.\r
-\r
-### `<webview>.delete()`\r
-\r
-Executes editing command `delete` in page.\r
-\r
-### `<webview>.selectAll()`\r
-\r
-Executes editing command `selectAll` in page.\r
-\r
-### `<webview>.unselect()`\r
-\r
-Executes editing command `unselect` in page.\r
-\r
-### `<webview>.replace(text)`\r
-\r
-* `text` String\r
-\r
-Executes editing command `replace` in page.\r
-\r
-### `<webview>.replaceMisspelling(text)`\r
-\r
-* `text` String\r
-\r
-Executes editing command `replaceMisspelling` in page.\r
-\r
-### `<webview>.insertText(text)`\r
-\r
-* `text` String\r
-\r
-Inserts `text` to the focused element.\r
-\r
-### `<webview>.findInPage(text[, options])`\r
-\r
-* `text` String - Content to be searched, must not be empty.\r
-* `options` Object (optional)\r
- * `forward` Boolean - Whether to search forward or backward, defaults to `true`.\r
- * `findNext` Boolean - Whether the operation is first request or a follow up,\r
- defaults to `false`.\r
- * `matchCase` Boolean - Whether search should be case-sensitive,\r
- defaults to `false`.\r
- * `wordStart` Boolean - Whether to look only at the start of words.\r
- defaults to `false`.\r
- * `medialCapitalAsWordStart` Boolean - When combined with `wordStart`,\r
- accepts a match in the middle of a word if the match begins with an\r
- uppercase letter followed by a lowercase or non-letter.\r
- Accepts several other intra-word matches, defaults to `false`.\r
-\r
-Starts a request to find all matches for the `text` in the web page and returns an `Integer`\r
-representing the request id used for the request. The result of the request can be\r
-obtained by subscribing to [`found-in-page`](web-view-tag.md#event-found-in-page) event.\r
-\r
-### `<webview>.stopFindInPage(action)`\r
-\r
-* `action` String - Specifies the action to take place when ending\r
- [`<webview>.findInPage`](web-view-tag.md#webviewtagfindinpage) request.\r
- * `clearSelection` - Clear the selection.\r
- * `keepSelection` - Translate the selection into a normal selection.\r
- * `activateSelection` - Focus and click the selection node.\r
-\r
-Stops any `findInPage` request for the `webview` with the provided `action`.\r
-\r
-### `<webview>.print([options])`\r
-\r
-Prints `webview`'s web page. Same as `webContents.print([options])`.\r
-\r
-### `<webview>.printToPDF(options, callback)`\r
-\r
-Prints `webview`'s web page as PDF, Same as `webContents.printToPDF(options, callback)`.\r
-\r
-### `<webview>.capturePage([rect, ]callback)`\r
-\r
-Captures a snapshot of the `webview`'s page. Same as `webContents.capturePage([rect, ]callback)`.\r
-\r
-### `<webview>.send(channel[, arg1][, arg2][, ...])`\r
-\r
-* `channel` String\r
-* `arg` (optional)\r
-\r
-Send an asynchronous message to renderer process via `channel`, you can also\r
-send arbitrary arguments. The renderer process can handle the message by\r
-listening to the `channel` event with the `ipcRenderer` module.\r
-\r
-See [webContents.send](web-contents.md#webcontentssendchannel-args) for\r
-examples.\r
-\r
-### `<webview>.sendInputEvent(event)`\r
-\r
-* `event` Object\r
-\r
-Sends an input `event` to the page.\r
-\r
-See [webContents.sendInputEvent](web-contents.md#webcontentssendinputeventevent)\r
-for detailed description of `event` object.\r
-\r
-### `<webview>.showDefinitionForSelection()` _macOS_\r
-\r
-Shows pop-up dictionary that searches the selected word on the page.\r
-\r
-### `<webview>.getWebContents()`\r
-\r
-Returns the [WebContents](web-contents.md) associated with this `webview`.\r
-\r
-## DOM events\r
-\r
-The following DOM events are available to the `webview` tag:\r
-\r
-### Event: 'load-commit'\r
-\r
-Returns:\r
-\r
-* `url` String\r
-* `isMainFrame` Boolean\r
-\r
-Fired when a load has committed. This includes navigation within the current\r
-document as well as subframe document-level loads, but does not include\r
-asynchronous resource loads.\r
-\r
-### Event: 'did-finish-load'\r
-\r
-Fired when the navigation is done, i.e. the spinner of the tab will stop\r
-spinning, and the `onload` event is dispatched.\r
-\r
-### Event: 'did-fail-load'\r
-\r
-Returns:\r
-\r
-* `errorCode` Integer\r
-* `errorDescription` String\r
-* `validatedURL` String\r
-* `isMainFrame` Boolean\r
-\r
-This event is like `did-finish-load`, but fired when the load failed or was\r
-cancelled, e.g. `window.stop()` is invoked.\r
-\r
-### Event: 'did-frame-finish-load'\r
-\r
-Returns:\r
-\r
-* `isMainFrame` Boolean\r
-\r
-Fired when a frame has done navigation.\r
-\r
-### Event: 'did-start-loading'\r
-\r
-Corresponds to the points in time when the spinner of the tab starts spinning.\r
-\r
-### Event: 'did-stop-loading'\r
-\r
-Corresponds to the points in time when the spinner of the tab stops spinning.\r
-\r
-### Event: 'did-get-response-details'\r
-\r
-Returns:\r
-\r
-* `status` Boolean\r
-* `newURL` String\r
-* `originalURL` String\r
-* `httpResponseCode` Integer\r
-* `requestMethod` String\r
-* `referrer` String\r
-* `headers` Object\r
-* `resourceType` String\r
-\r
-Fired when details regarding a requested resource is available.\r
-`status` indicates socket connection to download the resource.\r
-\r
-### Event: 'did-get-redirect-request'\r
-\r
-Returns:\r
-\r
-* `oldURL` String\r
-* `newURL` String\r
-* `isMainFrame` Boolean\r
-\r
-Fired when a redirect was received while requesting a resource.\r
-\r
-### Event: 'dom-ready'\r
-\r
-Fired when document in the given frame is loaded.\r
-\r
-### Event: 'page-title-updated'\r
-\r
-Returns:\r
-\r
-* `title` String\r
-* `explicitSet` Boolean\r
-\r
-Fired when page title is set during navigation. `explicitSet` is false when\r
-title is synthesized from file url.\r
-\r
-### Event: 'page-favicon-updated'\r
-\r
-Returns:\r
-\r
-* `favicons` Array - Array of URLs.\r
-\r
-Fired when page receives favicon urls.\r
-\r
-### Event: 'enter-html-full-screen'\r
-\r
-Fired when page enters fullscreen triggered by HTML API.\r
-\r
-### Event: 'leave-html-full-screen'\r
-\r
-Fired when page leaves fullscreen triggered by HTML API.\r
-\r
-### Event: 'console-message'\r
-\r
-Returns:\r
-\r
-* `level` Integer\r
-* `message` String\r
-* `line` Integer\r
-* `sourceId` String\r
-\r
-Fired when the guest window logs a console message.\r
-\r
-The following example code forwards all log messages to the embedder's console\r
-without regard for log level or other properties.\r
-\r
-```javascript\r
-const webview = document.getElementById('foo')\r
-webview.addEventListener('console-message', (e) => {\r
- console.log('Guest page logged a message:', e.message)\r
-})\r
-```\r
-\r
-### Event: 'found-in-page'\r
-\r
-Returns:\r
-\r
-* `result` Object\r
- * `requestId` Integer\r
- * `finalUpdate` Boolean - Indicates if more responses are to follow.\r
- * `activeMatchOrdinal` Integer (optional) - Position of the active match.\r
- * `matches` Integer (optional) - Number of Matches.\r
- * `selectionArea` Object (optional) - Coordinates of first match region.\r
-\r
-Fired when a result is available for\r
-[`webview.findInPage`](web-view-tag.md#webviewtagfindinpage) request.\r
-\r
-```javascript\r
-const webview = document.getElementById('foo')\r
-webview.addEventListener('found-in-page', (e) => {\r
- if (e.result.finalUpdate) webview.stopFindInPage('keepSelection')\r
-})\r
-\r
-const requestId = webview.findInPage('test')\r
-console.log(requestId)\r
-```\r
-\r
-### Event: 'new-window'\r
-\r
-Returns:\r
-\r
-* `url` String\r
-* `frameName` String\r
-* `disposition` String - Can be `default`, `foreground-tab`, `background-tab`,\r
- `new-window` and `other`.\r
-* `options` Object - The options which should be used for creating the new\r
- `BrowserWindow`.\r
-\r
-Fired when the guest page attempts to open a new browser window.\r
-\r
-The following example code opens the new url in system's default browser.\r
-\r
-```javascript\r
-const {shell} = require('electron')\r
-const webview = document.getElementById('foo')\r
-\r
-webview.addEventListener('new-window', (e) => {\r
- const protocol = require('url').parse(e.url).protocol\r
- if (protocol === 'http:' || protocol === 'https:') {\r
- shell.openExternal(e.url)\r
- }\r
-})\r
-```\r
-\r
-### Event: 'will-navigate'\r
-\r
-Returns:\r
-\r
-* `url` String\r
-\r
-Emitted when a user or the page wants to start navigation. It can happen when\r
-the `window.location` object is changed or a user clicks a link in the page.\r
-\r
-This event will not emit when the navigation is started programmatically with\r
-APIs like `<webview>.loadURL` and `<webview>.back`.\r
-\r
-It is also not emitted during in-page navigation, such as clicking anchor links\r
-or updating the `window.location.hash`. Use `did-navigate-in-page` event for\r
-this purpose.\r
-\r
-Calling `event.preventDefault()` does __NOT__ have any effect.\r
-\r
-### Event: 'did-navigate'\r
-\r
-Returns:\r
-\r
-* `url` String\r
-\r
-Emitted when a navigation is done.\r
-\r
-This event is not emitted for in-page navigations, such as clicking anchor links\r
-or updating the `window.location.hash`. Use `did-navigate-in-page` event for\r
-this purpose.\r
-\r
-### Event: 'did-navigate-in-page'\r
-\r
-Returns:\r
-\r
-* `isMainPage` Boolean\r
-* `url` String\r
-\r
-Emitted when an in-page navigation happened.\r
-\r
-When in-page navigation happens, the page URL changes but does not cause\r
-navigation outside of the page. Examples of this occurring are when anchor links\r
-are clicked or when the DOM `hashchange` event is triggered.\r
-\r
-### Event: 'close'\r
-\r
-Fired when the guest page attempts to close itself.\r
-\r
-The following example code navigates the `webview` to `about:blank` when the\r
-guest attempts to close itself.\r
-\r
-```javascript\r
-const webview = document.getElementById('foo')\r
-webview.addEventListener('close', () => {\r
- webview.src = 'about:blank'\r
-})\r
-```\r
-\r
-### Event: 'ipc-message'\r
-\r
-Returns:\r
-\r
-* `channel` String\r
-* `args` Array\r
-\r
-Fired when the guest page has sent an asynchronous message to embedder page.\r
-\r
-With `sendToHost` method and `ipc-message` event you can easily communicate\r
-between guest page and embedder page:\r
-\r
-```javascript\r
-// In embedder page.\r
-const webview = document.getElementById('foo')\r
-webview.addEventListener('ipc-message', (event) => {\r
- console.log(event.channel)\r
- // Prints "pong"\r
-})\r
-webview.send('ping')\r
-```\r
-\r
-```javascript\r
-// In guest page.\r
-const {ipcRenderer} = require('electron')\r
-ipcRenderer.on('ping', () => {\r
- ipcRenderer.sendToHost('pong')\r
-})\r
-```\r
-\r
-### Event: 'crashed'\r
-\r
-Fired when the renderer process is crashed.\r
-\r
-### Event: 'gpu-crashed'\r
-\r
-Fired when the gpu process is crashed.\r
-\r
-### Event: 'plugin-crashed'\r
-\r
-Returns:\r
-\r
-* `name` String\r
-* `version` String\r
-\r
-Fired when a plugin process is crashed.\r
-\r
-### Event: 'destroyed'\r
-\r
-Fired when the WebContents is destroyed.\r
-\r
-### Event: 'media-started-playing'\r
-\r
-Emitted when media starts playing.\r
-\r
-### Event: 'media-paused'\r
-\r
-Emitted when media is paused or done playing.\r
-\r
-### Event: 'did-change-theme-color'\r
-\r
-Returns:\r
-\r
-* `themeColor` String\r
-\r
-Emitted when a page's theme color changes. This is usually due to encountering a meta tag:\r
-\r
-```html\r
-<meta name='theme-color' content='#ff0000'>\r
-```\r
-\r
-### Event: 'update-target-url'\r
-\r
-Returns:\r
-\r
-* `url` String\r
-\r
-Emitted when mouse moves over a link or the keyboard moves the focus to a link.\r
-\r
-### Event: 'devtools-opened'\r
-\r
-Emitted when DevTools is opened.\r
-\r
-### Event: 'devtools-closed'\r
-\r
-Emitted when DevTools is closed.\r
-\r
-### Event: 'devtools-focused'\r
-\r
-Emitted when DevTools is focused / opened.\r
-\r
-[blink-feature-string]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/RuntimeEnabledFeatures.in\r
+# `<webview>` Tag
+
+> Display external web content in an isolated frame and process.
+
+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 embedded page within your app controls how the guest content is laid out and
+rendered.
+
+Unlike 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.
+
+For security purposes, `webview` can only be used in `BrowserWindow`s that have
+`nodeIntegration` enabled.
+
+## 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="display:inline-flex; 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 = () => {
+ const webview = document.getElementById('foo')
+ const indicator = document.querySelector('.indicator')
+
+ const loadstart = () => {
+ indicator.innerText = 'loading...'
+ }
+
+ const loadstop = () => {
+ indicator.innerText = ''
+ }
+
+ webview.addEventListener('did-start-loading', loadstart)
+ webview.addEventListener('did-stop-loading', loadstop)
+ }
+</script>
+```
+
+## CSS Styling Notes
+
+Please note that the `webview` tag's style uses `display:flex;` internally to
+ensure the child `object` element fills the full height and width of its `webview`
+container when used with traditional and flexbox layouts (since v0.36.11). Please
+do not overwrite the default `display:flex;` CSS property, unless specifying
+`display:inline-flex;` for inline layout.
+
+`webview` has issues being hidden using the `hidden` attribute or using `display: none;`.
+It can cause unusual rendering behaviour within its child `browserplugin` object
+and the web page is reloaded, when the `webview` is un-hidden, as opposed to just
+becoming visible again. The recommended approach is to hide the `webview` using
+CSS by zeroing the `width` & `height` and allowing the element to shrink to the 0px
+dimensions via `flex`.
+
+```html
+<style>
+ webview {
+ display:inline-flex;
+ width:640px;
+ height:480px;
+ }
+ webview.hide {
+ flex: 0 1;
+ width: 0px;
+ height: 0px;
+ }
+</style>
+```
+
+## Tag Attributes
+
+The `webview` tag has the following attributes:
+
+### `src`
+
+```html
+<webview src="https://www.github.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="https://www.github.com/" autosize="on" minwidth="576" minheight="432"></webview>
+```
+
+If "on", the `webview` container will automatically resize within the
+bounds specified by the attributes `minwidth`, `minheight`, `maxwidth`, and
+`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`
+
+```html
+<webview src="http://www.google.com/" nodeintegration></webview>
+```
+
+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`
+
+```html
+<webview src="https://www.github.com/" plugins></webview>
+```
+
+If "on", the guest page in `webview` will be able to use browser plugins.
+
+### `preload`
+
+```html
+<webview src="https://www.github.com/" preload="./test.js"></webview>
+```
+
+Specifies a script that will be loaded before other scripts run in the guest
+page. The protocol of script's URL must be either `file:` or `asar:`, because it
+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 finished executing.
+
+### `httpreferrer`
+
+```html
+<webview src="https://www.github.com/" httpreferrer="http://cheng.guru"></webview>
+```
+
+Sets the referrer URL for the guest page.
+
+### `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.
+
+### `disablewebsecurity`
+
+```html
+<webview src="https://www.github.com/" disablewebsecurity></webview>
+```
+
+If "on", the guest page will have web security disabled.
+
+### `partition`
+
+```html
+<webview src="https://github.com" partition="persist:github"></webview>
+<webview src="http://electron.atom.io" partition="electron"></webview>
+```
+
+Sets the session used by the page. If `partition` starts with `persist:`, the
+page will use a persistent session available to all pages in the app with the
+same `partition`. if there is no `persist:` prefix, the page will use an
+in-memory session. By assigning the same `partition`, multiple pages can share
+the same session. If the `partition` is unset then default session of the app
+will be used.
+
+This value can only be modified before the first navigation, since the session
+of an active renderer process cannot change. Subsequent attempts to modify the
+value will fail with a DOM exception.
+
+### `allowpopups`
+
+```html
+<webview src="https://www.github.com/" allowpopups></webview>
+```
+
+If "on", the guest page will be allowed to open new windows.
+
+### `blinkfeatures`
+
+```html
+<webview src="https://www.github.com/" blinkfeatures="PreciseMemoryInfo, CSSVariables"></webview>
+```
+
+A list of strings which specifies the blink features to be enabled separated by `,`.
+The full list of supported feature strings can be found in the
+[RuntimeEnabledFeatures.in][blink-feature-string] file.
+
+### `disableblinkfeatures`
+
+```html
+<webview src="https://www.github.com/" disableblinkfeatures="PreciseMemoryInfo, CSSVariables"></webview>
+```
+
+A list of strings which specifies the blink features to be disabled separated by `,`.
+The full list of supported feature strings can be found in the
+[RuntimeEnabledFeatures.in][blink-feature-string] file.
+
+## Methods
+
+The `webview` tag has the following methods:
+
+**Note:** The webview element must be loaded before using the methods.
+
+**Example**
+
+```javascript
+const webview = document.getElementById('foo')
+webview.addEventListener('dom-ready', () => {
+ webview.openDevTools()
+})
+```
+
+### `<webview>.loadURL(url[, options])`
+
+* `url` URL
+* `options` Object (optional)
+ * `httpReferrer` String - A HTTP Referrer url.
+ * `userAgent` String - A user agent originating the request.
+ * `extraHeaders` String - Extra headers separated by "\n"
+
+Loads the `url` in the webview, the `url` must contain the protocol prefix,
+e.g. the `http://` or `file://`.
+
+### `<webview>.getURL()`
+
+Returns URL of guest page.
+
+### `<webview>.getTitle()`
+
+Returns the title of guest page.
+
+### `<webview>.isLoading()`
+
+Returns a boolean whether guest page is still loading resources.
+
+### `<webview>.isWaitingForResponse()`
+
+Returns a boolean whether the guest page is waiting for a first-response for the
+main resource of the page.
+
+### `<webview>.stop()`
+
+Stops any pending navigation.
+
+### `<webview>.reload()`
+
+Reloads the guest page.
+
+### `<webview>.reloadIgnoringCache()`
+
+Reloads the guest page and ignores cache.
+
+### `<webview>.canGoBack()`
+
+Returns a boolean whether the guest page can go back.
+
+### `<webview>.canGoForward()`
+
+Returns a boolean whether the guest page can go forward.
+
+### `<webview>.canGoToOffset(offset)`
+
+* `offset` Integer
+
+Returns a boolean whether the guest page can go to `offset`.
+
+### `<webview>.clearHistory()`
+
+Clears the navigation history.
+
+### `<webview>.goBack()`
+
+Makes the guest page go back.
+
+### `<webview>.goForward()`
+
+Makes the 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 the guest page.
+
+### `<webview>.getUserAgent()`
+
+Returns a `String` representing the user agent for guest page.
+
+### `<webview>.insertCSS(css)`
+
+* `css` String
+
+Injects CSS into the guest page.
+
+### `<webview>.executeJavaScript(code, userGesture, callback)`
+
+* `code` String
+* `userGesture` Boolean - Default `false`.
+* `callback` Function (optional) - Called after script has been executed.
+ * `result`
+
+Evaluates `code` in page. If `userGesture` is set, it will create the user
+gesture context in the page. HTML APIs like `requestFullScreen`, which require
+user action, can take advantage of this option for automation.
+
+### `<webview>.openDevTools()`
+
+Opens a DevTools window for guest page.
+
+### `<webview>.closeDevTools()`
+
+Closes the DevTools window of guest page.
+
+### `<webview>.isDevToolsOpened()`
+
+Returns a boolean whether guest page has a DevTools window attached.
+
+### `<webview>.isDevToolsFocused()`
+
+Returns a boolean whether DevTools window of guest page is focused.
+
+### `<webview>.inspectElement(x, y)`
+
+* `x` Integer
+* `y` Integer
+
+Starts inspecting element at position (`x`, `y`) of guest page.
+
+### `<webview>.inspectServiceWorker()`
+
+Opens the DevTools for the service worker context present in the guest page.
+
+### `<webview>.setAudioMuted(muted)`
+
+* `muted` Boolean
+
+Set guest page muted.
+
+### `<webview>.isAudioMuted()`
+
+Returns whether guest page has been muted.
+
+### `<webview>.undo()`
+
+Executes editing command `undo` in page.
+
+### `<webview>.redo()`
+
+Executes editing command `redo` in page.
+
+### `<webview>.cut()`
+
+Executes editing command `cut` in page.
+
+### `<webview>.copy()`
+
+Executes editing command `copy` in page.
+
+### `<webview>.paste()`
+
+Executes editing command `paste` in page.
+
+### `<webview>.pasteAndMatchStyle()`
+
+Executes editing command `pasteAndMatchStyle` in page.
+
+### `<webview>.delete()`
+
+Executes editing command `delete` in page.
+
+### `<webview>.selectAll()`
+
+Executes editing command `selectAll` in page.
+
+### `<webview>.unselect()`
+
+Executes editing command `unselect` in page.
+
+### `<webview>.replace(text)`
+
+* `text` String
+
+Executes editing command `replace` in page.
+
+### `<webview>.replaceMisspelling(text)`
+
+* `text` String
+
+Executes editing command `replaceMisspelling` in page.
+
+### `<webview>.insertText(text)`
+
+* `text` String
+
+Inserts `text` to the focused element.
+
+### `<webview>.findInPage(text[, options])`
+
+* `text` String - Content to be searched, must not be empty.
+* `options` Object (optional)
+ * `forward` Boolean - Whether to search forward or backward, defaults to `true`.
+ * `findNext` Boolean - Whether the operation is first request or a follow up,
+ defaults to `false`.
+ * `matchCase` Boolean - Whether search should be case-sensitive,
+ defaults to `false`.
+ * `wordStart` Boolean - Whether to look only at the start of words.
+ defaults to `false`.
+ * `medialCapitalAsWordStart` Boolean - When combined with `wordStart`,
+ accepts a match in the middle of a word if the match begins with an
+ uppercase letter followed by a lowercase or non-letter.
+ Accepts several other intra-word matches, defaults to `false`.
+
+Starts a request to find all matches for the `text` in the web page and returns an `Integer`
+representing the request id used for the request. The result of the request can be
+obtained by subscribing to [`found-in-page`](web-view-tag.md#event-found-in-page) event.
+
+### `<webview>.stopFindInPage(action)`
+
+* `action` String - Specifies the action to take place when ending
+ [`<webview>.findInPage`](web-view-tag.md#webviewtagfindinpage) request.
+ * `clearSelection` - Clear the selection.
+ * `keepSelection` - Translate the selection into a normal selection.
+ * `activateSelection` - Focus and click the selection node.
+
+Stops any `findInPage` request for the `webview` with the provided `action`.
+
+### `<webview>.print([options])`
+
+Prints `webview`'s web page. Same as `webContents.print([options])`.
+
+### `<webview>.printToPDF(options, callback)`
+
+Prints `webview`'s web page as PDF, Same as `webContents.printToPDF(options, callback)`.
+
+### `<webview>.capturePage([rect, ]callback)`
+
+Captures a snapshot of the `webview`'s page. Same as `webContents.capturePage([rect, ]callback)`.
+
+### `<webview>.send(channel[, arg1][, arg2][, ...])`
+
+* `channel` String
+* `arg` (optional)
+
+Send an asynchronous message to renderer process via `channel`, you can also
+send arbitrary arguments. The renderer process can handle the message by
+listening to the `channel` event with the `ipcRenderer` module.
+
+See [webContents.send](web-contents.md#webcontentssendchannel-args) for
+examples.
+
+### `<webview>.sendInputEvent(event)`
+
+* `event` Object
+
+Sends an input `event` to the page.
+
+See [webContents.sendInputEvent](web-contents.md#webcontentssendinputeventevent)
+for detailed description of `event` object.
+
+### `<webview>.showDefinitionForSelection()` _macOS_
+
+Shows pop-up dictionary that searches the selected word on the page.
+
+### `<webview>.getWebContents()`
+
+Returns the [WebContents](web-contents.md) associated with this `webview`.
+
+## DOM events
+
+The following DOM events are available to the `webview` tag:
+
+### Event: 'load-commit'
+
+Returns:
+
+* `url` String
+* `isMainFrame` Boolean
+
+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.
+
+### Event: 'did-finish-load'
+
+Fired when the navigation is done, i.e. the spinner of the tab will stop
+spinning, and the `onload` event is dispatched.
+
+### Event: 'did-fail-load'
+
+Returns:
+
+* `errorCode` Integer
+* `errorDescription` String
+* `validatedURL` String
+* `isMainFrame` Boolean
+
+This event is like `did-finish-load`, but fired when the load failed or was
+cancelled, e.g. `window.stop()` is invoked.
+
+### Event: 'did-frame-finish-load'
+
+Returns:
+
+* `isMainFrame` Boolean
+
+Fired when a frame has done navigation.
+
+### Event: 'did-start-loading'
+
+Corresponds to the points in time when the spinner of the tab starts spinning.
+
+### Event: 'did-stop-loading'
+
+Corresponds to the points in time when the spinner of the tab stops spinning.
+
+### Event: 'did-get-response-details'
+
+Returns:
+
+* `status` Boolean
+* `newURL` String
+* `originalURL` String
+* `httpResponseCode` Integer
+* `requestMethod` String
+* `referrer` String
+* `headers` Object
+* `resourceType` String
+
+Fired when details regarding a requested resource is available.
+`status` indicates socket connection to download the resource.
+
+### Event: 'did-get-redirect-request'
+
+Returns:
+
+* `oldURL` String
+* `newURL` String
+* `isMainFrame` Boolean
+
+Fired when a redirect was received while requesting a resource.
+
+### Event: 'dom-ready'
+
+Fired when document in the given frame is loaded.
+
+### Event: 'page-title-updated'
+
+Returns:
+
+* `title` String
+* `explicitSet` Boolean
+
+Fired when page title is set during navigation. `explicitSet` is false when
+title is synthesized from file url.
+
+### Event: 'page-favicon-updated'
+
+Returns:
+
+* `favicons` Array - Array of URLs.
+
+Fired when page receives favicon urls.
+
+### Event: 'enter-html-full-screen'
+
+Fired when page enters fullscreen triggered by HTML API.
+
+### Event: 'leave-html-full-screen'
+
+Fired when page leaves fullscreen triggered by HTML API.
+
+### Event: 'console-message'
+
+Returns:
+
+* `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
+const webview = document.getElementById('foo')
+webview.addEventListener('console-message', (e) => {
+ console.log('Guest page logged a message:', e.message)
+})
+```
+
+### Event: 'found-in-page'
+
+Returns:
+
+* `result` Object
+ * `requestId` Integer
+ * `finalUpdate` Boolean - Indicates if more responses are to follow.
+ * `activeMatchOrdinal` Integer (optional) - Position of the active match.
+ * `matches` Integer (optional) - Number of Matches.
+ * `selectionArea` Object (optional) - Coordinates of first match region.
+
+Fired when a result is available for
+[`webview.findInPage`](web-view-tag.md#webviewtagfindinpage) request.
+
+```javascript
+const webview = document.getElementById('foo')
+webview.addEventListener('found-in-page', (e) => {
+ if (e.result.finalUpdate) webview.stopFindInPage('keepSelection')
+})
+
+const requestId = webview.findInPage('test')
+console.log(requestId)
+```
+
+### Event: 'new-window'
+
+Returns:
+
+* `url` String
+* `frameName` String
+* `disposition` String - Can be `default`, `foreground-tab`, `background-tab`,
+ `new-window` and `other`.
+* `options` Object - The options which should be used for creating the new
+ `BrowserWindow`.
+
+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
+const {shell} = require('electron')
+const webview = document.getElementById('foo')
+
+webview.addEventListener('new-window', (e) => {
+ const protocol = require('url').parse(e.url).protocol
+ if (protocol === 'http:' || protocol === 'https:') {
+ shell.openExternal(e.url)
+ }
+})
+```
+
+### Event: 'will-navigate'
+
+Returns:
+
+* `url` String
+
+Emitted when a user or the page wants to start navigation. It can happen when
+the `window.location` object is changed or a user clicks a link in the page.
+
+This event will not emit when the navigation is started programmatically with
+APIs like `<webview>.loadURL` and `<webview>.back`.
+
+It is also not emitted during in-page navigation, such as clicking anchor links
+or updating the `window.location.hash`. Use `did-navigate-in-page` event for
+this purpose.
+
+Calling `event.preventDefault()` does __NOT__ have any effect.
+
+### Event: 'did-navigate'
+
+Returns:
+
+* `url` String
+
+Emitted when a navigation is done.
+
+This event is not emitted for in-page navigations, such as clicking anchor links
+or updating the `window.location.hash`. Use `did-navigate-in-page` event for
+this purpose.
+
+### Event: 'did-navigate-in-page'
+
+Returns:
+
+* `isMainFrame` Boolean
+* `url` String
+
+Emitted when an in-page navigation happened.
+
+When in-page navigation happens, the page URL changes but does not cause
+navigation outside of the page. Examples of this occurring are when anchor links
+are clicked or when the DOM `hashchange` event is triggered.
+
+### Event: 'close'
+
+Fired when the guest page attempts to close itself.
+
+The following example code navigates the `webview` to `about:blank` when the
+guest attempts to close itself.
+
+```javascript
+const webview = document.getElementById('foo')
+webview.addEventListener('close', () => {
+ webview.src = 'about:blank'
+})
+```
+
+### Event: 'ipc-message'
+
+Returns:
+
+* `channel` String
+* `args` Array
+
+Fired when the guest page has sent an asynchronous message to embedder page.
+
+With `sendToHost` method and `ipc-message` event you can easily communicate
+between guest page and embedder page:
+
+```javascript
+// In embedder page.
+const webview = document.getElementById('foo')
+webview.addEventListener('ipc-message', (event) => {
+ console.log(event.channel)
+ // Prints "pong"
+})
+webview.send('ping')
+```
+
+```javascript
+// In guest page.
+const {ipcRenderer} = require('electron')
+ipcRenderer.on('ping', () => {
+ ipcRenderer.sendToHost('pong')
+})
+```
+
+### Event: 'crashed'
+
+Fired when the renderer process is crashed.
+
+### Event: 'gpu-crashed'
+
+Fired when the gpu process is crashed.
+
+### Event: 'plugin-crashed'
+
+Returns:
+
+* `name` String
+* `version` String
+
+Fired when a plugin process is crashed.
+
+### Event: 'destroyed'
+
+Fired when the WebContents is destroyed.
+
+### Event: 'media-started-playing'
+
+Emitted when media starts playing.
+
+### Event: 'media-paused'
+
+Emitted when media is paused or done playing.
+
+### Event: 'did-change-theme-color'
+
+Returns:
+
+* `themeColor` String
+
+Emitted when a page's theme color changes. This is usually due to encountering a meta tag:
+
+```html
+<meta name='theme-color' content='#ff0000'>
+```
+
+### Event: 'update-target-url'
+
+Returns:
+
+* `url` String
+
+Emitted when mouse moves over a link or the keyboard moves the focus to a link.
+
+### Event: 'devtools-opened'
+
+Emitted when DevTools is opened.
+
+### Event: 'devtools-closed'
+
+Emitted when DevTools is closed.
+
+### Event: 'devtools-focused'
+
+Emitted when DevTools is focused / opened.
+
+[blink-feature-string]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/RuntimeEnabledFeatures.in
projects / platform / framework / web / crosswalk-tizen.git / commitdiff