Fornecedores de widgets Web

Pode preencher um widget do Windows com HTML servido a partir de uma URL em vez de definir o seu corpo com o Cartões Adaptativos. O seu fornecedor continua a fornecer um payload Adaptive Card JSON que especifica a URL do conteúdo. Comece por implementar um widget provider numa Aplicação do Windows C# ou implementar um widget provider numa aplicação win32 (C++/WinRT), depois adicione as capacidades de conteúdo web descritas aqui.

As APIs de recursos e mensagens neste artigo foram introduzidas na versão 1.6.3 do SDK de Aplicações Windows. Use uma versão estável atualmente suportada dos canais de lançamento do SDK de Aplicações Windows e teste num dispositivo Windows 11 com um host de widgets que suporte conteúdo web.

Os exemplos de C# são fragmentos para um fornecedor de widgets de ambiente de trabalho em pacote. Adicione using Microsoft.Windows.Widgets.Providers; e using Windows.Storage.Streams; ao ficheiro fonte do fornecedor. Continue a implementar IWidgetProvider quando adicionar IWidgetResourceProvider ou IWidgetProviderMessage.

Especifique o URL do conteúdo

Envie o seu payload JSON com o WidgetManager.UpdateWidget. Especifique um objeto de metadados com um campo webUrl que aponte para o conteúdo HTML. Inclua um corpo de Adaptive Card como conteúdo de reserva para hosts que não suportem carregamento de conteúdo 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 suporta conteúdo web. Usa-o quando precisares de adaptar ainda mais a apresentação de recurso. Para mais detalhes, consulte as propriedades do anfitrião dos widgets do Windows.

Lidar com solicitações de recursos

Os fornecedores de widgets podem especificar uma string de filtro de pedido web para um widget no atributo WebRequestFilter do elemento Definition no ficheiro de manifesto do pacote do fornecedor. Sempre que o conteúdo do widget solicita um recurso por URI que corresponda ao filtro, o pedido será interceptado e redirecionado para a implementação do fornecedor do widget do IWidgetResourceProvider.OnResourceRequested.

O padrão de filtro utiliza o formato descrito em Padrões de Correspondência. Usa o Punycode quando necessário. O filtro deve corresponder à origem especificada em webUrl. Os pedidos de qualquer tipo de conteúdo são redirecionados quando correspondem ao filtro, por isso limite o filtro aos recursos que o seu fornecedor gere. Para detalhes, veja Formato XML do manifesto do pacote fornecedor de widgets.

Para gerir pedidos de recursos, os fornecedores de widgets 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 um URL solicitado para uma imagem empacotada. Inclua Assets\image.png como conteúdo no pacote da sua aplicação. RandomAccessStreamReference.CreateFromUri suporta o esquema ms-appx, por isso pode criar a referência do fluxo sem ter de aguardar a localização de um ficheiro.

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 diferimento. Se a sua implementação aguarda trabalho antes de definir a resposta, chame GetDeferral antes que o callback regresse e conclua-o num bloco finally. Trate e reporte falhas assíncronas de acordo com a política de gestão de erros da sua aplicação.

Se não definir uma resposta configurada, o sistema recupera o recurso da web. Podes modificar WidgetResourceRequest.Headers no args.Request antes dessa busca. Só adicione credenciais a pedidos de origens em que confie; uma correspondência de filtro por si só não é autorização para enviar um token.

Gerenciar envio e receção de mensagens para e de conteúdos web

Para receber mensagens de texto do conteúdo do widget que foi publicado usando o método JavaScript window.chrome.webview.postMessage, os fornecedores de widgets podem implementar a interface IWidgetProviderMessage e implementar o método OnMessageReceived.

internal class WidgetProvider : IWidgetProvider, IWidgetProviderMessage

Adicione o callback à sua classe do fornecedor:

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

Envie uma mensagem para o conteúdo web de um widget através do WidgetManager.SendMessageToContent. Passe o ID da instância do widget de WidgetContext.Id, não o ID de definição do manifesto do pacote. Múltiplas instâncias de uma definição têm IDs de instância diferentes.

Chame a seguinte função auxiliar a partir de um callback do fornecedor, passando o WidgetContext para a instância alvo, como o contexto recebido pelo CreateWidget ou pelo OnActionInvoked. Serialize mensagens estruturadas em vez de construir JSON com interpolação de strings, para que os valores que contenham aspas ou barras inversas 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 cadeia de caracteres através do evento de window.chrome.webviewmessage. Se serializares JSON como neste exemplo, faz o parsing da string no teu conteúdo web. Para mais detalhes, consulte PostWebMessageAsString e a API de JavaScript do WebView2.

Limitações e requisitos

Importante

Esta funcionalidade está disponível apenas para utilizadores no Espaço Económico Europeu (EEE).

Os fornecedores de widgets web não são fornecedores de feeds. Para feeds de dashboards e os seus requisitos regionais, consulte Dashboards e fornecedores de feeds. Para o caminho separado do manifesto PWA e do caminho de implementação do service worker, veja Construir widgets orientados por PWA.

  • Última atualização a