WebView

아티클
08/30/2024

.NET 다중 플랫폼 앱 UI(.NET MAUI) WebView 는 앱에 원격 웹 페이지, 로컬 HTML 파일 및 HTML 문자열을 표시합니다. CSS(Cascading Style Sheets) 및 JavaScript에 대한 지원이 포함된 콘텐츠가 표시 WebView 되었습니다. 기본적으로 .NET MAUI 프로젝트에는 원격 웹 페이지를 표시하는 데 필요한 WebView 플랫폼 권한이 포함됩니다.

WebView는 다음 속성을 정의합니다.

Cookies형식 CookieContainer의 쿠키 컬렉션에 대한 스토리지를 제공합니다.
CanGoBack형식 bool의 는 사용자가 이전 페이지로 이동할 수 있는지 여부를 나타냅니다. 읽기 전용 속성입니다.
CanGoForward형식 bool의 는 사용자가 앞으로 이동할 수 있는지 여부를 나타냅니다. 읽기 전용 속성입니다.
Source형식 WebViewSource의 < a0/gt;는 표시되는 위치를 WebView 나타냅니다.
UserAgent형식 string의 은 사용자 에이전트를 나타냅니다. 기본값은 기본 플랫폼 브라우저의 사용자 에이전트이거나 null 확인할 수 없는 경우입니다.

이러한 속성은 BindableProperty 개체에서 지원하며, 따라서 데이터 바인딩의 대상이 될 수 있고 스타일이 지정될 수 있습니다.

속성은 Source 개체 또는 HtmlWebViewSource 개체로 UrlWebViewSource 설정할 수 있습니다. 이 개체는 둘 다에서 WebViewSource파생됩니다. A UrlWebViewSource 는 URL로 지정된 웹 페이지를 로드하는 데 사용되고 개체 HtmlWebViewSource 는 로컬 HTML 파일 또는 로컬 HTML을 로드하는 데 사용됩니다.

WebView 는 Navigating 페이지 탐색이 시작될 때 발생하는 이벤트와 Navigated 페이지 탐색이 완료될 때 발생하는 이벤트를 정의합니다. 이벤트와 Navigating 함께 제공되는 개체는 WebNavigatingEventArgs 탐색을 Cancel 취소하는 데 사용할 수 있는 형식 bool 의 속성을 정의합니다. 이벤트와 Navigated 함께 제공되는 개체는 WebNavigatedEventArgs 탐색 결과를 나타내는 형식 WebNavigationResult 의 속성을 정의 Result 합니다.

WebView 는 다음 이벤트를 정의합니다.

Navigating페이지 탐색이 시작될 때 발생합니다. 이 이벤트와 함께 제공되는 개체는 WebNavigatingEventArgs 탐색을 Cancel 취소하는 데 사용할 수 있는 형식 bool 의 속성을 정의합니다.
Navigated페이지 탐색이 완료되면 발생합니다. 이 이벤트와 함께 제공되는 개체는 WebNavigatedEventArgs 탐색 결과를 나타내는 형식 WebNavigationResult 의 속성을 정의 Result 합니다.
ProcessTerminated- 프로세스가 예기치 않게 종료될 때 WebView 발생합니다. 이 이벤트와 함께 제공되는 개체는 WebViewProcessTerminatedEventArgs 프로세스가 실패한 이유를 나타내는 플랫폼별 속성을 정의합니다.

Important

A WebView 는 해당 HeightRequest 및 WidthRequest 속성을 지정해야 합니다( 또는 .StackLayout VerticalStackLayout)에 HorizontalStackLayout포함되는 경우 이러한 속성을 WebView 지정하지 않으면 렌더링되지 않습니다.

웹 페이지 표시

원격 웹 페이지를 표시하려면 URI를 Source 지정하는 속성으로 string 설정합니다.

<WebView Source="https://learn.microsoft.com/dotnet/maui" />

해당하는 C# 코드는 다음과 같습니다.

WebView webvView = new WebView
{
    Source = "https://learn.microsoft.com/dotnet/maui"
};

URI는 지정된 프로토콜을 사용하여 완전히 구성되어야 합니다.

참고 항목

형식WebViewSource의 Source 속성임에도 불구하고 속성은 문자열 기반 URI로 설정할 수 있습니다. .NET MAUI에는 문자열 기반 URI를 개체로 변환하는 형식 변환기 및 암시적 변환 연산자가 포함되어 있기 때문입니다 UrlWebViewSource .

iOS 및 Mac Catalyst에서 앱 전송 보안 구성

버전 9부터 iOS는 앱이 보안 서버와 통신할 수 있도록 허용합니다. 앱은 안전하지 않은 서버와의 통신을 사용하도록 옵트인해야 합니다.

다음 Info.plist 구성은 특정 도메인이 ATS(Apple Transport Security) 요구 사항을 무시하도록 설정하는 방법을 보여 줍니다.

	<key>NSAppTransportSecurity</key>
	<dict>
		<key>NSExceptionDomains</key>
		<dict>
			<key>mydomain.com</key>
			<dict>
				<key>NSIncludesSubdomains</key>
				<true/>
				<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
				<true/>
				<key>NSTemporaryExceptionMinimumTLSVersion</key>
				<string>TLSv1.1</string>
			</dict>
		</dict>
	</dict>

특정 도메인만 ATS를 바이패스하도록 설정하여 신뢰할 수 없는 도메인에 대한 추가 보안을 활용하면서 신뢰할 수 있는 사이트를 사용할 수 있도록 하는 것이 가장 좋습니다.

다음 Info.plist 구성은 앱에 대해 ATS를 사용하지 않도록 설정하는 방법을 보여 줍니다.

	<key>NSAppTransportSecurity</key>
	<dict>
		<key>NSAllowsArbitraryLoads</key>
		<true/>
	</dict>

Important

앱에서 안전하지 않은 웹 사이트에 연결해야 하는 경우 키를 사용하여 ATS를 완전히 해제하는 대신 항상 키를 사용하여 NSExceptionDomains 도메인을 NSAllowsArbitraryLoads 예외로 입력해야 합니다.

로컬 HTML 표시

인라인 HTML을 표시하려면 속성을 개체로 HtmlWebViewSource 설정합니다Source.

<WebView>
    <WebView.Source>
        <HtmlWebViewSource Html="&lt;HTML&gt;&lt;BODY&gt;&lt;H1&gt;.NET MAUI&lt;/H1&gt;&lt;P&gt;Welcome to WebView.&lt;/P&gt;&lt;/BODY&gt;&lt;HTML&gt;" />
    </WebView.Source>
</WebView>

XAML에서 HTML 문자열은 이스케 < 이프 및 > 기호로 인해 읽을 수 없게 될 수 있습니다. 따라서 가독성을 높이기 위해 HTML을 섹션에 CDATA 인라인 처리할 수 있습니다.

<WebView>
    <WebView.Source>
        <HtmlWebViewSource>
            <HtmlWebViewSource.Html>
                <![CDATA[
                <HTML>
                <BODY>
                <H1>.NET MAUI</H1>
                <P>Welcome to WebView.</P>
                </BODY>
                </HTML>
                ]]>
            </HtmlWebViewSource.Html>
        </HtmlWebViewSource>
    </WebView.Source>
</WebView>

해당하는 C# 코드는 다음과 같습니다.

WebView webView = new WebView
{
    Source = new HtmlWebViewSource
    {
        Html = @"<HTML><BODY><H1>.NET MAUI</H1><P>Welcome to WebView.</P></BODY></HTML>"
    }
};

로컬 HTML 파일 표시

로컬 HTML 파일을 표시하려면 앱 프로젝트의 Resources\Raw 폴더에 파일을 추가하고 빌드 작업을 MauiAsset로 설정합니다. 그런 다음, 속성 값 Source 으로 설정된 개체에 HtmlWebViewSource 정의된 인라인 HTML에서 파일을 로드할 수 있습니다.

<WebView>
    <WebView.Source>
        <HtmlWebViewSource>
            <HtmlWebViewSource.Html>
                <![CDATA[
                <html>
                <head>
                </head>
                <body>
                <h1>.NET MAUI</h1>
                <p>The CSS and image are loaded from local files!</p>
                <p><a href="localfile.html">next page</a></p>
                </body>
                </html>                    
                ]]>
            </HtmlWebViewSource.Html>
        </HtmlWebViewSource>
    </WebView.Source>
</WebView>

MauiAsset 빌드 작업을 사용하여 앱 프로젝트에 추가된 경우 로컬 HTML 파일은 CSS(Cascading Style Sheets), JavaScript 및 이미지를 로드할 수 있습니다.

원시 자산에 대한 자세한 내용은 원시 자산을 참조 하세요.

콘텐츠 다시 로드

WebView 에는 Reload 해당 소스를 다시 로드하기 위해 호출할 수 있는 메서드가 있습니다.

WebView webView = new WebView();
...
webView.Reload();

메서드가 Reload 호출되면 ReloadRequested 현재 콘텐츠를 다시 로드하기 위한 요청이 발생했음을 나타내는 이벤트가 발생합니다.

WebView 는 및 메서드를 사용하여 프로그래밍 방식 탐색을 GoBack GoForward 지원합니다. 이러한 메서드를 사용하면 페이지 스택을 WebView 탐색할 수 있으며, 값 및 CanGoForward 속성을 검사한 CanGoBack 후에만 호출해야 합니다.

WebView webView = new WebView();
...

// Go backwards, if allowed.
if (webView.CanGoBack)
{
    webView.GoBack();
}

// Go forwards, if allowed.
if (webView.CanGoForward)
{
    webView.GoForward();
}

프로그래밍 방식으로 또는 사용자가 시작한 페이지에서 페이지 탐색이 발생하면 WebView다음 이벤트가 발생합니다.

Navigating- 페이지 탐색이 시작될 때 발생합니다. 이벤트와 Navigating 함께 제공되는 개체는 WebNavigatingEventArgs 탐색을 Cancel 취소하는 데 사용할 수 있는 형식 bool 의 속성을 정의합니다.
Navigated- 페이지 탐색이 완료될 때 발생합니다. 이벤트와 Navigated 함께 제공되는 개체는 WebNavigatedEventArgs 탐색 결과를 나타내는 형식 WebNavigationResult 의 속성을 정의 Result 합니다.

Android에 대한 권한 처리

카메라 또는 마이크와 같은 디바이스의 녹음 하드웨어에 대한 액세스를 요청하는 페이지로 이동하면 컨트롤에서 WebView 사용 권한을 부여해야 합니다. 컨트롤은 WebView Android의 Android.Webkit.WebChromeClient 형식을 사용하여 권한 요청에 반응합니다. 그러나 WebChromeClient .NET MAUI에서 제공하는 구현은 권한 요청을 무시합니다. 사용 권한 요청에서 MauiWebChromeClient 상속하고 승인하는 새 형식을 만들어야 합니다.

Important

WebView 이 방법을 사용하여 권한 요청을 승인하도록 사용자 지정하려면 Android API 26 이상이 필요합니다.

웹 페이지에서 컨트롤로의 WebView 권한 요청은 .NET MAUI 앱에서 사용자에게 부여한 권한 요청과 다릅니다. .NET MAUI 앱 권한은 전체 앱에 대해 사용자가 요청하고 승인합니다. 컨트롤은 WebView 하드웨어에 액세스하는 앱 기능에 따라 달라집니다. 이 개념을 설명하기 위해 디바이스의 카메라에 대한 액세스를 요청하는 웹 페이지를 고려합니다. 해당 요청이 컨트롤에 WebView 의해 승인되었더라도 .NET MAUI 앱은 사용자가 카메라에 액세스하도록 승인하지 않았더라도 웹 페이지에서 카메라에 액세스할 수 없습니다.

다음 단계에서는 카메라를 사용하기 위해 컨트롤에서 WebView 권한 요청을 가로채는 방법을 보여 줍니다. 마이크를 사용하려는 경우 카메라 관련 권한 대신 마이크 관련 권한을 사용한다는 점을 제외하면 단계가 유사합니다.

먼저 필요한 앱 권한을 Android 매니페스트에 추가합니다. Platforms/Android/AndroidManifest.xml 파일을 열고 노드에 다음을 manifest 추가합니다.
```
<uses-permission android:name="android.permission.CAMERA" />
```

컨트롤이 포함된 WebView 페이지가 로드되는 경우와 같이 앱의 특정 지점에서는 앱이 카메라에 액세스할 수 있도록 사용자에게 권한을 요청합니다.

private async Task RequestCameraPermission()
{
    PermissionStatus status = await Permissions.CheckStatusAsync<Permissions.Camera>();

    if (status != PermissionStatus.Granted)
        await Permissions.RequestAsync<Permissions.Camera>();
}

Platforms/Android 폴더에 다음 클래스를 추가하여 프로젝트의 네임스페이스에 맞게 루트 네임스페이스를 변경합니다.

using Android.Webkit;
using Microsoft.Maui.Handlers;
using Microsoft.Maui.Platform;

namespace MauiAppWebViewHandlers.Platforms.Android;

internal class MyWebChromeClient: MauiWebChromeClient
{
    public MyWebChromeClient(IWebViewHandler handler) : base(handler)
    {

    }

    public override void OnPermissionRequest(PermissionRequest request)
    {
        // Process each request
        foreach (var resource in request.GetResources())
        {
            // Check if the web page is requesting permission to the camera
            if (resource.Equals(PermissionRequest.ResourceVideoCapture, StringComparison.OrdinalIgnoreCase))
            {
                // Get the status of the .NET MAUI app's access to the camera
                PermissionStatus status = Permissions.CheckStatusAsync<Permissions.Camera>().Result;

                // Deny the web page's request if the app's access to the camera is not "Granted"
                if (status != PermissionStatus.Granted)
                    request.Deny();
                else
                    request.Grant(request.GetResources());

                return;
            }
        }

        base.OnPermissionRequest(request);
    }
}

이전 코드 조각에서 클래스는 MyWebChromeClient 웹 페이지 권한 요청을 가로채기 위해 메서드를 MauiWebChromeClient상속하고 재정 OnPermissionRequest 의합니다. 각 사용 권한 항목이 카메라를 나타내는 문자열 상수와 PermissionRequest.ResourceVideoCapture 일치하는지 확인합니다. 카메라 사용 권한이 일치하는 경우 코드는 앱에 카메라 사용 권한이 있는지 확인합니다. 권한이 있는 경우 웹 페이지의 요청이 부여됩니다.

SetWebChromeClient Android 컨트롤의 WebView 메서드를 사용하여 Chrome 클라이언트MyWebChromeClient를 .로 설정합니다. 다음 두 항목은 Chrome 클라이언트를 설정하는 방법을 보여 줍니다.
- 이름이 theWebViewControl.NET MAUI WebView 컨트롤인 경우 Android 컨트롤인 플랫폼 보기에서 직접 Chrome 클라이언트를 설정할 수 있습니다.
```
((IWebViewHandler)theWebViewControl.Handler).PlatformView.SetWebChromeClient(new MyWebChromeClient((IWebViewHandler)theWebViewControl.Handler));
```
- 처리기 속성 매핑을 사용하여 모든 WebView 컨트롤이 Chrome 클라이언트를 사용하도록 강제할 수도 있습니다. 자세한 내용은 처리기를 참조 하세요.
  
  메서드와 같이 앱이 시작될 때 다음 코드 조각의 CustomizeWebViewHandler 메서드를 MauiProgram.CreateMauiApp 호출해야 합니다.
```
private static void CustomizeWebViewHandler()
{
#if ANDROID26_0_OR_GREATER
    Microsoft.Maui.Handlers.WebViewHandler.Mapper.ModifyMapping(
        nameof(Android.Webkit.WebView.WebChromeClient),
        (handler, view, args) => handler.PlatformView.SetWebChromeClient(new MyWebChromeClient(handler)));
#endif
}
```

쿠키 설정

쿠키는 웹 요청과 함께 지정된 URL로 전송되도록 설정될 WebView 수 있습니다. 개체를 추가하여 Cookie 쿠키를 CookieContainer설정한 다음 컨테이너를 바인딩 가능한 속성의 WebView.Cookies 값으로 설정합니다. 다음 코드에서는 예제를 보여 줍니다.

using System.Net;

CookieContainer cookieContainer = new CookieContainer();
Uri uri = new Uri("https://learn.microsoft.com/dotnet/maui", UriKind.RelativeOrAbsolute);

Cookie cookie = new Cookie
{
    Name = "DotNetMAUICookie",
    Expires = DateTime.Now.AddDays(1),
    Value = "My cookie",
    Domain = uri.Host,
    Path = "/"
};
cookieContainer.Add(uri, cookie);
webView.Cookies = cookieContainer;
webView.Source = new UrlWebViewSource { Url = uri.ToString() };

이 예제에서는 개체에 CookieContainer 단일 Cookie 이 추가된 다음 속성 값 WebView.Cookies 으로 설정됩니다. WebView 웹 요청을 지정된 URL로 보내면 쿠키가 요청과 함께 전송됩니다.

JavaScript 호출

WebView 에는 C#에서 JavaScript 함수를 호출하고 모든 결과를 호출하는 C# 코드로 반환하는 기능이 포함되어 있습니다. 이 interop는 다음 예제에 표시된 메서드를 사용하여 수행 EvaluateJavaScriptAsync 됩니다.

Entry numberEntry = new Entry { Text = "5" };
Label resultLabel = new Label();
WebView webView = new WebView();
...

int number = int.Parse(numberEntry.Text);
string result = await webView.EvaluateJavaScriptAsync($"factorial({number})");
resultLabel.Text = $"Factorial of {number} is {result}.";

메서드는 WebView.EvaluateJavaScriptAsync 인수로 지정된 JavaScript를 평가하고 결과를 .로 string반환합니다. 이 예제 factorial 에서는 JavaScript 함수가 호출되어 결과 요소 number 값을 반환합니다. 이 JavaScript 함수는 로드되는 WebView 로컬 HTML 파일에 정의되며 다음 예제에 나와 있습니다.

<html>
<body>
<script type="text/javascript">
function factorial(num) {
        if (num === 0 || num === 1)
            return 1;
        for (var i = num - 1; i >= 1; i--) {
            num *= i;
        }
        return num;
}
</script>
</body>
</html>

iOS 및 Mac Catalyst에서 네이티브 WebView 구성

네이티브 WebView 컨트롤은 MauiWKWebView iOS 및 Mac Catalyst에서 WKWebView파생됩니다. 생성자 오버로드 중 MauiWKWebView 하나를 사용하면 개체를 지정할 수 있으며 WKWebViewConfiguration , 개체를 구성하는 WKWebView 방법에 대한 정보를 제공합니다. 일반적인 구성에는 사용자 에이전트 설정, 웹 콘텐츠에 사용할 수 있는 쿠키 지정 및 웹 콘텐츠에 사용자 지정 스크립트 삽입이 포함됩니다.

앱에서 개체를 WKWebViewConfiguration 만든 다음 필요에 따라 해당 속성을 구성할 수 있습니다. 또는 정적 MauiWKWebView.CreateConfiguration 메서드를 호출하여 .NET MAUI의 WKWebViewConfiguration 개체를 검색한 다음 수정할 수 있습니다. WKWebViewConfiguration 그런 다음 생성자 오버로드에 대한 인수로 개체를 MauiWKWebView 지정할 수 있습니다.

처리기의 플랫폼 뷰를 만든 후에는 iOS 및 Mac Catalyst에서 네이티브 WebView 구성을 변경할 수 없으므로 사용자 지정 처리기 팩터리 대리자를 만들어 수정해야 합니다.

#if IOS || MACCATALYST
using WebKit;
using CoreGraphics;
using Microsoft.Maui.Platform;
using Microsoft.Maui.Handlers;
#endif
...

#if IOS || MACCATALYST
    Microsoft.Maui.Handlers.WebViewHandler.PlatformViewFactory = (handler) =>
    {
        WKWebViewConfiguration config = MauiWKWebView.CreateConfiguration();
        config.ApplicationNameForUserAgent = "MyProduct/1.0.0";
        return new MauiWKWebView(CGRect.Empty, (WebViewHandler)handler, config);
    };
#endif

참고 항목

앱에 WKWebViewConfiguration 표시되기 전에 개체를 WebView 사용하여 구성 MauiWKWebView 해야 합니다. 이 작업을 수행하는 데 적합한 위치는 앱의 시작 경로(예: MauiProgram.cs 또는 App.xaml.cs)에 있습니다.

iOS 및 Mac Catalyst에서 미디어 재생 기본 설정

그림의 자동 실행 및 사진을 포함하여 HTML5 비디오의 인라인 미디어 재생은 기본적으로 WebView iOS 및 Mac Catalyst에서 사용하도록 설정됩니다. 이 기본값을 변경하거나 다른 미디어 재생 기본 설정을 지정하려면 처리기의 플랫폼 보기를 만든 후에는 미디어 재생 기본 설정을 변경할 수 없으므로 사용자 지정 처리기 팩터리 대리자를 만들어야 합니다. 다음 코드에서는 이 작업을 수행하는 예제를 보여 있습니다.

#if IOS || MACCATALYST
using WebKit;
using CoreGraphics;
using Microsoft.Maui.Platform;
using Microsoft.Maui.Handlers;
#endif
...

#if IOS || MACCATALYST
    Microsoft.Maui.Handlers.WebViewHandler.PlatformViewFactory = (handler) =>
    {
        WKWebViewConfiguration config = MauiWKWebView.CreateConfiguration();

        // True to play HTML5 videos inliine, false to use the native full-screen controller.
        config.AllowsInlineMediaPlayback = false;

        // True to play videos over AirPlay, otherwise false.
        config.AllowsAirPlayForMediaPlayback = false;

        // True to let HTML5 videos play Picture in Picture.
        config.AllowsPictureInPictureMediaPlayback = false;

        // Media types that require a user gesture to begin playing.
        config.MediaTypesRequiringUserActionForPlayback = WKAudiovisualMediaTypes.All;

        return new MauiWKWebView(CGRect.Empty, (WebViewHandler)handler, config);
    };
#endif

iOS에서 구성 WebView 에 대한 자세한 내용은 iOS 및 Mac Catalyst에서 네이티브 WebView 구성을 참조하세요.

Mac Catalyst에서 WebView 검사

Safari 개발자 도구를 사용하여 Mac Catalyst의 WebView 콘텐츠를 검사하려면 앱에 다음 코드를 추가합니다.

#if MACCATALYST
        Microsoft.Maui.Handlers.WebViewHandler.Mapper.AppendToMapping("Inspect", (handler, view) =>
        {
            if (OperatingSystem.IsMacCatalystVersionAtLeast(16, 6))
                handler.PlatformView.Inspectable = true;
        });
#endif

이 코드는 Safari 개발자 도구에서 콘텐츠를 검사할 수 있도록 WebView Mac Catalyst의 속성 매퍼 WebViewHandler 를 사용자 지정합니다. 처리기에 대한 자세한 내용은 처리기를 참조 하세요.

Mac Catalyst 앱에서 Safari 개발자 도구를 사용하려면 다음을 수행합니다.

Mac에서 Safari를 엽니다.
Safari의 메뉴 모음에서 Safari > 설정 > 고급 > 표시 개발 메뉴를 선택합니다.
.NET MAUI Mac Catalyst 앱을 실행합니다.
Safari에서 자리 표시자가 디바이스 이름(예: Macbook Pro디바이스 이름)인 {Device name} 개발 {Device name} 메뉴를 선택합니다 > . 그런 다음 앱 이름 아래에 있는 항목을 선택하면 실행 중인 앱도 강조 표시됩니다. 그러면 웹 검사기 창이 표시됩니다.

시스템 브라우저 시작

에서 제공하는 Microsoft.Maui.Essentials클래스를 사용하여 시스템 웹 브라우저에서 URI를 Launcher 열 수 있습니다. 시작 관리자의 OpenAsync 메서드를 호출하고 URI를 string 나타내는 인수를 Uri 전달하여 엽니다.

await Launcher.OpenAsync("https://learn.microsoft.com/dotnet/maui");

자세한 내용은 시작 관리자를 참조 하세요.

다음을 통해 공유

WebView

웹 페이지 표시

iOS 및 Mac Catalyst에서 앱 전송 보안 구성

로컬 HTML 표시

로컬 HTML 파일 표시

콘텐츠 다시 로드

탐색 수행

Android에 대한 권한 처리

쿠키 설정

JavaScript 호출

iOS 및 Mac Catalyst에서 네이티브 WebView 구성

iOS 및 Mac Catalyst에서 미디어 재생 기본 설정

Mac Catalyst에서 WebView 검사

시스템 브라우저 시작

추가 리소스