Поставщики веб-мини-приложений

Вы можете заполнить виджет Windows HTML-контентом, получаемым по URL-адресу, а не определять его содержимое с помощью Adaptive Cards. Ваш поставщик по-прежнему предоставляет JSON-пакет адаптивной карточки, указывающий URL-адрес содержимого. Начните с реализации поставщика виджета в приложение для Windows C# или реализации поставщика виджета в приложении win32 (C++/WinRT), а затем добавьте возможности веб-содержимого, описанные здесь.

API-интерфейсы ресурсов и обмена сообщениями, описанные в этой статье, были представлены в Windows App SDK 1.6.3. Используйте поддерживаемый на данный момент стабильный выпуск из каналов выпуска Windows App SDK и проверьте на устройстве Windows 11 с хостом мини-приложения, поддерживающим веб-содержимое.

Примеры C# — это фрагменты для поставщика упакованных виджетов рабочего стола. Добавьте using Microsoft.Windows.Widgets.Providers; и using Windows.Storage.Streams; в исходный файл поставщика. Продолжайте реализовывать IWidgetProvider при добавлении IWidgetResourceProvider или IWidgetProviderMessage.

Укажите URL-адрес содержимого

Отправьте полезную нагрузку JSON с помощью метода WidgetManager.UpdateWidget. Укажите объект метаданных с полем webUrl , которое указывает на HTML-содержимое. Включите body адаптивной карточки в качестве резервного содержимого для узлов, которые не поддерживают загрузку веб-содержимого, а не оставляйте эти узлы с пустым мини-виджетом.

{
    "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 указывает, поддерживает ли хост веб-содержимое. Используйте его, когда необходимо дополнительно адаптировать резервное представление. Дополнительные сведения см. в разделе свойства хоста мини-приложений Windows.

Обработка запросов ресурсов

Поставщики мини-приложений могут указать строку фильтра веб-запроса для мини-приложения в атрибуте WebRequestFilter элемента Definition в файле манифеста пакета поставщика. Когда содержимое мини-приложения запрашивает ресурс по URI, который соответствует фильтру, запрос будет перехвачен и перенаправлен на реализацию поставщика мини-приложений IWidgetResourceProvider.OnResourceRequested.

Шаблон фильтра использует формат, описанный в Match Patterns. При необходимости используйте Punycode . Фильтр должен соответствовать источнику веб-страницы, указанному в webUrl. Запросы для всех типов контента перенаправляются, если они соответствуют фильтру, поэтому ограничьте фильтр ресурсами, которые поддерживает ваш поставщик. Дополнительные сведения см. в формате XML манифеста пакета поставщика Widget.

Для обработки запросов ресурсов поставщики мини-приложений должны реализовать интерфейс IWidgetResourceProvider .

internal class WidgetProvider : IWidgetProvider, IWidgetResourceProvider

В OnResourceRequested задайте WidgetResourceRequestedArgs.Response значение WidgetResourceResponse, содержащее ресурс. В этом примере сопоставляется один запрошенный URL-адрес с упакованным изображением. Включите Assets\image.png в качестве содержимого в пакет приложения. RandomAccessStreamReference.CreateFromUri поддерживает схему ms-appx , поэтому можно создать ссылку на поток без ожидания поиска файла.

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

В этом синхронном примере не требуется отложенная операция. Если реализация ожидает завершения асинхронной операции перед установкой ответа, вызовите GetDeferral до возврата обратного вызова и завершите его в блоке finally. Обрабатывайте и сообщайте об асинхронных сбоях в соответствии с политикой обработки ошибок приложения.

Если ответ не задан, система извлекает ресурс из Интернета. Вы можете изменить WidgetResourceRequest.Headers в args.Request до этого получения. Только добавьте учетные данные в запросы к источникам origin, которым вы доверяете; сопоставление фильтров не является авторизацией для отправки токена.

Обработка сообщений к веб-содержимому и от него

Чтобы получать строковые сообщения из содержимого мини-приложения, размещенного с помощью метода window.chrome.webview.postMessage JavaScript, поставщики мини-приложений могут реализовать интерфейс IWidgetProviderMessage и реализовать метод OnMessageReceived .

internal class WidgetProvider : IWidgetProvider, IWidgetProviderMessage

Добавьте обратный вызов в класс поставщика:

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

Отправьте сообщение веб-содержимому мини-приложения с помощью WidgetManager.SendMessageToContent. Передайте идентификатор экземпляра мини-приложения из WidgetContext.Id, а не идентификатор определения из манифеста пакета. Несколько экземпляров одного определения имеют разные идентификаторы экземпляров.

Вызовите следующий вспомогательный метод из обратного вызова поставщика, передав WidgetContext для целевого экземпляра, например контекст, полученный в CreateWidget или OnActionInvoked. Сериализуйте структурированные сообщения, а не создавайте JSON с интерполяцией строк, поэтому значения, содержащие кавычки или обратные косые черты, остаются допустимыми.

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

Веб-содержимое получает сообщение в виде строки через событие объекта window.chrome.webviewmessage. При сериализации JSON, как в этом примере, разберите строку в веб-содержимом. Дополнительные сведения см. в статье PostWebMessageAsString и JavaScript API WebView2.

Ограничения и требования

Important

Эта функция доступна только пользователям в Европейской экономической зоне (EEA).

Поставщики веб-мини-приложений не являются поставщиками веб-каналов. Сведения о каналах панели мониторинга и региональных требованиях к ним см. в разделе «Панели мониторинга» и «Поставщики веб-каналов». Сведения об отдельном пути реализации манифеста PWA и service worker см. в разделе «Сборка виджетов на основе PWA».

  • Последнее обновление: