window.HTMLWebViewElement
Since: v6.0
HTMLWebViewElement()
WebViews in Adobe UXP is a component that allows you to embed web content in your plugins.
They are essentially a browser window that is displayed inside the plugin, allowing you to load web pages,
and interact with them using JavaScript.
WebViews can be used to display complex web pages inside the plugin.
WebViews can be controlled by the plugin using the JavaScript API provided by UXP.
They can also communicate with the plugin using postMessage
,
allowing the plugin to interact with WebView and vice versa.
WebViews can be used to access external web services, to create custom UI
and to isolate the web content from the rest of the plugin.
WebViews are resource intensive since it launches multiple processes per plugin
and therefore should be used only in cases where you cannot create the plugin using UXP features.
Note:
- WebViews support was introduced in UXP v6.0 to be used only in Dialogs. The reasoning here was to limit WebViews usage in persistent panels. Later due to overwhelming requests, WebView support was added for
Panels
with UXP v6.4. - WebViews will need manifest version v5 or above.
- Checkout the template available in
UXP Developer Tool
for a quick getting starter plugin for WebView in UXP. requiredPermissions.webview.enableMessageBridge=“localAndRemote”
is required for Plugin & WebView communication via postMessage.
Limitations:
- Only remote content (including localhost) is allowed at present. This means you will not be able to load local html files from plugin folders in UXP WebView. This behaviour is due to limitations on WindowsOS and may be enabled in later releases.
- Any links in a UXP WebView will not open in a new window.
e.g., In a browser, clicking
<a href="https://www.adobe.com" target="_blank">
would create a new Window and openhttps://www.adobe.com
from the new Window or JavaScript alert() pops up a new Window. UXP WebView doesn't permit this.
In your plugin's code, add a WebView element in the desired location.
The element can take attributes such as id , height , and src to specify the WebView's properties
Copied to your clipboard<webview id="webviewsample" width="100%" height="360px" src="https://www.adobe.com" uxpAllowInspector="true" ></webview>
Manifest requirements for UXP WebView
In order to use UXP WebView, the plugin should have the following manifest v5 permissions.Key | Value | Description | Mandatory/Optional |
---|---|---|---|
.domains | string[] | Allows access to the specified domains. Wildcards (except top-level) are supported. e.g "https://*.adobe.com". Recommended | Mandatory |
.domains | "all" | Allows access to all domains. Not recommended, may affect performance, security and privacy. Plugin may be blocked by enterprises. | Mandatory |
.allow | "yes" | Enables WebView access to the plugin | Mandatory |
.enableMessageBridge | "localAndRemote" | Allows Plugin & the content loaded on WebView to communicate regardless of where the content is loaded from **locally or remotely.** **Note: ** At this stage only remote content is allowed. Refer **Limitations** section for more details | Optional |
.enableMessageBridge | "no" | Not allow WebView & the content loaded on WebView to communicate | Optional |
Example
Copied to your clipboard1// In your `manifest.json` update the following2{3"manifestVersion": 5,4"requiredPermissions": {5 "webview": {6 "allow": "yes",7 // domains --> string[] | "all"8 "domains": [ "https://*.adobe.com", "https://*.google.com"],9 // enableMessageBridge can use either of these data "localAndRemote" | "localOnly" | "no"10 "enableMessageBridge": "localAndRemote"11 }12 }13}
HTMLWebViewElement()
Properties
Name | Type | Description |
---|---|---|
uxpallowinspector | boolean | Enable Developer tools for debugging in UXP WebView Note: Not supported in UWP platform eg: <webview id="webviewsample" width="100%" height="360px" src="https://www.adobe.com" uxpAllowInspector="true" ></webview> |
src | string | The url to load in the WebView |
width | string | Width of the WebView |
height | string | Height of the WebView |
src : string
The url to load in the WebView. Only remote content (including localhost
) is allowed at present.
postMessage(message, targetOrigin, transfer)
The plugin and the content within the WebView can communicate with each other using postMessage
and listening to the 'message' event.
[Plugin]
- send messages to the content in the WebView
HTMLWebViewElement.postMessage(msg)
- receive messages from the content in the WebView
window.addEventListener("message", (e) => {...})
wheree: Event { origin: url of the content, source: window.HTMLWebViewElement, data: message }
[Content in the WebView]
- send messages to plugin
window.uxpHost.postMessage(msg)
- receive messages from plugin
window.addEventListener("message", (e) => { ... })
wheree: Event { origin: plugin id, source: window.uxpHost, data: message }
Param | Type | Description |
---|---|---|
message | Object | A message sent to the WebView. Please note that the message is stringified & parsed by JSON |
targetOrigin | string | [Optional] - The origin of WebView for the event to be dispatched. The literal string "*" indicates no preference |
transfer | Object | Optional and not functional yet . Will be enabled in future release. |
Example
Copied to your clipboard1// Send message from plugin to WebView2let webViewDisplay = document.getElementById("webviewSample");3webViewDisplay.postMessage("PluginMessage1");45// Plugin receives message from WebView via "message" event.6window.addEventListener("message", (e) => {7 console.log(`Message from WebView(Origin:${e.origin}): ${e.data}\n`);89 if (e.data === "webviewmessage1") {10 webViewDisplay.postMessage("Thanks, Message1 recieved successfully");11 }12});
Example
Copied to your clipboard1// WebView sends message to Plugin2window.uxpHost.postMessage("webviewmessage1");34// WebView receives messages from Plugin5window.addEventListener("message", (e) => {6 // (e) from Plugin7 // e.origin would be 'plugin id'8 // e.source would be 'window.uxpHost'9 // e.data is 'JSON.parse(JSON.stringify("PluginMessage1"))' which is "PluginMessage1"10 if (e.data === "PluginMessage1") {11 console.log(e.data);12 }13});
loadstart
Event fired when loading has started.
Properties
Name | Type | Description |
---|---|---|
type | string | "loadstart" |
url | string | url which WebView navigates to |
Example
Copied to your clipboard1const webview = document.getElementById("webviewSample");2// Print the url when loading has started3webview.addEventListener("loadstart", (e) => {4 console.log(`webview.loadstart ${e.url}`);5});
loadstop
Event fired when loading has completed.
Properties
Name | Type | Description |
---|---|---|
type | string | "loadstop" |
url | string | url which WebView navigates to |
Example
Copied to your clipboard1// Print the url when loading has completed2webview.addEventListener("loadstop", (e) => {3 console.log(`webview.loadstop ${e.url}`);4});
loaderror
Event fired when loading has failed.
Properties
Name | Type | Description |
---|---|---|
type | string | "loaderror" |
url | string | url which WebView navigates to |
code | number | Platform specific error code. Below are the Error Code details for the following platforms 1. Mac Error Codes 2. Windows Error Code 3. Windows Common HRESULT codes |
message | string | Error description |
Example
Copied to your clipboard1// Print the url, code and message when loading has failed2webview.addEventListener("loaderror", (e) => {3 console.log(`webview.loaderror ${e.url}, code:${e.code}, message:${e.message}`);4});