Web pencere öğesi sağlayıcıları

Windows pencere öğesini, gövdesini Uyarlamalı Kartlar ile tanımlamak yerine URL'den sunulan HTML ile doldurabilirsiniz. Sağlayıcınız yine de içerik URL'sini belirten bir Uyarlamalı Kart JSON yükü sağlar. C# Windows Uygulaması'te bir pencere öğesi sağlayıcısı uygulayın veya bir Win32 uygulamasında pencere öğesi sağlayıcısı uygulayın (C++/WinRT) ile başlayın ve burada açıklanan web içeriği özelliklerini ekleyin.

Bu makaledeki kaynak ve mesajlaşma API'leri Windows Uygulama SDK'sı 1.6.3'te sunulmuştur. Windows Uygulama SDK'sı yayın kanallarından şu anda desteklenen kararlı bir sürümü kullanın ve web içeriğini destekleyen bir widget ana bilgisayarıyla Windows 11 yüklü bir cihazda test edin.

C# örnekleri, paketlenmiş masaüstü widget sağlayıcısının parçalarıdır. using Windows.Storage.Streams; ve using Microsoft.Windows.Widgets.Providers; öğelerini sağlayıcının kaynak dosyasına ekleyin. IWidgetResourceProvider veya IWidgetProviderMessage eklediğinizde IWidgetProvider uygulamaya devam edin.

İçerik URL'sini belirtme

WidgetManager.UpdateWidget ile JSON yükünüzü gönderin. HTML içeriğine işaret eden bir webUrl alanı olan bir meta veri nesnesi belirtin. Bu konakları boş bir pencere öğesiyle bırakmak yerine web içeriğini yüklemeyi desteklemeyen konaklar için geri dönüş içeriği olarak Adaptive Card body ekleyin.

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

$host.isWebSupported Şablon özelliği, ana bilgisayarın web içeriğini destekleyip desteklemediğini gösterir. Yedek sunumu daha da uyarlamanız gerektiğinde kullanın. Ayrıntılar için bkz. Windows pencere öğesi konak özellikleri.

Kaynak isteklerini işleme

Pencere öğesi sağlayıcıları, sağlayıcının paket bildirim dosyasındaki Tanım öğesinin WebRequestFilter özniteliğindeki bir pencere öğesi için bir web isteği filtre dizesi belirtebilir. Pencere öğesi içeriği filtreyle eşleşen URI'ye göre bir kaynak istediğinde, istek durdurulur ve pencere öğesi sağlayıcısının IWidgetResourceProvider.OnResourceRequested uygulamasına yönlendirilir.

Filtre düzeni, Eşleştirme Desenleri'nde açıklanan biçimi kullanır. Gerektiğinde Punycode kullanın. Filtrenin webUrl tarafından belirtilen orijinle eşleşmesi gerekir. Tüm içerik türlerine yönelik istekler eşleştiğinde yeniden yönlendirilir, bu nedenle filtreyi sağlayıcınızın işlediği kaynaklarla sınırlayın. Ayrıntılar için bkz. Pencere öğesi sağlayıcı paketi bildirim XML biçimi.

Kaynak isteklerini işlemek için pencere öğesi sağlayıcılarının IWidgetResourceProvider arabirimini uygulaması gerekir.

internal class WidgetProvider : IWidgetProvider, IWidgetResourceProvider

OnResourceRequested içinde, WidgetResourceRequestedArgs.Response öğesini kaynağı içeren bir WidgetResourceResponse olarak ayarlayın. Bu örnek, istenen bir URL'yi paketlenmiş bir görüntüye eşler. Assets\image.png öğesini uygulama paketinizin içine içerik olarak ekleyin. RandomAccessStreamReference.CreateFromUri, ms-appx şemasını desteklediğinden, dosya aramasını beklemeden akış başvurusu oluşturabilirsiniz.

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

Bu eşzamanlı örnekte erteleme nesnesi gerekmez. Uygulamanız yanıtı ayarlamadan önce yapılacak işi bekletiyorsa, geri çağırma döndürmeden önce GetDeferral çağırın ve bunu bir finally blokta tamamlayın. Eşzamansız hataları uygulamanızın hata işleme ilkesine göre işleyin ve rapor edin.

Yanıt ayarlamazsanız sistem kaynağı web'den alır. Bu getirme işleminden önce, args.Request üzerinde WidgetResourceRequest.Headers'ı değiştirebilirsiniz. Yalnızca güvendiğiniz kaynaklara yönelik isteklere kimlik bilgileri ekleyin; yalnızca filtre eşleşmesi, belirteç gönderme yetkisi değildir.

Web içeriğine gelen ve web içeriğinden gelen iletileri işleme

Pencere öğesi içeriğinden window.chrome.webview.postMessage JavaScript yöntemi kullanılarak gönderilen dize iletilerini almak için, pencere öğesi sağlayıcıları IWidgetProviderMessage arabirimini uygulayabilir ve OnMessageReceived yöntemini uygulayabilir.

internal class WidgetProvider : IWidgetProvider, IWidgetProviderMessage

Sağlayıcı sınıfınıza geri çağırma ekleyin:

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

WidgetManager.SendMessageToContent ile bir widget'ın web içeriğine ileti gönderin. Paket bildirimindeki tanım kimliğini değil WidgetContext.Id pencere öğesi örneği kimliğini geçirin. Bir tanımın birden çok örneğinin farklı örnek kimlikleri vardır.

CreateWidget veya OnActionInvoked tarafından alınan bağlam gibi hedef örnek için WidgetContext'i geçirerek sağlayıcı geri aramasından aşağıdaki yardımcıyı çağırın. String enterpolasyonu ile JSON oluşturmak yerine yapılandırılmış iletileri seri hale getirerek tırnak işareti veya ters eğik çizgi içeren değerlerin geçerli kalmasını sağlayın.

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

Web içeriği, window.chrome.webviewmessage olayı aracılığıyla iletiyi dize olarak alır. JSON'ı bu örnekte olduğu gibi serileştirdiyseniz, web içeriğinizdeki dizeyi ayrıştırın. Ayrıntılar için bkz. PostWebMessageAsString ve WebView2 JavaScript API’si.

Sınırlamalar ve gereksinimler

Important

Bu özellik yalnızca Avrupa Ekonomik Alanı'ndaki (EEA) kullanıcılar tarafından kullanılabilir.

Web widget sağlayıcıları akış sağlayıcıları değildir. Gösterge paneli akışları ve bunların bölgesel gereksinimleri için bkz. Gösterge panelleri ve akış sağlayıcıları. Ayrı PWA manifesti ve service worker uygulama yolu için bkz. PWA temelli pencere öğeleri oluşturma.

  • Son güncelleştirme: