| Description: | Use the webview tag to actively load live content
from the web over the network and embed it in your packaged app.
Your app can control the appearance of the webview and
interact with the web content,
initiate navigations in an embedded web page,
react to error events that happen within it, and more
(see Usage).
|
| Availability: | Available in Chrome 25 or later |
| Permissions: | "webview" |
| Samples: | browser; tcpserver; webview |
| Learn more: | Embed Content; Chrome Apps Office Hours - the WebView Control |
Use the webview tag to embed 'guest' content
(such as web pages) in your packaged app.
The guest content is contained within the webview container;
an embedder page within your packaged 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 app and
all interactions between your app and embedded content will be asynchronous.
This keeps your app safe from the embedded content.
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:
<webview id="foo" src="http://www.google.com/" style="width:640px; height:480px"></webview>
Note: You can only use css styles to control the look and feel of the container, for example, the container size. You cannot use css to control the guest content itself.
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 in app.js
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:
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("loadstart", loadstart);
webview.addEventListener("loadstop", loadstop);
}
<webview id="foo" src="http://www.google.com/" style="width:640px; height:480px"></webview>
Returns the visible URL. Mirrors the logic in the browser's omnibox: either returning a pending new navigation if initiated by the embedder page, or the last committed navigation. Writing to this attribute initiates top-level navigation.
<webview id="foo" src="http://www.google.com/" style="width:640px; height:480px" partition="persist:googlepluswidgets"></webview>
Storage partition ID used by the webview tag.
If the storage partition ID starts with persist:
(partition="persist:googlepluswidgets"),
the webview will use a persistent storage partition
available to all guests in the app
with the same storage partition ID.
If the ID is unset or if there is no 'persist': prefix,
the webview will use an in-memory storage partition.
This value can only be modified before the first navigation,
since the storage partition of an active renderer process cannot change.
Subsequent attempts to modify the value will fail with a DOM exception.
By assigning the same partition ID,
multiple webviews can share the same storage partition.
Exception thrown:
The partition attribute must be valid for navigation to proceed.
In the case of an invalid partition, such as partition="persist:",
the src attribute cannot be set and an exception is thrown.
<webview id="foo" src="http://www.google.com/" style="width:640px; height:480px" autosize="on" minwidth="576" minheight="432"></webview>
If "on", the webview will fire the sizechanged event
and adjust the size of the guest content within the webview container,
provided you have written event handlers to change these dimensions.
You can also include size contraints on the guest content:
minwidth, minheight,
maxwidth, maxheight.
These contraints do not impact the webview UNLESS autosize is enabled.
When autosize is enabled, the webview content cannot be less than the minimum values
or greater than the maximum.
stop()
Stops the loading of the current webview navigation, if one is in progress.
reload()
Reloads the current top-level page.
back()
forward()
go(integer relativeIndex)
Initiates a history navigation back, forward, or to a relative index, if possible.
Includes history navigations to subframes.
The go() method has a relativeIndex parameter,
which can either be a positive integer, meaning to go forward a certain number of entries,
or negative, meaning to go back.
canGoBack()
canGoForward()
Indicates whether it is possible to go back or forward from the current state.
contentWindow.postMessage(message, targetOrigin)
Posts message (example: "Message from app to embedded page")
to the embedded web content,
as long as the embedded content is displaying a page
from the targetOrigin (example: "https://www.google.com").
This method isn't available until the page has completed loading.
Listen to the loadstop event
and then call the method.
Allows the guest to send replies and
provides the guest web page with a JavaScript reference
to the embedder page's window (via event.source).
Uses the same
HTML5 postMessage
API as between web pages.
The embedder should listen for replies
by adding a message event listener to its own frame.
The event.source corresponds to the guest frame that sent the reply.
getProcessId()
Returns Chrome's internal process ID for the guest web page's current process, allowing embedders to know how many guests would be affected by terminating the process. Two guests will share a process only if they belong to the same app and have the same storage partition ID. The call is synchronous and returns the embedder's cached notion of the current process ID. The process ID isn't the same as the operating system's process ID.
terminate()
Forcibly kills the guest web page's renderer process.
This may affect multiple webview tags in the current app
if they share the same process,
but it will not affect webview tags in other apps.
Each event handler is a function that takes in an event object.
Each event object has a name property matching the event's name,
so that one event handler function can be used to handle multiple types of events.
Event handlers are specified using
addEventListener("eventName", function).
addEventListener("loadstart", function(string url, boolean isTopLevel))
Fired when a load has begun.
addEventListener("loadabort", function(string url, boolean isTopLevel, string reason))
Fired when a top-level load has aborted without committing.
networkError, download,
canceled, sslError, safeBrowsingError.
addEventListener("loadredirect", function(string oldUrl, string newUrl, boolean isTopLevel))
Fired when a top-level load request has redirected to a different URL.
addEventListener("loadcommit", function(string url, boolean isTopLevel))
Fired when a load has committed.
addEventListener("loadstop", function)
Fired when all loads in the tag (including all subframes) have completed. Fires in addition to any loadcommit or loadabort events, which occur per-frame.
addEventListener("sizechanged", function(integer oldWidth, integer oldHeight, integer newWidth, integer newHeight))
Fired when the embedded web content has been resized. Only fires if autosize enabled.
addEventListener("exit", function(integer processID, string reason))
Fired when the process rendering the guest web content has exited.
normal, abnormal,
crash, kill.
addEventListener("unresponsive", function(integer processID))
Fired when the process rendering the guest web content has become unresponsive. This event will be generated once, with a matching responsive event if the guest begins to respond again.
addEventListener("responsive", function(integer processID))
Fired when the process rendering the guest web content has become responsive again after being unresponsive.