diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md index eb081e48eac5..7bdb3607fc1b 100644 --- a/docs/api/web-contents.md +++ b/docs/api/web-contents.md @@ -185,7 +185,7 @@ Returns: * `event` Event * `url` String -* `isMainPage` Boolean +* `isMainFrame` Boolean Emitted when an in-page navigation happened. diff --git a/docs/api/web-view-tag.md b/docs/api/web-view-tag.md index e518ba10a7a8..0ae7b6cdf801 100644 --- a/docs/api/web-view-tag.md +++ b/docs/api/web-view-tag.md @@ -1,827 +1,827 @@ -# `` 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 - -``` - -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 - -``` - -## 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 - -``` - -## Tag Attributes - -The `webview` tag has the following attributes: - -### `src` - -```html - -``` - -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 - -``` - -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 - -``` - -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 - -``` - -If "on", the guest page in `webview` will be able to use browser plugins. - -### `preload` - -```html - -``` - -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 - -``` - -Sets the referrer URL for the guest page. - -### `useragent` - -```html - -``` - -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 - -``` - -If "on", the guest page will have web security disabled. - -### `partition` - -```html - - -``` - -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 - -``` - -If "on", the guest page will be allowed to open new windows. - -### `blinkfeatures` - -```html - -``` - -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 - -``` - -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() -}) -``` - -### `.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://`. - -### `.getURL()` - -Returns URL of guest page. - -### `.getTitle()` - -Returns the title of guest page. - -### `.isLoading()` - -Returns a boolean whether guest page is still loading resources. - -### `.isWaitingForResponse()` - -Returns a boolean whether the guest page is waiting for a first-response for the -main resource of the page. - -### `.stop()` - -Stops any pending navigation. - -### `.reload()` - -Reloads the guest page. - -### `.reloadIgnoringCache()` - -Reloads the guest page and ignores cache. - -### `.canGoBack()` - -Returns a boolean whether the guest page can go back. - -### `.canGoForward()` - -Returns a boolean whether the guest page can go forward. - -### `.canGoToOffset(offset)` - -* `offset` Integer - -Returns a boolean whether the guest page can go to `offset`. - -### `.clearHistory()` - -Clears the navigation history. - -### `.goBack()` - -Makes the guest page go back. - -### `.goForward()` - -Makes the guest page go forward. - -### `.goToIndex(index)` - -* `index` Integer - -Navigates to the specified absolute index. - -### `.goToOffset(offset)` - -* `offset` Integer - -Navigates to the specified offset from the "current entry". - -### `.isCrashed()` - -Whether the renderer process has crashed. - -### `.setUserAgent(userAgent)` - -* `userAgent` String - -Overrides the user agent for the guest page. - -### `.getUserAgent()` - -Returns a `String` representing the user agent for guest page. - -### `.insertCSS(css)` - -* `css` String - -Injects CSS into the guest page. - -### `.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. - -### `.openDevTools()` - -Opens a DevTools window for guest page. - -### `.closeDevTools()` - -Closes the DevTools window of guest page. - -### `.isDevToolsOpened()` - -Returns a boolean whether guest page has a DevTools window attached. - -### `.isDevToolsFocused()` - -Returns a boolean whether DevTools window of guest page is focused. - -### `.inspectElement(x, y)` - -* `x` Integer -* `y` Integer - -Starts inspecting element at position (`x`, `y`) of guest page. - -### `.inspectServiceWorker()` - -Opens the DevTools for the service worker context present in the guest page. - -### `.setAudioMuted(muted)` - -* `muted` Boolean - -Set guest page muted. - -### `.isAudioMuted()` - -Returns whether guest page has been muted. - -### `.undo()` - -Executes editing command `undo` in page. - -### `.redo()` - -Executes editing command `redo` in page. - -### `.cut()` - -Executes editing command `cut` in page. - -### `.copy()` - -Executes editing command `copy` in page. - -### `.paste()` - -Executes editing command `paste` in page. - -### `.pasteAndMatchStyle()` - -Executes editing command `pasteAndMatchStyle` in page. - -### `.delete()` - -Executes editing command `delete` in page. - -### `.selectAll()` - -Executes editing command `selectAll` in page. - -### `.unselect()` - -Executes editing command `unselect` in page. - -### `.replace(text)` - -* `text` String - -Executes editing command `replace` in page. - -### `.replaceMisspelling(text)` - -* `text` String - -Executes editing command `replaceMisspelling` in page. - -### `.insertText(text)` - -* `text` String - -Inserts `text` to the focused element. - -### `.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. - -### `.stopFindInPage(action)` - -* `action` String - Specifies the action to take place when ending - [`.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`. - -### `.print([options])` - -Prints `webview`'s web page. Same as `webContents.print([options])`. - -### `.printToPDF(options, callback)` - -Prints `webview`'s web page as PDF, Same as `webContents.printToPDF(options, callback)`. - -### `.capturePage([rect, ]callback)` - -Captures a snapshot of the `webview`'s page. Same as `webContents.capturePage([rect, ]callback)`. - -### `.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. - -### `.sendInputEvent(event)` - -* `event` Object - -Sends an input `event` to the page. - -See [webContents.sendInputEvent](web-contents.md#webcontentssendinputeventevent) -for detailed description of `event` object. - -### `.showDefinitionForSelection()` _macOS_ - -Shows pop-up dictionary that searches the selected word on the page. - -### `.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 `.loadURL` and `.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: - -* `isMainPage` 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 - -``` - -### 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 +# `` 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 + +``` + +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 + +``` + +## 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 + +``` + +## Tag Attributes + +The `webview` tag has the following attributes: + +### `src` + +```html + +``` + +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 + +``` + +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 + +``` + +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 + +``` + +If "on", the guest page in `webview` will be able to use browser plugins. + +### `preload` + +```html + +``` + +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 + +``` + +Sets the referrer URL for the guest page. + +### `useragent` + +```html + +``` + +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 + +``` + +If "on", the guest page will have web security disabled. + +### `partition` + +```html + + +``` + +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 + +``` + +If "on", the guest page will be allowed to open new windows. + +### `blinkfeatures` + +```html + +``` + +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 + +``` + +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() +}) +``` + +### `.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://`. + +### `.getURL()` + +Returns URL of guest page. + +### `.getTitle()` + +Returns the title of guest page. + +### `.isLoading()` + +Returns a boolean whether guest page is still loading resources. + +### `.isWaitingForResponse()` + +Returns a boolean whether the guest page is waiting for a first-response for the +main resource of the page. + +### `.stop()` + +Stops any pending navigation. + +### `.reload()` + +Reloads the guest page. + +### `.reloadIgnoringCache()` + +Reloads the guest page and ignores cache. + +### `.canGoBack()` + +Returns a boolean whether the guest page can go back. + +### `.canGoForward()` + +Returns a boolean whether the guest page can go forward. + +### `.canGoToOffset(offset)` + +* `offset` Integer + +Returns a boolean whether the guest page can go to `offset`. + +### `.clearHistory()` + +Clears the navigation history. + +### `.goBack()` + +Makes the guest page go back. + +### `.goForward()` + +Makes the guest page go forward. + +### `.goToIndex(index)` + +* `index` Integer + +Navigates to the specified absolute index. + +### `.goToOffset(offset)` + +* `offset` Integer + +Navigates to the specified offset from the "current entry". + +### `.isCrashed()` + +Whether the renderer process has crashed. + +### `.setUserAgent(userAgent)` + +* `userAgent` String + +Overrides the user agent for the guest page. + +### `.getUserAgent()` + +Returns a `String` representing the user agent for guest page. + +### `.insertCSS(css)` + +* `css` String + +Injects CSS into the guest page. + +### `.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. + +### `.openDevTools()` + +Opens a DevTools window for guest page. + +### `.closeDevTools()` + +Closes the DevTools window of guest page. + +### `.isDevToolsOpened()` + +Returns a boolean whether guest page has a DevTools window attached. + +### `.isDevToolsFocused()` + +Returns a boolean whether DevTools window of guest page is focused. + +### `.inspectElement(x, y)` + +* `x` Integer +* `y` Integer + +Starts inspecting element at position (`x`, `y`) of guest page. + +### `.inspectServiceWorker()` + +Opens the DevTools for the service worker context present in the guest page. + +### `.setAudioMuted(muted)` + +* `muted` Boolean + +Set guest page muted. + +### `.isAudioMuted()` + +Returns whether guest page has been muted. + +### `.undo()` + +Executes editing command `undo` in page. + +### `.redo()` + +Executes editing command `redo` in page. + +### `.cut()` + +Executes editing command `cut` in page. + +### `.copy()` + +Executes editing command `copy` in page. + +### `.paste()` + +Executes editing command `paste` in page. + +### `.pasteAndMatchStyle()` + +Executes editing command `pasteAndMatchStyle` in page. + +### `.delete()` + +Executes editing command `delete` in page. + +### `.selectAll()` + +Executes editing command `selectAll` in page. + +### `.unselect()` + +Executes editing command `unselect` in page. + +### `.replace(text)` + +* `text` String + +Executes editing command `replace` in page. + +### `.replaceMisspelling(text)` + +* `text` String + +Executes editing command `replaceMisspelling` in page. + +### `.insertText(text)` + +* `text` String + +Inserts `text` to the focused element. + +### `.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. + +### `.stopFindInPage(action)` + +* `action` String - Specifies the action to take place when ending + [`.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`. + +### `.print([options])` + +Prints `webview`'s web page. Same as `webContents.print([options])`. + +### `.printToPDF(options, callback)` + +Prints `webview`'s web page as PDF, Same as `webContents.printToPDF(options, callback)`. + +### `.capturePage([rect, ]callback)` + +Captures a snapshot of the `webview`'s page. Same as `webContents.capturePage([rect, ]callback)`. + +### `.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. + +### `.sendInputEvent(event)` + +* `event` Object + +Sends an input `event` to the page. + +See [webContents.sendInputEvent](web-contents.md#webcontentssendinputeventevent) +for detailed description of `event` object. + +### `.showDefinitionForSelection()` _macOS_ + +Shows pop-up dictionary that searches the selected word on the page. + +### `.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 `.loadURL` and `.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 + +``` + +### 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