Provedores de widget web

Você pode preencher um widget Windows com HTML servido de uma URL em vez de definir seu corpo com Cartões Adaptáveis. Seu provedor ainda fornece um conteúdo JSON de Adaptive Card que especifica a URL de conteúdo. Comece com Implementar um provedor de widget em um aplicativo do Windows C# ou implemente um provedor de widget em um aplicativo win32 (C++/WinRT) e adicione os recursos de conteúdo da Web descritos aqui.

As APIs de recursos e mensagens neste artigo foram introduzidas no SDK do Aplicativo Windows 1.6.3. Use uma versão estável com suporte no momento de canais de lançamento do SDK do Aplicativo Windows e teste em um dispositivo Windows 11 com um host de widget que dá suporte ao conteúdo da Web.

Os exemplos de C# são fragmentos para um provedor de widget de área de trabalho empacotado. Adicione using Microsoft.Windows.Widgets.Providers; e using Windows.Storage.Streams; ao arquivo de origem do provedor. Continue implementando IWidgetProvider ao adicionar IWidgetResourceProvider ou IWidgetProviderMessage.

Especificar a URL de conteúdo

Envie seu conteúdo JSON com WidgetManager.UpdateWidget. Especifique um objeto de metadados com um campo webUrl que aponta para o conteúdo HTML. Inclua um body de Adaptive Card como conteúdo de fallback para hosts que não dão suporte ao carregamento de conteúdo da Web, em vez de deixar esses hosts com um widget vazio.

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": [
        {
            "type": "TextBlock",
            "text": "Open the app to view this content.",
            "wrap": true
        }
    ],
    "metadata": {
        "webUrl": "https://contoso.com/widgetprovider.html"
    }
}

A propriedade $host.isWebSupported template indica se o host dá suporte a conteúdo da Web. Use-o quando precisar adaptar ainda mais a apresentação de contingência. Para obter detalhes, consulte propriedades do host de widget do Windows.

Lidar com solicitações de recurso

Os provedores de widget podem especificar uma string de filtro de solicitação web para um widget no atributo WebRequestFilter do elemento Definition no arquivo de manifesto do pacote do provedor. Sempre que o conteúdo do widget solicitar um recurso por URI que corresponda ao filtro, a solicitação será interceptada e redirecionada para a implementação do provedor de widget de IWidgetResourceProvider.OnResourceRequested.

O padrão de filtro usa o formato descrito em Padrões de Correspondência. Use Punycode onde for necessário. O filtro deve corresponder à origem especificada por webUrl. As solicitações para todos os tipos de conteúdo são redirecionadas quando correspondem, portanto, limite o filtro aos recursos que seu provedor manipula. Para obter detalhes, consulte o formato XML do manifesto do pacote do provedor do Widget.

Para lidar com solicitações de recursos, os provedores de widget devem implementar a interface IWidgetResourceProvider .

internal class WidgetProvider : IWidgetProvider, IWidgetResourceProvider

Em OnResourceRequested, defina WidgetResourceRequestedArgs.Response como um WidgetResourceResponse que contém o recurso. Este exemplo mapeia uma URL solicitada para uma imagem empacotada. Inclua Assets\image.png como conteúdo no pacote do aplicativo. RandomAccessStreamReference.CreateFromUri dá suporte ao esquema ms-appx , para que você possa criar a referência de fluxo sem aguardar uma pesquisa de arquivo.

void IWidgetResourceProvider.OnResourceRequested(WidgetResourceRequestedArgs args)
{
    if (args.Request.Uri == "https://contoso.com/logo-image")
    {
        var imageUri = new System.Uri("ms-appx:///Assets/image.png");
        var content = RandomAccessStreamReference.CreateFromUri(imageUri);
        var response = new WidgetResourceResponse(content, "OK", 200);
        response.Headers.Add("Content-Type", "image/png");
        args.Response = response;
    }
}

Este exemplo síncrono não precisa de um adiamento. Se a sua implementação aguarda a conclusão de uma tarefa antes de definir a resposta, chame GetDeferral antes que o retorno de chamada (callback) seja finalizado, e conclua-o dentro de um bloco finally. Processe e relate falhas assíncronas de acordo com a política de tratamento de erros do seu aplicativo.

Se você não definir uma resposta, o sistema recuperará o recurso da Web. Você pode modificar WidgetResourceRequest.Headers em args.Request antes dessa busca. Adicione credenciais apenas às solicitações para origens em que você confia; uma correspondência de filtro por si só não é autorização para enviar um token.

Manipular mensagens de e para o conteúdo da Web

Para receber mensagens de cadeia de caracteres do conteúdo do widget que foi postado usando o método JavaScript window.chrome.webview.postMessage , os provedores de widget podem implementar a interface IWidgetProviderMessage e implementar o método OnMessageReceived .

internal class WidgetProvider : IWidgetProvider, IWidgetProviderMessage

Adicione o callback à classe de provedor:

public void OnMessageReceived(WidgetMessageReceivedArgs args)
{
    System.Console.WriteLine($"Message received from widget {args.WidgetContext.Id}: {args.Message}");
}

Envie uma mensagem para o conteúdo da Web de um widget com WidgetManager.SendMessageToContent. Passe a ID da instância do widget de WidgetContext.Id, não a ID de definição do manifesto do pacote. Várias instâncias de uma definição têm IDs de instância diferentes.

Chame o auxiliar a seguir em um callback do provedor, passando o WidgetContext para a instância de destino, como o contexto recebido por CreateWidget ou OnActionInvoked. Serialize mensagens estruturadas em vez de construir JSON com interpolação de cadeia de caracteres, de modo que os valores que contêm aspas ou barras invertidas permaneçam válidos.

private static void SendLocationToWidget(WidgetContext widgetContext, string location)
{
    string message = System.Text.Json.JsonSerializer.Serialize(
        new { current_location = location });
    WidgetManager.GetDefault().SendMessageToContent(widgetContext.Id, message);
}

O conteúdo web recebe a mensagem como uma string por meio do evento window.chrome.webviewmessage. Se você serializar JSON como neste exemplo, analise a cadeia de caracteres em seu conteúdo da Web. Para obter detalhes, consulte PostWebMessageAsString e o API de JavaScript WebView2.

Limitações e requisitos

Importante

Esse recurso está disponível apenas para usuários da Área Econômica Europeia (EEE).

Os provedores de widget da Web não são provedores de feed. Para feeds de dashboard e seus requisitos regionais, consulte Dashboards e provedores de feed. Para o caminho de implementação que utiliza um manifesto PWA e um service worker separados, consulte Criar widgets baseados em PWA.

  • Última atualização em