Penyedia widget web

Anda dapat mengisi widget Windows dengan HTML yang disajikan dari URL alih-alih menentukan isinya dengan Kartu Adaptif. Penyedia Anda masih menyediakan payload JSON Adaptive Card yang menentukan URL konten. Mulailah dengan Menerapkan penyedia widget di C# Windows App atau Menerapkan penyedia widget di aplikasi win32 (C++/WinRT), lalu tambahkan kemampuan konten web yang dijelaskan di sini.

API sumber daya dan olahpesan dalam artikel ini diperkenalkan di SDK Aplikasi Windows 1.6.3. Gunakan rilis stabil yang saat ini didukung dari saluran rilis SDK Aplikasi Windows, dan uji pada perangkat Windows 11 dengan host widget yang mendukung konten web.

Contoh C# adalah fragmen untuk penyedia widget desktop terpaket. Tambahkan using Microsoft.Windows.Widgets.Providers; dan using Windows.Storage.Streams; ke file sumber penyedia. Terus terapkan IWidgetProvider saat Anda menambahkan IWidgetResourceProvider atau IWidgetProviderMessage.

Tentukan URL konten

Kirim payload JSON Anda dengan WidgetManager.UpdateWidget. Tentukan objek metadata dengan bidang webUrl yang menunjuk ke konten HTML. Sertakan isi Kartu Adaptif sebagai konten fallback untuk host yang tidak mendukung pemuatan konten web, daripada meninggalkan host tersebut dengan widget kosong.

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

Properti $host.isWebSupported templat menunjukkan apakah host mendukung konten web. Gunakan saat Anda perlu menyesuaikan presentasi fallback lebih lanjut. Untuk detailnya, lihat properti host widget Windows.

Menangani permintaan sumber daya

Penyedia widget dapat menentukan string filter permintaan web untuk widget di atribut WebRequestFilter dari elemen Definisi dalam file manifes paket penyedia. Setiap kali konten widget meminta sumber daya oleh URI yang cocok dengan filter, permintaan akan dicegat dan dialihkan ke implementasi penyedia widget IWidgetResourceProvider.OnResourceRequested.

Pola filter menggunakan format yang dijelaskan dalam Pola Pencocokan. Gunakan Punycode jika perlu. Filter harus cocok dengan asal yang ditentukan oleh webUrl. Permintaan untuk semua jenis konten dialihkan ketika permintaan tersebut cocok, jadi batasi filter ke sumber daya yang ditangani penyedia Anda. Untuk detailnya, lihat Format XML manifes paket penyedia widget.

Untuk menangani permintaan sumber daya, penyedia widget harus menerapkan antarmuka IWidgetResourceProvider .

internal class WidgetProvider : IWidgetProvider, IWidgetResourceProvider

Di OnResourceRequested, atur WidgetResourceRequestedArgs.Response ke WidgetResourceResponse yang berisi sumber daya. Contoh ini memetakan satu URL yang diminta ke gambar yang dipaketkan. Sertakan Assets\image.png sebagai konten dalam paket aplikasi Anda. RandomAccessStreamReference.CreateFromUri mendukung skema ms-appx , sehingga Anda dapat membuat referensi aliran tanpa menunggu pencarian 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;
    }
}

Contoh sinkron ini tidak memerlukan deferral. Jika implementasi Anda menunggu pekerjaan sebelum mengatur respons, panggil GetDeferral sebelum callback selesai, dan selesaikan dalam blok finally. Menangani dan melaporkan kegagalan asinkron sesuai dengan kebijakan penanganan kesalahan aplikasi Anda.

Jika Anda tidak mengatur respons, sistem akan mengambil sumber daya dari web. Anda dapat memodifikasi WidgetResourceRequest.Headers di args.Request sebelum pengambilan itu. Hanya tambahkan kredensial ke permintaan untuk origin yang Anda percayai; kecocokan filter saja bukan otorisasi untuk mengirim token.

Menangani pesan ke dan dari konten web

Untuk menerima pesan string dari konten widget yang telah diposting menggunakan metode JavaScript window.chrome.webview.postMessage , penyedia widget dapat mengimplementasikan antarmuka IWidgetProviderMessage dan menerapkan metode OnMessageReceived .

internal class WidgetProvider : IWidgetProvider, IWidgetProviderMessage

Tambahkan callback ke kelas penyedia Anda:

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

Kirim pesan ke konten web widget dengan WidgetManager.SendMessageToContent. Teruskan ID instans widget dari WidgetContext.Id, bukan ID definisi dari manifes paket. Beberapa instans dari satu definisi memiliki ID instans yang berbeda.

Panggil fungsi helper berikut dari panggilan balik penyedia, dengan meneruskan WidgetContext untuk instans target, seperti konteks yang diterima oleh CreateWidget atau OnActionInvoked. Serialkan pesan terstruktur alih-alih membuat JSON dengan interpolasi string, sehingga nilai yang berisi tanda kutip atau garis miring terbalik tetap valid.

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

Konten web menerima pesan sebagai string melalui event window.chrome.webviewmessage. Jika Anda menserialisasikan JSON seperti dalam contoh ini, parse string tersebut di konten web Anda. Untuk detailnya, lihat PostWebMessageAsString dan JavaScript API WebView2.

Batasan dan persyaratan

Important

Fitur ini hanya tersedia untuk pengguna di European Economic Area (EEA).

Jalur implementasi terkait

Penyedia widget web bukan penyedia feed. Untuk umpan dasbor dan persyaratan regionalnya, lihat Dasbor dan penyedia umpan. Untuk manifes PWA terpisah dan jalur implementasi pekerja layanan, lihat Membangun widget berbasis PWA.