Тип QML WebEngineView

Компонент WebEngineView отображает веб-содержимое в приложении QML. Подробнее...

• Список всех членов, включая унаследованные

Свойства

• ErrorDomain : перечисление
• Feature : перечисление
• FindFlags : перечисление
• JavaScriptConsoleMessageLevel : перечисление
• LoadStatus : перечисление
• NewViewDestination : перечисление
• RenderProcessTerminationStatus : перечисление
• WebAction : перечисление
• activeFocusOnPress : bool
• backgroundColor : bool
• canGoBack : bool
• canGoForward : bool
• icon : url
• isFullScreen : bool
• loadProgress : int
• loading : bool
• navigationHistory : WebEngineHistory
• profile : WebEngineProfile
• settings : WebEngineSettings
• title : string
• url : url
• userScripts : list<WebEngineScript>
• webChannel : QQmlWebChannel
• zoomFactor : real

Сигналы

• activeFocusOnPressChanged(bool activeFocusOnPress)
• backgroundColorChanged()
• certificateError(WebEngineCertificateError error)
• featurePermissionRequested(url securityOrigin, Feature feature)
• fullScreenRequested(WebEngineFullScreenRequest request)
• javaScriptConsoleMessage(JavaScriptConsoleMessageLevel level, string message, int lineNumber, string sourceID)
• linkHovered(url hoveredUrl)
• loadingChanged(WebEngineLoadRequest loadRequest)
• newViewRequested(WebEngineViewRequest request)
• renderProcessTerminated(RenderProcessTerminationStatus terminationStatus, int exitCode)
• windowCloseRequested()

Методы

• void findText(string subString, FindFlags options, variant resultCallback)
• void findText(string subString, FindFlags options)
• void findText(string subString)
• void fullScreenCancelled()
• void goBack()
• void goBackOrForward(int offset)
• void goForward()
• void grantFeaturePermission(url securityOrigin, Feature feature, bool granted)
• void loadHtml(string html, url baseUrl)
• void reload()
• void reloadAndBypassCache()
• void runJavaScript(string script, variant callback)
• void setActiveFocusOnPress(bool arg)
• void stop()
• void triggerWebAction(WebAction action)

Подробное описание

Тип WebEngineView позволяет приложениям QML отображать области динамического веб-содержимого. Он может совместно использовать экран с другими типами QML, такими как TabView, или заполнять весь экран, как указано в приложении QML.

Инициализация Web Engine

Для того, чтобы представление веб-движка было отображено, веб-движок должен быть инициализирован с помощью QtWebEngine::initialize в основном файле приложения, как показано в следующем фрагменте кода:

int main(int argc, char *argv[])
{
    QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);
    QGuiApplication app(argc, argv);

    QtWebEngine::initialize();

    QQmlApplicationEngine engine;
    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));

    return app.exec();
}

Загрузка веб-страниц

Приложение может загружать страницы в WebEngineView, используя либо свойство url, либо метод loadHtml, и переходить по истории сеанса представления. Метод GET всегда используется для загрузки URL-адресов.

История представлена моделью данных WebEngineHistory, которая хранится в свойстве navigationHistory.

В следующем примере приложения QML загружается веб-страница, используя свойство url:

import QtQuick 2.0
import QtQuick.Window 2.0
import QtWebEngine 1.0

Window {
    width: 1024
    height: 750
    visible: true
    WebEngineView {
        anchors.fill: parent
        url: "http://www.qt.io"
    }
}

Свойство loading указывает, загружается ли в данный момент HTML-страница. Сигнал loadingChanged() генерируется, когда загрузка страницы начинается, заканчивается или завершается неудачей.

Заголовок HTML-страницы можно получить с помощью свойства title. Кроме того, веб-страница может указать значок, который можно получить, используя свойство icon. Свойство zoomFactor позволяет изменять масштаб содержимого веб-страницы.

Если при загрузке веб-страницы возникает ошибка сертификата, генерируется сигнал certificateError(). Ошибки сертификатов обрабатываются с помощью методов типа WebEngineCertificateError.

Взаимодействие

По умолчанию ссылки на разные страницы загружаются в том же объекте WebEngineView, но веб-сайты могут запросить их открытие в новой вкладке, окне или диалоговом окне. Сигнал newViewRequested() генерируется, когда поступит запрос на загрузку страницы в отдельном представлении веб-движка. Свойство NewViewDestination описывает, как должно быть открыто новое представление. Кроме того, для загрузки веб-страниц в отдельных представлениях веб-движка можно использовать утилиту типа WebEngineNewViewRequest.

Метод findText() может использоваться для поиска строки на веб-странице, используя параметры, описанные в FindFlags.

Метод setActiveFocusOnPress() может использоваться для создания элемента пользовательского интерфейса, который не должен получать фокус. Это может быть полезно в гибридном пользовательском интерфейсе.

Сигнал linkHovered() генерируется, когда указатель мыши перемещается над ссылкой и, следовательно, соответствует событию mouseover DOM.

Действия, такие как выделение и редактирование содержимого, могут выполняться на веб-странице с помощью метода triggerWebAction(). Доступные действия описаны в свойстве WebAction.

Сигнал backgroundColorChanged() генерируется, когда меняется цвет фона веб-страницы.

Скрипты пользователя

При загрузке страницы, так называемые скрипты пользователя могут быть внедрены в движок JavaScript в различные моменты. Объекты скриптов, прикреплённые к представлению веб-движка, хранятся в свойстве userScripts и внедряются с помощью типа WebEngineScript. Скрипты также могут быть выполнены с помощью метода runJavaScript() в том же контексте, что и другие скрипты, являющиеся частью загруженного сайта.

Свойство webChannel может использоваться для экспонирования экземпляра WebChannel в контексте JavaScript страницы, которую он отображает, как qt.webChannelTransport.

Режим полноэкранного отображения

Веб-страница может запросить через API JavaScript загрузку в полноэкранном режиме. Сигнал fullScreenRequested() генерируется, когда веб-страница отправляет запрос. Утилита типа WebEngineFullScreenRequest может использоваться для переключения запросов полноэкранного режима. Метод fullScreenCancelled может использоваться для уведомления движка браузера, когда система оконного интерфейса заставляет приложение выйти из полноэкранного режима.

Профили

Представления веб-движка могут быть изолированы друг от друга с помощью типа WebEngineProfile. Профиль содержит настройки, скрипты и список посещённых ссылок, общих для всех представлений, принадлежащих к профилю. Например, можно создать отдельный профиль для режима инкогнито. Текущий профиль для представления хранится в свойстве profile, а текущие настройки — в свойстве settings. Настройки задаются с помощью типа WebEngineSettings.

Функциональные возможности платформы

Веб-страницы могут запрашивать доступ к функциональным возможностям платформы, таким как геолокация или устройства захвата аудио и видео. Сигнал featurePermissionRequested() генерируется, когда веб-страница запрашивает использование ресурса. Поддерживаемые функциональные возможности платформы описаны в свойстве Feature. Если пользователи предоставят разрешение, метод grantFeaturePermission() используется для установки значения разрешено.

Вывод на OpenGL поверхность

При использовании QQuickRenderControl для отрисовки пользовательского интерфейса Qt Quick на поверхность OpenGL, тип WebEngineView не отображается правильно. Представление веб-движка пытается использовать глобальный контекст OpenGL, созданный функцией QtWebEngine::initialize, но нет публичного API для доступа к этому контексту, чтобы поделиться им с контекстом QQuickRenderControl.

Для правильного отображения представления веб-движка можно вручную создать новый контекст вне экрана, который будет совместно использоваться с QQuickRenderControl, и вызвать непубличную функцию qt_gl_set_global_share_context(), вместо вызова initialize(). Если initialize() будет вызван после установки глобального контекста, он ничего не сделает.

Документация свойств

ErrorDomain : перечисление

Описывает различные типы ошибок высокого уровня:

Feature : перечисление

Описывает категории доступа к функциональным возможностям платформы, к которым пользователю может быть предложено предоставить или запретить доступ:

См. также featurePermissionRequested() и grantFeaturePermission().

FindFlags : перечисление

Описывает параметры, доступные для функции findText(). Параметры могут быть объединены по битовому ИЛИ из следующего списка:

См. также findText().

JavaScriptConsoleMessageLevel : перечисление

Указывает на уровень важности сообщения консоли JavaScript:

LoadStatus : перечисление

Отражает статус загрузки страницы:

NewViewDestination : перечисление

Описывает, как открыть новое представление:

См. также WebEngineNewViewRequest.destination.

RenderProcessTerminationStatus : перечисление

Описывает состояние завершения процесса рендеринга:

Это свойство QML было добавлено в QtWebEngine 1.2.

WebAction : перечисление

Описывает типы действий, которые могут быть выполнены над веб-страницей:

Это свойство QML было добавлено в QtWebEngine 1.2.

activeFocusOnPress : bool

Указывает, должен ли вид получать активный фокус при нажатии. Значение по умолчанию — true.

Это свойство QML было добавлено в QtWebEngine 1.2.

backgroundColor : bool

Изменяет цвет фона WebEngineView за телом документа. Может быть установлен на "transparent" или на полупрозрачный цвет, чтобы видеть сквозь документ или чтобы соответствовать веб-контенту в гибридном приложении, предотвращая вспышки белого цвета, которые могут появляться во время загрузки.

Значение по умолчанию — белый.

Это свойство QML было добавлено в QtWebEngine 1.2.

[только для чтения] canGoBack : bool

Возвращает true если существуют предыдущие записи истории сеанса, false в противном случае.

[только для чтения] canGoForward : bool

Возвращает true если существуют последующие записи истории сеанса, false в противном случае.

[только для чтения] icon : url

Расположение значка текущего веб-сайта, также известного как favicon или значок ярлыка. Этот URL только для чтения соответствует изображению, используемому в приложении мобильного браузера для представления закладки на главном экране устройства.

Следующий фрагмент кода использует свойство icon для создания компонента Image:

Image {
    id: appIcon
    source: webView.icon != "" ? webView.icon : "fallbackFavIcon.png";
    // ...
}

[только для чтения] isFullScreen : bool

Возвращает true если веб-просмотр находится в полноэкранном режиме, false в противном случае.

Это свойство QML было добавлено в QtWebEngine 1.1.

См. также fullScreenRequested() и fullScreenCancelled().

[только для чтения] loadProgress : int

Количество данных страницы, загруженное в виде целого процента в диапазоне от 0 до 100.

[только для чтения] loading : bool

Возвращает true если страница HTML загружается в данный момент, false в противном случае.

[только для чтения] navigationHistory : WebEngineHistory

История навигации текущего вида.

Это свойство QML было добавлено в QtWebEngine 1.1.

См. также WebEngineHistory.

profile : WebEngineProfile

Текущий профиль, используемый для просмотра.

Это свойство QML было добавлено в QtWebEngine 1.1.

См. также WebEngineProfile.

[только для чтения] settings : WebEngineSettings

Настройки, используемые этим видом.

Это свойство QML было добавлено в QtWebEngine 1.1.

См. также WebEngineSettings.

[только для чтения] title : string

Заголовок текущей отображаемой страницы HTML. Это значение только для чтения, отражающее содержимое тега <title>.

url : url

Расположение текущей отображаемой HTML-страницы. Это изменяемое свойство предоставляет основной интерфейс для загрузки страницы в веб-просмотр. Оно работает так же, как свойство window.location DOM.

См. также loadHtml().

[только для чтения] userScripts : list<WebEngineScript>

Список объектов скриптов, прикреплённых к просмотру.

Это свойство QML было добавлено в QtWebEngine 1.1.

См. также WebEngineScript.

webChannel : QQmlWebChannel

Экземпляр канала веб-соединения, используемый этим видом. Этот канал автоматически использует внутренний механизм транспортировки QtWebEngine через Chromium IPC и экспонирован в контексте JavaScript страницы, которую он рендерит, как qt.webChannelTransport. Этот объект транспорта используется при создании JavaScript-аналога QWebChannel с использованием Qt WebChannel JavaScript API.

Примечание: Вид не принимает на себя ответственность за назначенный объект webChannel.

Это свойство QML было добавлено в QtWebEngine 1.1.

zoomFactor : real

Коэффициент масштабирования для просмотра. Действительные значения находятся в диапазоне от 0.25 до 5.0 . Значение по умолчанию — 1.0.

Это свойство QML было добавлено в QtWebEngine 1.1.

Документация по сигналам

activeFocusOnPressChanged(bool activeFocusOnPress)

Этот сигнал подаётся, когда изменяется возможность веб-вида получать фокус при нажатии.

Этот QML-сигнал был добавлен в QtWebEngine 1.2.

См. также setActiveFocusOnPress().

backgroundColorChanged()

Этот сигнал испускается при изменении цвета фона области просмотра веб-движка.

Этот QML-сигнал был представлен в QtWebEngine 1.2.

certificateError(WebEngineCertificateError error)

Этот сигнал испускается при возникновении ошибки недействительного сертификата во время загрузки заданного запроса.

Ошибка сертификата может быть обработана с помощью методов типа WebEngineCertificateError.

Этот QML-сигнал был представлен в QtWebEngine 1.1.

featurePermissionRequested(url securityOrigin, Feature feature)

Этот сигнал испускается, когда веб-сайт, идентифицированный по securityOrigin, запрашивает использование ресурса или устройства, идентифицированного по feature.

Этот QML-сигнал был представлен в QtWebEngine 1.1.

См. также grantFeaturePermission().

fullScreenRequested(WebEngineFullScreenRequest request)

Этот сигнал испускается, когда веб-страница запрашивает полноэкранный режим через JavaScript-API.

Этот QML-сигнал был представлен в QtWebEngine 1.1.

См. также isFullScreen.

javaScriptConsoleMessage(JavaScriptConsoleMessageLevel level, string message, int lineNumber, string sourceID)

Этот сигнал испускается, когда JavaScript-программа пытается вывести message в консоль веб-браузера.

Например, в случае ошибок вычисления исходный URL может быть указан в sourceID, а также lineNumber.

level указывает степень серьезности события, вызвавшего сообщение, то есть, было ли оно вызвано ошибкой или менее серьезным событием.

Если обработчик не указан, просмотрщик будет регистрировать сообщения в js категории регистрации.

См. также Ведение журнала консоли.

linkHovered(url hoveredUrl)

В пользовательском интерфейсе, управляемом мышью, этот сигнал испускается, когда указатель мыши проходит над ссылкой, соответствующей mouseover DOM-событию. Это событие также может возникать в сенсорных интерфейсах для mouseover событий, которые не отменены preventDefault(). hoveredUrl предоставляет расположение ссылки.

loadingChanged(WebEngineLoadRequest loadRequest)

Этот сигнал испускается, когда начало загрузки страницы, ее окончание или ошибка.

При обработке сигнала с onLoadingChanged, доступны различные параметры только для чтения в loadRequest:

См. также loading, LoadStatus и ErrorDomain.

newViewRequested(WebEngineViewRequest request)

Этот сигнал испускается, когда загрузка страницы запрашивается в отдельном окне веб-движка. Это может быть вызвано тем, что текущая страница явно запросила это через вызов JavaScript в window.open, или потому что пользователь щелкнул по ссылке, удерживая Shift, Ctrl или встроенную комбинацию, которая запускает открытие страницы в новом окне.

Если этот сигнал не обработан, запрошенная загрузка завершится ошибкой.

Пример реализации:

QtObject {
    id: windowParent
    // Create the initial browsing windows and open the startup page.
    Component.onCompleted: {
        var firstWindow = windowComponent.createObject(windowParent)
        firstWindow.webView.loadHtml('<input type="button" value="Click!" onclick="window.open(&quot;http://qt.io&quot;)">')
    }

    property Component windowComponent: Window {
        // Destroy on close to release the Window's QML resources.
        // Because it was created with a parent, it won't be garbage-collected.
        onClosing: destroy()
        visible: true

        property WebEngineView webView: webView_
        WebEngineView {
            id: webView_
            anchors.fill: parent

            // Handle the signal. Dynamically create the window and
            // use its WebEngineView as the destination of our request.
            onNewViewRequested: {
                var newWindow = windowComponent.createObject(windowParent)
                request.openIn(newWindow.webView)
            }
        }
    }
}

Этот QML-сигнал был представлен в QtWebEngine 1.1.

См. также NewViewDestination и Веб-движок Quick Nano Браузер.

renderProcessTerminated(RenderProcessTerminationStatus terminationStatus, int exitCode)

Этот сигнал испускается, когда процесс отрисовки завершается с ненулевым выходным статусом. terminationStatus — это статус завершения процесса, а exitCode — код состояния, с которым процесс завершился.

Этот QML-сигнал был представлен в QtWebEngine 1.2.

См. также RenderProcessTerminationStatus.

windowCloseRequested()

Этот сигнал испускается всякий раз, когда страница запрашивает закрытие окна веб-браузера, например, через JavaScript window.close() вызов.

Этот QML-сигнал был представлен в QtWebEngine 1.2.

Документация по методам

void findText(string subString, FindFlags options, variant resultCallback)

Ищет указанную строку subString на странице с использованием заданных options.

Для очистки выделения поиска просто передайте пустую строку.

resultCallback должен принимать булевый параметр. Он будет вызываться со значением true, если subString найдена; в противном случае значение обратного вызова будет false.

findText("Qt", WebEngineView.FindCaseSensitively, function(success) {
    if (success)
        console.log("Qt was found!");
});

Этот QML-метод был представлен в QtWebEngine 1.1.

void findText(string subString, FindFlags options)

Ищет указанную строку subString на странице с использованием заданных options.

Для очистки выделения поиска просто передайте пустую строку.

findText("Qt", WebEngineView.FindBackward | WebEngineView.FindCaseSensitively);

Этот QML-метод был представлен в QtWebEngine 1.1.

void findText(string subString)

Ищет указанную строку subString на странице.

Для очистки выделения поиска просто передайте пустую строку.

Этот QML-метод был представлен в QtWebEngine 1.1.

void fullScreenCancelled()

Немедленно устанавливает isFullScreen свойство в false. Он может использоваться для уведомления движка браузера, когда система оконного интерфейса вынуждает приложение выйти из полноэкранного режима.

ApplicationWindow {
    onVisibilityChanged: {
        if (webEngineView.isFullScreen && visibility != Window.FullScreen)
            webEngineView.fullScreenCancelled()
    }

    WebEngineView {
        id: webEngineView
        // ...
    }
}

Этот QML-метод был представлен в QtWebEngine 1.1.

См. также isFullScreen и fullScreenRequested().

void goBack()

Перейти назад в истории сеанса браузера, если возможно. Эта функция эквивалентна window.history.back() DOM-методу.

См. также canGoBack.

void goBackOrForward(int offset)

Если offset положительный, переходит вперёд на указанное количество страниц в текущей истории сеанса. Если offset отрицательный, переходит назад. Если смещение неверно, страница не изменяется.

Этот QML-метод был представлен в QtWebEngine 1.1.

См. также goBack() и goForward().

void goForward()

Перейти вперёд в истории сеанса браузера, если возможно. Эта функция эквивалентна window.history.forward() DOM-методу.

void grantFeaturePermission(url securityOrigin, Feature feature, bool granted)

Устанавливает или отменяет разрешение, в зависимости от granted, для веб-сайта, идентифицированного по securityOrigin, использовать feature.

Этот QML-метод был представлен в QtWebEngine 1.1.

См. также featurePermissionRequested().

void loadHtml(string html, url baseUrl)

Загружает указанный html как содержимое веб-представления.

Этот метод предлагает альтернативу более низкого уровня свойству url, которое ссылается на HTML-страницы через URL.

Внешние объекты, такие как таблицы стилей или изображения, на которые ссылается HTML-документ, должны находиться относительно baseUrl. Например, если html получен из http://www.example.com/documents/overview.html, которое является базовым URL, то изображение, на которое ссылается относительный URL diagram.png, должно находиться по адресу http://www.example.com/documents/diagram.png.

См. также url.

void reload()

Перезагружает текущую страницу. Эта функция эквивалентна методу window.location.reload() DOM.

См. также reloadAndBypassCache().

void reloadAndBypassCache()

Перезагружает текущую страницу, игнорируя кешированные данные.

Этот метод QML был добавлен в QtWebEngine 1.1.

См. также reload().

void runJavaScript(string script, variant callback)

Выполняет указанный script в содержимом веб-вью.

В случае предоставления функции обратного вызова, она будет вызвана после завершения выполнения скрипта.

runJavaScript("document.title", function(result) { console.log(result); });

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

Предупреждение: Не выполняйте длительные операции в функции обратного вызова, так как это может заблокировать отображение веб-содержимого.

См. WebEngineView::userScripts для альтернативного API для вставки скриптов.

void setActiveFocusOnPress(bool arg)

Устанавливает активный фокус на нажатие веб-движка, если arg равно true. Установив его в значение false, веб-движок может использоваться для создания элемента пользовательского интерфейса, который не должен получать фокус. Это может быть полезно в гибридном пользовательском интерфейсе.

Этот метод QML был добавлен в QtWebEngine 1.2.

См. также activeFocusOnPressChanged().

void stop()

Останавливает загрузку текущей страницы.

void triggerWebAction(WebAction action)

Вызывает веб-действие action.

Этот метод QML был добавлен в QtWebEngine 1.2.

См. также WebAction.