Partilhar via

HybridWebView

  • Artigo

Procurar amostra. Procurar no exemplo

O HybridWebView do .NET MAUI (.NET Multi-Platform App UI) permite hospedar conteúdo HTML/JS/CSS arbitrário em uma exibição da Web e permite a comunicação entre o código na exibição da Web (JavaScript) e o código que hospeda a exibição da Web (C#/.NET). Por exemplo, se você tiver um aplicativo React JS, poderá hospedá-lo em um aplicativo nativo .NET MAUI multiplataforma e criar o back-end do aplicativo usando C# e .NET.

HybridWebView define as propriedades a seguir:

  • DefaultFile, do tipo string?, que especifica o arquivo dentro do HybridRoot que deve ser apresentado como o arquivo padrão. O valor padrão é index.html.
  • HybridRoot, do tipo string?, que é o caminho dentro dos recursos de ativos brutos do aplicativo que contêm o conteúdo do aplicativo Web. O valor padrão é wwwroot, que é mapeado para Resources/Raw/wwwroot.

Além disso, HybridWebView define um evento RawMessageReceived que é gerado quando uma mensagem bruta é recebida. O objeto HybridWebViewRawMessageReceivedEventArgs que acompanha o evento define uma propriedade Message que contém a mensagem.

O código C# do seu aplicativo pode invocar métodos JavaScript síncronos e assíncronos dentro de HybridWebView com os métodos InvokeJavaScriptAsync e EvaluateJavaScriptAsync. O código JavaScript do seu aplicativo também pode invocar métodos C# de forma síncrona. Para obter mais informações, consulte Invocar JavaScript do C# e Invocar C# do JavaScript.

Para criar um aplicativo .NET MAUI com HybridWebView, você precisa:

  • O conteúdo da Web do aplicativo, que consiste em HTML, JavaScript, CSS, imagens e outros arquivos estáticos.
  • Um HybridWebView controle como parte da interface do usuário do aplicativo. Isso pode ser feito referenciando-o no XAML do aplicativo.
  • Código no conteúdo da Web e em C#/.NET, que usa as HybridWebView APIs para enviar mensagens entre os dois componentes.

Todo o aplicativo, incluindo o conteúdo da Web, é empacotado e executado localmente em um dispositivo e pode ser publicado nas lojas de aplicativos aplicáveis. O conteúdo da Web é hospedado em um controle do modo de exibição da Web nativo e é executado no contexto do aplicativo. Qualquer parte do aplicativo pode acessar serviços Web externos, mas isso não é necessário.

Importante

Por padrão, o controle não estará disponível quando o corte completo ou o HybridWebView AOT nativo estiverem habilitados. Para alterar esse comportamento, consulte Chaves de recurso de corte.

Criar um aplicativo .NET MAUI HybridWebView

Para criar um aplicativo .NET MAUI com um HybridWebView:

  1. Abra um projeto de aplicativo .NET MAUI já existente ou crie um novo.

  2. Adicione seu conteúdo da Web ao projeto de aplicativo .NET MAUI.

    O conteúdo da Web do aplicativo deve ser incluído como parte de um projeto .NET MAUI como ativos brutos. Um ativo bruto é qualquer arquivo na pasta Resources\Raw do aplicativo e inclui subpastas. Para um HybridWebView padrão, o conteúdo da Web deve ser colocado na pasta Resources\Raw\wwwroot, com o arquivo principal chamado index.html.

    Um aplicativo simples pode ter os seguintes arquivos e conteúdo:

    • Resources\Raw\wwwroot\index.html com conteúdo para a interface do usuário principal:

      <!DOCTYPE html>

<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta charset="utf-8" />
    <title></title>
    <link rel="icon" href="data:,">
    <link rel="stylesheet" href="styles/app.css">
    <script src="scripts/HybridWebView.js"></script>
    <script>
        function LogMessage(msg) {
            var messageLog = document.getElementById("messageLog");
            messageLog.value += '\r\n' + msg;
        }

        window.addEventListener(
            "HybridWebViewMessageReceived",
            function (e) {
                LogMessage("Raw message: " + e.detail.message);
            });

        function AddNumbers(a, b) {
            var result = {
                "result": a + b,
                "operationName": "Addition"
            };
            return result;
        }

        var count = 0;

        async function EvaluateMeWithParamsAndAsyncReturn(s1, s2) {
            const response = await fetch("/asyncdata.txt");
            if (!response.ok) {
                throw new Error(`HTTP error: ${response.status}`);
            }
            var jsonData = await response.json();

            jsonData[s1] = s2;

            const msg = 'JSON data is available: ' + JSON.stringify(jsonData);
            window.HybridWebView.SendRawMessage(msg)

            return jsonData;
        }

        async function InvokeDoSyncWork() {
            LogMessage("Invoking DoSyncWork");
            await window.HybridWebView.InvokeDotNet('DoSyncWork');
            LogMessage("Invoked DoSyncWork");
        }

        async function InvokeDoSyncWorkParams() {
            LogMessage("Invoking DoSyncWorkParams");
            await window.HybridWebView.InvokeDotNet('DoSyncWorkParams', [123, 'hello']);
            LogMessage("Invoked DoSyncWorkParams");
        }

        async function InvokeDoSyncWorkReturn() {
            LogMessage("Invoking DoSyncWorkReturn");
            const retValue = await window.HybridWebView.InvokeDotNet('DoSyncWorkReturn');
            LogMessage("Invoked DoSyncWorkReturn, return value: " + retValue);
        }

        async function InvokeDoSyncWorkParamsReturn() {
            LogMessage("Invoking DoSyncWorkParamsReturn");
            const retValue = await window.HybridWebView.InvokeDotNet('DoSyncWorkParamsReturn', [123, 'hello']);
            LogMessage("Invoked DoSyncWorkParamsReturn, return value: message=" + retValue.Message + ", value=" + retValue.Value);
        }

    </script>
</head>
<body>
    <div>
        Hybrid sample!
    </div>
    <div>
        <button onclick="window.HybridWebView.SendRawMessage('Message from JS! ' + (count++))">Send message to C#</button>
    </div>
    <div>
        <button onclick="InvokeDoSyncWork()">Call C# sync method (no params)</button>
        <button onclick="InvokeDoSyncWorkParams()">Call C# sync method (params)</button>
        <button onclick="InvokeDoSyncWorkReturn()">Call C# method (no params) and get simple return value</button>
        <button onclick="InvokeDoSyncWorkParamsReturn()">Call C# method (params) and get complex return value</button>
    </div>
    <div>
        Log: <textarea readonly id="messageLog" style="width: 80%; height: 10em;"></textarea>
    </div>
    <div>
        Consider checking out this PDF: <a href="docs/sample.pdf">sample.pdf</a>
    </div>
</body>
</html>

    • Resources\Raw\wwwroot\scripts\HybridWebView.js com a biblioteca JavaScript padrão HybridWebView :

      window.HybridWebView = {
    "Init": function Init() {
        function DispatchHybridWebViewMessage(message) {
            const event = new CustomEvent("HybridWebViewMessageReceived", { detail: { message: message } });
            window.dispatchEvent(event);
        }

        if (window.chrome && window.chrome.webview) {
            // Windows WebView2
            window.chrome.webview.addEventListener('message', arg => {
                DispatchHybridWebViewMessage(arg.data);
            });
        }
        else if (window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.webwindowinterop) {
            // iOS and MacCatalyst WKWebView
            window.external = {
                "receiveMessage": message => {
                    DispatchHybridWebViewMessage(message);
                }
            };
        }
        else {
            // Android WebView
            window.addEventListener('message', arg => {
                DispatchHybridWebViewMessage(arg.data);
            });
        }
    },

    "SendRawMessage": function SendRawMessage(message) {
        window.HybridWebView.__SendMessageInternal('__RawMessage', message);
    },

    "InvokeDotNet": async function InvokeDotNetAsync(methodName, paramValues) {
        const body = {
            MethodName: methodName
        };

        if (typeof paramValues !== 'undefined') {
            if (!Array.isArray(paramValues)) {
                paramValues = [paramValues];
            }

            for (var i = 0; i < paramValues.length; i++) {
                paramValues[i] = JSON.stringify(paramValues[i]);
            }

            if (paramValues.length > 0) {
                body.ParamValues = paramValues;
            }
        }

        const message = JSON.stringify(body);

        var requestUrl = `${window.location.origin}/__hwvInvokeDotNet?data=${encodeURIComponent(message)}`;

        const rawResponse = await fetch(requestUrl, {
            method: 'GET',
            headers: {
                'Accept': 'application/json'
            }
        });
        const response = await rawResponse.json();

        if (response) {
            if (response.IsJson) {
                return JSON.parse(response.Result);
            }

            return response.Result;
        }

        return null;
    },

    "__SendMessageInternal": function __SendMessageInternal(type, message) {

        const messageToSend = type + '|' + message;

        if (window.chrome && window.chrome.webview) {
            // Windows WebView2
            window.chrome.webview.postMessage(messageToSend);
        }
        else if (window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.webwindowinterop) {
            // iOS and MacCatalyst WKWebView
            window.webkit.messageHandlers.webwindowinterop.postMessage(messageToSend);
        }
        else {
            // Android WebView
            hybridWebViewHost.sendMessage(messageToSend);
        }
    },

    "__InvokeJavaScript": function __InvokeJavaScript(taskId, methodName, args) {
        if (methodName[Symbol.toStringTag] === 'AsyncFunction') {
            // For async methods, we need to call the method and then trigger the callback when it's done
            const asyncPromise = methodName(...args);
            asyncPromise
                .then(asyncResult => {
                    window.HybridWebView.__TriggerAsyncCallback(taskId, asyncResult);
                })
                .catch(error => console.error(error));
        } else {
            // For sync methods, we can call the method and trigger the callback immediately
            const syncResult = methodName(...args);
            window.HybridWebView.__TriggerAsyncCallback(taskId, syncResult);
        }
    },

    "__TriggerAsyncCallback": function __TriggerAsyncCallback(taskId, result) {
        // Make sure the result is a string
        if (result && typeof (result) !== 'string') {
            result = JSON.stringify(result);
        }

        window.HybridWebView.__SendMessageInternal('__InvokeJavaScriptCompleted', taskId + '|' + result);
    }
}

window.HybridWebView.Init();

    Em seguida, adicione qualquer conteúdo da Web adicional ao seu projeto.

    Aviso

    Em alguns casos, o Visual Studio pode adicionar entradas incorretas ao arquivo .csproj do projeto. Ao usar o local padrão para ativos brutos, não deve haver entradas para esses arquivos ou pastas no arquivo .csproj.

  3. Adicione os controles HybridWebView aos aplicativos:

    <Grid RowDefinitions="Auto,*"
      ColumnDefinitions="*">
    <Button Text="Send message to JavaScript"
            Clicked="OnSendMessageButtonClicked" />
    <HybridWebView x:Name="hybridWebView"
                   RawMessageReceived="OnHybridWebViewRawMessageReceived"
                   Grid.Row="1" />
</Grid>

  4. Modifique o CreateMauiApp método da sua MauiProgram classe para habilitar ferramentas de desenvolvedor nos controles WebView subjacentes quando seu aplicativo estiver em execução na configuração de depuração. Para fazer isso, chame o AddHybridWebViewDeveloperTools método no IServiceCollection objeto:

    using Microsoft.Extensions.Logging;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
            });

#if DEBUG
        builder.Services.AddHybridWebViewDeveloperTools();
        builder.Logging.AddDebug();            
#endif
        // Register any app services on the IServiceCollection object

        return builder.Build();
    }
}

  5. Use as APIs HybridWebView para enviar mensagens entre o código JavaScript e C#:

    private void OnSendMessageButtonClicked(object sender, EventArgs e)
{
    hybridWebView.SendRawMessage($"Hello from C#!");
}

private async void OnHybridWebViewRawMessageReceived(object sender, HybridWebViewRawMessageReceivedEventArgs e)
{
    await DisplayAlert("Raw Message Received", e.Message, "OK");
}

    As mensagens acima são classificadas como brutas porque nenhum processamento adicional é executado. Você também pode codificar dados dentro da mensagem para executar mensagens mais avançadas.

Invocar JavaScript em C#

O código C# do aplicativo pode invocar métodos JavaScript de forma síncrona e assíncrona dentro do HybridWebView, com parâmetros opcionais e um valor retornado opcional. Isso pode ser feito com os métodos InvokeJavaScriptAsync e EvaluateJavaScriptAsync:

  • O método EvaluateJavaScriptAsync executa o código JavaScript fornecido por meio de um parâmetro e retorna o resultado como uma cadeia de caracteres.
  • O InvokeJavaScriptAsync método invoca um método JavaScript especificado, opcionalmente passando valores de parâmetro, e especifica um argumento genérico que indica o tipo do valor retornado. Ele retorna um objeto do tipo de argumento genérico que contém o valor retornado do método JavaScript chamado. Internamente, os parâmetros e os valores retornados são codificados em JSON.

Invocar JavaScript síncrono

Os métodos JavaScript síncronos podem ser invocados com os métodos EvaluateJavaScriptAsync e InvokeJavaScriptAsync. No exemplo a seguir, o método InvokeJavaScriptAsync é usado para demonstrar a invocação do JavaScript inserido no conteúdo da Web de um aplicativo. Por exemplo, um método Javascript simples para adicionar dois números pode ser definido em seu conteúdo da Web:

function AddNumbers(a, b) {
    return a + b;
}

O método AddNumbers JavaScript pode ser invocado do C# com o método InvokeJavaScriptAsync:

double x = 123d;
double y = 321d;

double result = await hybridWebView.InvokeJavaScriptAsync<double>(
    "AddNumbers", // JavaScript method name
    HybridSampleJSContext.Default.Double, // JSON serialization info for return type
    [x, y], // Parameter values
    [HybridSampleJSContext.Default.Double, HybridSampleJSContext.Default.Double]); // JSON serialization info for each parameter

A invocação do método requer a especificação de objetos JsonTypeInfo que incluem informações de serialização dos tipos usados na operação. Esses objetos são criados automaticamente incluindo a seguinte classe partial em seu projeto:

[JsonSourceGenerationOptions(WriteIndented = true)]
[JsonSerializable(typeof(double))]
internal partial class HybridSampleJsContext : JsonSerializerContext
{
    // This type's attributes specify JSON serialization info to preserve type structure
    // for trimmed builds.
}

Importante

A classe HybridSampleJsContext deve ser partial para que a geração de código possa fornecer a implementação quando o projeto for compilado. Se o tipo estiver aninhado em outro tipo, esse tipo também deverá ser partial.

Invocar JavaScript assíncrono

Os métodos JavaScript assíncronos podem ser invocados com os métodos EvaluateJavaScriptAsync e InvokeJavaScriptAsync. No exemplo a seguir, o método InvokeJavaScriptAsync é usado para demonstrar a invocação do JavaScript inserido no conteúdo da Web de um aplicativo. Por exemplo, um método Javascript que recupera dados de forma assíncrona pode ser definido em seu conteúdo da Web:

async function EvaluateMeWithParamsAndAsyncReturn(s1, s2) {
    const response = await fetch("/asyncdata.txt");
    if (!response.ok) {
            throw new Error(`HTTP error: ${response.status}`);
    }
    var jsonData = await response.json();
    jsonData[s1] = s2;

    return jsonData;
}

O método JavaScript EvaluateMeWithParamsAndAsyncReturn pode ser invocado do C# com o método InvokeJavaScriptAsync:

Dictionary<string, string> asyncResult = await hybridWebView.InvokeJavaScriptAsync<Dictionary<string, string>>(
    "EvaluateMeWithParamsAndAsyncReturn", // JavaScript method name
    HybridSampleJSContext.Default.DictionaryStringString, // JSON serialization info for return type
    ["new_key", "new_value"], // Parameter values
    [HybridSampleJSContext.Default.String, HybridSampleJSContext.Default.String]); // JSON serialization info for each parameter

Neste exemplo, asyncResult é um Dictionary<string, string> que contém os dados JSON da solicitação da Web.

A invocação do método requer a especificação de objetos JsonTypeInfo que incluem informações de serialização dos tipos usados na operação. Esses objetos são criados automaticamente incluindo a seguinte classe partial em seu projeto:

[JsonSourceGenerationOptions(WriteIndented = true)]
[JsonSerializable(typeof(Dictionary<string, string>))]
[JsonSerializable(typeof(string))]
internal partial class HybridSampleJSContext : JsonSerializerContext
{
    // This type's attributes specify JSON serialization info to preserve type structure
    // for trimmed builds.  
}

Importante

A classe HybridSampleJsContext deve ser partial para que a geração de código possa fornecer a implementação quando o projeto for compilado. Se o tipo estiver aninhado em outro tipo, esse tipo também deverá ser partial.

Invocar C# do JavaScript

O código JavaScript do seu aplicativo dentro do HybridWebView pode invocar métodos C# de forma síncrona, com parâmetros opcionais e um valor retornado opcional. Isso pode ser feito:

  • Definindo métodos C# públicos que serão invocados do JavaScript.
  • Chamar o SetInvokeJavaScriptTarget método para definir o objeto que será o destino das chamadas JavaScript do HybridWebView.
  • Chamando os métodos C# do JavaScript.

Importante

No momento, não há suporte para invocar métodos C# de JavaScript de forma assíncrona.

O exemplo a seguir define quatro métodos públicos para invocar a partir do JavaScript:

public partial class MainPage : ContentPage
{
    ...  

    public void DoSyncWork()
    {
        Debug.WriteLine("DoSyncWork");
    }

    public void DoSyncWorkParams(int i, string s)
    {
        Debug.WriteLine($"DoSyncWorkParams: {i}, {s}");
    }

    public string DoSyncWorkReturn()
    {
        Debug.WriteLine("DoSyncWorkReturn");
        return "Hello from C#!";
    }

    public SyncReturn DoSyncWorkParamsReturn(int i, string s)
    {
        Debug.WriteLine($"DoSyncWorkParamReturn: {i}, {s}");
        return new SyncReturn
        {
            Message = "Hello from C#!" + s,
            Value = i
        };
    }

    public class SyncReturn
    {
        public string? Message { get; set; }
        public int Value { get; set; }
    }  
}

Em seguida, você deve chamar o SetInvokeJavaScriptTarget método para definir o objeto que será o destino das chamadas JavaScript a partir do HybridWebView:

public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();
        hybridWebView.SetInvokeJavaScriptTarget(this);
    }

    ...
}

Os métodos públicos no conjunto de objetos por meio do SetInvokeJavaScriptTarget método podem ser invocados a partir do JavaScript com a window.HybridWebView.InvokeDotNet função:

await window.HybridWebView.InvokeDotNet('DoSyncWork');
await window.HybridWebView.InvokeDotNet('DoSyncWorkParams', [123, 'hello']);
const retValue = await window.HybridWebView.InvokeDotNet('DoSyncWorkReturn');
const retValue = await window.HybridWebView.InvokeDotNet('DoSyncWorkParamsReturn', [123, 'hello']);

A window.HybridWebView.InvokeDotNet função JavaScript invoca um método C# especificado, com parâmetros opcionais e um valor retornado opcional.

Observação

Invocar a window.HybridWebView.InvokeDotNet função JavaScript exige que seu aplicativo inclua a biblioteca JavaScript HybridWebView.js listada anteriormente neste artigo.