Skip to content

Commit 843a50f

Browse files
maxkatz6maxkatz6
authored
Revise WebView documentation for clarity and updates
1 parent e0096c2 commit 843a50f

File tree

1 file changed

+110
-22
lines changed

1 file changed

+110
-22
lines changed

‎xpf/embedding/web-view.md‎

Lines changed: 110 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -6,21 +6,18 @@ title: Using WebView control
66
## Overview
77

88
Windows provides several controls to embed native WebView inside of the application.
9-
The same controls can't be supported in cross platform environment, as these browsers are usually tied to a Windows.
9+
The same controls can't be supported in cross platform XPF environment, as these browsers are usually tied to a Windows.
1010

11-
XPF provides an optional control that abstracts over `WebView2` on Windows and `WKWebView` on macOS. Native browsers that don't require any heavy dependencies like Chromium.
12-
13-
:::note
14-
Since Linux doesn't have any standardized built-in native browser, this platform is not currently supported.
15-
:::
11+
Instead, XPF provides a webview control is based on Avalonia Accelerate version of [NativeWebView](https://docs.avaloniaui.net/accelerate/components/webview/nativewebview).
12+
All functionality and configuration documentation can be applied for both.
1613

17-
## Installing AvaloniaUI.WebView.Wpf package
14+
## Installing WebView package
1815

1916
First of all, make sure you have installed XPF nuget feed as per [instruction](../build-feeds.md).
2017

2118
With nuget feed working, install `Avalonia.Xpf.Controls.WebView` package:
2219
```xml
23-
<PackageReference Include="Avalonia.Xpf.Controls.WebView" Version="11.3.3" />
20+
<PackageReference Include="Avalonia.Xpf.Controls.WebView" Version="11.3.9" />
2421
```
2522

2623
:::note
@@ -39,13 +36,19 @@ Typical usage of the NativeWebView looks like this:
3936

4037
Where `Source` is a bindable property.
4138

42-
## Handling navigation events
39+
:::note
40+
Embeddable `NativeWebView` is not supported on Linux.
41+
Instead, use `NativeWebDialog` there.
42+
:::
43+
44+
45+
### Handling navigation events
4346

4447
`NativeWebView` supports two navigation events:
4548
- `NavigationStarted` is raised when web page navigation was started. You can read the request Uri from `WebViewNavigationStartingEventArgs.Request`. And it's possible to cancel navigation via `WebViewNavigationStartingEventArgs.Cancel` property. This event also handles redirects.
4649
- `NavigationCompleted` is raised when web page navigation has completed. And `WebViewNavigationCompletedEventArgs` provides `Request` as well as `IsSuccess` properties.
4750

48-
## Bi-directional JavaScript execution
51+
### Bi-directional JavaScript execution
4952

5053
In some situations it's necessary to execute arbitrary JavaScript code from the web view control.
5154
`NativeWebView` provides `InvokeScript` async method:
@@ -71,24 +74,109 @@ private void NativeWebView_OnWebMessageReceived(object? sender, WebMessageReceiv
7174

7275
![alt text](../../static/img/webview.png)
7376

77+
## Using `NativeWebDialog` control
78+
79+
Typical usage of the NativeWebDialog looks like this:
80+
```c#
81+
var dialog = new NativeWebDialog
82+
{
83+
Title = "Avalonia Docs",
84+
CanUserResize = true,
85+
Source = new Uri("https://docs.avaloniaui.net/")
86+
};
87+
88+
dialog.NavigationCompleted += (s, e) =>
89+
{
90+
if (e.IsSuccess)
91+
{
92+
// Navigation completed successfully
93+
}
94+
};
95+
96+
dialog.Show();
97+
```
98+
99+
## Using WebAuthenticationBroker
100+
101+
```csharp
102+
var authOptions = new WebAuthenticatorOptions(
103+
RequestUri: new Uri("https://accounts.google.com/o/oauth2/auth?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost&scope=openid"),
104+
RedirectUri: new Uri("http://localhost")
105+
);
106+
107+
var result = await WebAuthenticationBroker.AuthenticateAsync(mainWindow, authOptions);
108+
109+
if (result.CallbackUri != null)
110+
{
111+
// Process authentication result
112+
var code = HttpUtility.ParseQueryString(result.CallbackUri.Query)["code"];
113+
}
114+
```
115+
116+
Replace YOUR_CLIENT_ID with the client ID for your application.
117+
74118
## Using with native WPF
75119

76120
To streamline code migration, it's also possible to use `NativeWebView` control with native WPF on Windows. Without XPF involving.
77121

78122
In this scenario, all the API members and underlying browsers are the same. As well as steps to install, the same package can be used.
79123

80-
## Platform compatibility:
124+
## Platform Prerequisites
81125

82-
| Feature | Windows WebView2-Edge | Windows IE (fallback) | macOS WKWebView | Linux |
83-
|---------------|-------|-------|-------|-------|
84-
| `NativeWebView` | ✔ | ✔ | ✔ | ✖ |
85-
| `Source` | ✔ | ✔ | ✔ | ✖ |
86-
| `NavigationStarted` | ✔ | ✔ | ✔ | ✖ |
87-
| `NavigationCompleted` | ✔ | ✔ | ✔ | ✖ |
88-
| `WebMessageReceived` | ✔ | ✖ | ✔ | ✖ |
89-
| `InvokeScript` | ✔ | ✖ | ✔ | ✖ |
126+
The WebView component relies on native web rendering implementations that must be available on the user's machine:
90127

91-
## Accelerate WebView
128+
### Windows
92129

93-
XPF NativeWebView control is based on Avalonia Accelerate version of [NativeWebView](https://docs.avaloniaui.net/accelerate/components/webview/nativewebview).
94-
All functionality and configuration documentation can be applied for both.
130+
Uses Microsoft Edge WebView2, which is:
131+
132+
- Pre-installed on Windows 11
133+
- May need installation on Windows 10
134+
135+
For Windows 10 users, you can include the WebView2 runtime with your installer:
136+
137+
- [WebView2 Runtime Download](https://developer.microsoft.com/en-us/microsoft-edge/webview2?form=MA13LH#download)
138+
- [Distribution Guide](https://learn.microsoft.com/en-us/microsoft-edge/webview2/concepts/distribution?tabs=dotnetcsharp)
139+
140+
### macOS/iOS
141+
142+
Uses `WKWebView` which is pre-installed on all modern macOS/iOS devices.
143+
144+
- No additional setup required
145+
- For WebAuthenticationBroker: macOS 10.15+ or iOS 12.0+ required
146+
147+
### Linux
148+
149+
Requires GTK 3.0 and WebKitGTK 4.1:
150+
151+
Debian/Ubuntu:
152+
153+
```bash
154+
apt install libgtk-3-0 libwebkit2gtk-4.1-0
155+
```
156+
157+
Fedora:
158+
159+
```bash
160+
dnf install gtk3 webkit2gtk4.1
161+
```
162+
163+
:::note
164+
NativeWebDialog also supports libwebkit2gtk-4.0 and soup-2.4 for older Ubuntu distributives. But it is recommended to use libwebkit2gtk-4.1.
165+
:::
166+
167+
| Component | Windows | macOS | Linux |
168+
|-----------|---------|-------|-------|
169+
| NativeWebView | ✔ | ✔ | ✖* |
170+
| NativeWebDialog | ✔ | ✔ | ✔ |
171+
| WebAuthenticationBroker | ✔** | ✔ | ✔** |
172+
173+
\* For Linux, use NativeWebDialog instead of NativeWebView
174+
\** Uses NativeWebDialog implementation
175+
176+
## Next Steps
177+
178+
For detailed API documentation, see:
179+
180+
- [NativeWebView API](/accelerate/components/webview/nativewebview.md)
181+
- [NativeWebDialog API](/accelerate/components/webview/nativewebdialog.md)
182+
- [WebAuthenticationBroker API](/accelerate/components/webview/webauthenticationbroker.md)

0 commit comments

Comments
 (0)