Fornitori di widget web

È possibile popolare un widget Windows con HTML fornito da un URL invece di definirne il corpo con Schede adattive. Il provider fornisce ancora un payload JSON della scheda adattiva che specifica l'URL del contenuto. Iniziare con Implementare un provider di widget in un app di Windows C# o Implementare un provider di widget in un'app win32 (C++/WinRT), quindi aggiungere le funzionalità web-content descritte qui.

Le API di risorsa e messaggistica in questo articolo sono state introdotte in SDK per app di Windows 1.6.3. Usare una versione stabile attualmente supportata dai canali di rilascio di SDK per app di Windows e testare su un dispositivo Windows 11 con un host widget che supporta il contenuto Web.

Gli esempi C# sono frammenti per un provider pacchettizzato di widget desktop. Aggiungere using Microsoft.Windows.Widgets.Providers; e using Windows.Storage.Streams; al file di origine del provider. Continua a implementare IWidgetProvider quando aggiungi IWidgetResourceProvider o IWidgetProviderMessage.

Specificare l'URL del contenuto

Inviare il payload JSON con WidgetManager.UpdateWidget. Specificare un oggetto metadata con un campo webUrl che punta al contenuto HTML. Includi un body della scheda adattiva come contenuto di fallback per gli host che non supportano il caricamento del contenuto Web, anziché lasciare gli host con un widget vuoto.

{
    "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"
    }
}

La proprietà del $host.isWebSupported modello indica se l'host supporta il contenuto Web. Usarlo quando è necessario adattare ulteriormente la presentazione di fallback. Per informazioni dettagliate, vedere Proprietà dell'host del widget di Windows.

Gestire le richieste di risorse

I provider di widget possono specificare una stringa di filtro delle richieste Web per un widget nell'attributo WebRequestFilter dell'elemento Definition nel file manifesto del pacchetto del provider. Ogni volta che il contenuto del widget richiede una risorsa per URI che corrisponde al filtro, la richiesta verrà intercettata e reindirizzata all'implementazione del provider di widget di IWidgetResourceProvider.OnResourceRequested.

Il pattern di filtro usa il formato descritto in Pattern di corrispondenza. Usare Punycode , se necessario. Il filtro deve corrispondere all'origine specificata da webUrl. Le richieste per tutti i tipi di contenuto vengono reindirizzate quando corrispondono, quindi limitare il filtro alle risorse gestite dal provider. Per informazioni dettagliate, vedere Formato XML del manifesto del pacchetto del provider di widget.

Per gestire le richieste di risorse, i provider di widget devono implementare l'interfaccia IWidgetResourceProvider .

internal class WidgetProvider : IWidgetProvider, IWidgetResourceProvider

In OnResourceRequested impostare WidgetResourceRequestedArgs.Response su un WidgetResourceResponse contenente la risorsa. Questo esempio esegue il mapping di un URL richiesto a un'immagine in pacchetto. Includere Assets\image.png come contenuto nel pacchetto dell'app. RandomAccessStreamReference.CreateFromUri supporta lo schema ms-appx, quindi è possibile creare il riferimento al flusso senza attendere una ricerca di file.

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;
    }
}

Questo esempio sincrono non richiede un rinvio. Se l'implementazione attende il completamento di un'operazione prima di impostare la risposta, chiamare GetDeferral prima che il callback restituisca e completarlo in un blocco finally. Gestire e segnalare guasti asincroni in base ai criteri di gestione degli errori dell'app.

Se non si imposta una risposta, il sistema recupera la risorsa dal Web. È possibile modificare WidgetResourceRequest.Headers in args.Request prima di tale recupero. Aggiungere credenziali solo alle richieste di origini attendibili; una corrispondenza di filtro da sola non autorizza l'invio di un token.

Gestire i messaggi da e verso il contenuto Web

Per ricevere messaggi stringa dal contenuto del widget pubblicato usando il metodo JavaScript window.chrome.webview.postMessage , i provider di widget possono implementare l'interfaccia IWidgetProviderMessage e implementare il metodo OnMessageReceived .

internal class WidgetProvider : IWidgetProvider, IWidgetProviderMessage

Aggiungere il callback alla classe del provider:

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

Inviare un messaggio al contenuto Web di un widget con WidgetManager.SendMessageToContent. Passare l'ID istanza del widget da WidgetContext.Id, non dall'ID definizione del manifest del pacchetto. Più istanze di una definizione hanno ID istanza diversi.

Chiamare l'helper seguente da un callback del provider, passando widgetContext per l'istanza di destinazione, ad esempio il contesto ricevuto da CreateWidget o OnActionInvoked. Serializzare messaggi strutturati anziché costruire JSON con interpolazione di stringhe, pertanto i valori contenenti virgolette o barre rovesciata rimangono validi.

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);
}

Il contenuto Web riceve il messaggio come stringa tramite l'evento di window.chrome.webviewmessage. Se serializzi JSON come in questo esempio, analizza la stringa nel contenuto Web. Per informazioni dettagliate, vedere PostWebMessageAsString e webView2 API JavaScript.

Limitazioni e requisiti

Importante

Questa funzionalità è disponibile solo per gli utenti dello Spazio economico europeo (SEE).

Percorsi di implementazione correlati

I provider di widget Web non sono provider di feed. Per i feed di dashboard e i relativi requisiti a livello di area, vedere Dashboard e provider di feed. Per il percorso di implementazione separato del manifest PWA e del service worker, vedere Creare widget basati su PWA.