Partilhar via


Fornecedores de widgets Web

Na versão mais recente, os aplicativos que implementam widgets do Windows podem optar por preencher o conteúdo do widget com HTML servido a partir de uma URL remota. Anteriormente, o conteúdo do widget só podia ser fornecido no formato de esquema Adaptive Card no payload JSON que era passado do provedor para o Widgets Board. Como os provedores de widgets da Web ainda devem fornecer uma carga JSON de cartão adaptável, você deve seguir as etapas para implementar um provedor de widget em Implementar um provedor de widget em um aplicativo do Windows em C# ou Implementar um provedor de widget em um aplicativo win32 (C++/WinRT).

Especifique o URL do conteúdo

Os provedores de widgets passam uma carga JSON para o Widgets Board com uma chamada para WidgetManager.UpdateWidget. Para um web widget, em vez de fornecer um objeto body definindo o conteúdo do widget, você deve especificar um objeto body vazio e, em vez disso, incluir um objeto de metadados com um campo webUrl que aponte para a URL que fornecerá o conteúdo HTML para o widget.

{ 
    "type": "AdaptiveCard", 
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", 
    "version": "1.6", 
    "body": [], 
    "metadata": 
    { 
        "webUrl": "https://www.contoso.com/widgetprovider.html" 
    } 
} 

Lidar com solicitações de recursos

Os provedores de widgets podem especificar uma cadeia de caracteres de filtro de solicitação da 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á intercetada e redirecionada para a implementação do provedor do widget de IWidgetResourceProvider.OnResourceRequested.

O padrão de filtro é expresso usando o formato descrito em Padrões de correspondência. A string de filtro no registro deve usar Punycode quando necessário. Todos os tipos de conteúdo serão redirecionados quando correspondidos, portanto, o filtro só deve resolver para o conteúdo destinado a ser obtido por meio do IWidgetResourceProvider no aplicativo. Para obter mais informações sobre o formato de manifesto do pacote do provedor de widgets, consulte Formato XML do manifesto do pacote do provedor de widgets.

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

internal class WidgetProvider : IWidgetProvider, IWidgetResourceProvider

Na implementação do método OnResourceRequested , os provedores de widget podem fornecer os recursos solicitados definindo a propriedade WidgetResourceRequestedArgs.Response como um objeto WidgetResourceResponse que contém o recurso solicitado. Ao obter o recurso de forma assíncrona, o provedor deve solicitar um adiamento chamando WidgetResourceRequestedArgs.GetDeferral e, em seguida, concluir o adiamento quando o recurso tiver sido definido.

async void IWidgetResourceProvider.OnResourceRequested(WidgetResourceRequestedArgs args)
{
    var deferral = args.GetDeferral();

    if (args.Request.Uri.Length > 0)
    {
        if (args.Request.Uri == "https://contoso.com/logo-image")
        {
            string fullPath = Windows.ApplicationModel.Package.Current.InstalledPath + "/Assets/image.png";
            var file = await StorageFile.GetFileFromPathAsync(fullPath);
            var response = new WidgetResourceResponse(RandomAccessStreamReference.CreateFromFile(file), "OK", 200);
            response.Headers.Add("Content-Type", "image/png");
            args.Response = response;
        }
    }

    deferral.Complete();
}

Se o provedor não definir uma resposta no objeto WidgetResourceRequestedArgs passado para o método, o sistema recuperará o recurso da Web. Nesse caso, o provedor pode optar por modificar a propriedade Headers do objeto WidgetResourceRequestedArgs.Request, como para fornecer contexto de usuário ou tokens, e o sistema usará os cabeçalhos atualizados ao recuperar o recurso da Web.

Gerenciar envio e receção de mensagens para e de conteúdos 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 widgets podem implementar a interface IWidgetProviderMessage e implementar o método OnMessageReceived .

internal class WidgetProvider : IWidgetProvider, IWidgetProviderMessage
...
public void OnMessageReceived(WidgetMessageReceivedArgs args)
{
    Console.WriteLine($"Message received from widget {args.WidgetContext.Id}: {args.Message}");
}

Os provedores de widgets podem enviar uma mensagem para o conteúdo da Web do widget chamando WidgetManager.SendMessage. Você deve fornecer a ID do widget para o qual a mensagem é enviada, que é o valor especificado no atributo Id do elemento Definition no arquivo de manifesto do pacote do provedor. Para obter mais informações, consulte Formato XML do manifesto do pacote do provedor de widgets. A cadeia de caracteres de mensagem pode ser texto simples ou a forma serializada de um objeto interpretado pelo conteúdo da Web. Para obter mais informações, consulte PostWebMessageAsString.

var message = $"{{ \"current_location\": \"{ location }\" }}";
WidgetManager.GetDefault().SendMessageToContent("Weather_Widget", message);

Limitações e requisitos

  • Esta funcionalidade está disponível apenas para utilizadores no Espaço Económico Europeu (EEE). No EEE, as aplicações instaladas que implementam um provedor de feed podem fornecer um feed de conteúdo no Painel de Widgets.