Qt WebEngine（04）：QWebEngineView 类【官翻】

一、前言

原文链接

QWebEngineView类提供了一个小部件，用于查看和编辑Web文档。

Header:	#include < QWebEngineView >
qmake:	QT += webenginewidgets
Since:	Qt 5.4
Inherits:	QWidget

二、详述

Web视图是Qt WebEngine Web浏览模块的主要窗口小部件组件。 可以在各种应用程序中使用它来实时显示Internet上的Web内容。

可以使用load()函数将网站加载到Web视图。 GET方法始终用于加载URL。

像所有Qt小部件一样，必须调用show()函数才能显示Web视图。 下面的代码段说明了这一点：

     QWebEngineView *view = new QWebEngineView(parent);
     view->load(QUrl("http://qt-project.org/"));
     view->show();

或者，可以使用setUrl()加载网站。如果您拥有随时可用的HTML内容，则可以使用setHtml()代替。

当视图开始加载时，将发出loadStarted()信号，并且每当Web视图的元素完成加载时，都会发出loadProgress()信号，例如嵌入式图像或脚本。完全加载视图后，将发出loadFinished()信号。它的参数true或false指示加载是成功还是失败。

page()函数返回一个指向网页对象的指针。一个QWebEngineView包含一个QWebEnginePage，它进而允许在页面上下文中访问QWebEngineHistory。

可以使用title()属性访问HTML文档的标题。此外，网站可以指定一个图标，可以使用icon()或使用iconUrl()属性访问其URL。如果标题或图标发生更改，将发出相应的titleChanged()，iconChanged()和iconUrlChanged()信号。通过使用zoomFactor()属性，可以按比例缩放网页内容。

该小部件具有适合于手边元素的上下文菜单，并包括在浏览器中有用的动作。对于自定义上下文菜单，或将动作嵌入菜单或工具栏中，可以通过pageAction()来使用各个动作。 Web视图维护返回的动作的状态，但允许修改动作属性，例如文本或图标。动作语义也可以通过triggerPageAction()直接触发。

如果要为允许用户打开新窗口（例如弹出窗口）的网站提供支持，则可以将QWebEngineView子类化并重新实现createWindow()函数。

另请参阅WebEngine窗口小部件简单浏览器示例，WebEngine内容操作示例和WebEngine Markdown编辑器示例。

三、属性

1. hasSelection: const bool
   此属性保存此页面是否包含所选内容。默认情况下，此属性为false。
2. icon: const QIcon
   此属性保存与当前查看的页面关联的图标。默认情况下，此属性包含一个空图标。
3. iconUrl: const QUrl
   此属性保存与当前查看的页面关联的图标的URL。默认情况下，此属性包含一个空URL。
4. selectedText: const QString
   此属性保存当前选定的文本。默认情况下，此属性包含一个空字符串。
5. title: const QString
   此属性保存HTML < title >元素定义的页面标题。等效于QWebEnginePage :: title()。
6. url: QUrl
   此属性保存当前查看的网页的URL。设置此属性将清除视图并加载URL。默认情况下，此属性包含一个空的无效URL。
7. zoomFactor:
   qreal此属性保存视图的缩放系数。有效值范围是0.25到5.0。 默认因子是1.0。

四、公共函数

1. QWebEngineView(QWidget *parent = Q_NULLPTR)
   构造函数

2. virtual ~QWebEngineView()
   析构函数

3. void findText(const QString &subString, QWebEnginePage::FindFlags options = QWebEnginePage::FindFlags(),
   const QWebEngineCallback< bool > &resultCallback = QWebEngineCallback< bool >() )
   使用给定的选项在页面中查找指定的字符串subString。要清除选择，只需传递一个空字符串。
   resultCallback必须采用布尔值参数。 如果找到subString，它将以true值调用； 否则，回调值将为false。
   警告：我们保证始终会调用回调（resultCallback），但是可以在销毁页面期间完成。 删除QWebEnginePage时，将使用无效值触发回调，并且在其中使用相应的QWebEnginePage或QWebEngineView实例并不安全。
   另请参见selectedText()和selectionChanged()。

4. bool hasSelection() const
   是否有选择内容

5. QWebEngineHistory * history() const
   返回指向导航网页视图历史的指针。
   它等效于： view-> page()-> history();

6. QIcon icon() const
   返回QIcon

7. QUrl iconUrl() const
   返回icon的URL

8. void load(const QUrl &url)
   加载并显示指定的URL。注意：在到达足够的数据以显示新URL之前，视图将保持不变。

9. void load(const QWebEngineHttpRequest &request)
   发出指定的请求并加载响应。

10. QWebEnginePage * page() const
    返回指向基础页面的指针。

11. QAction * pageAction(QWebEnginePage::WebAction action) const
    返回封装的Web Action指针

12. QString selectedText() const
    返回选择的内容的文本

13. void setContent(const QByteArray &data, const QString &mimeType = QString(), const QUrl &baseUrl = QUrl())
    将Web视图的内容设置为数据。 如果mimeType参数为空，则假定内容为text / plain，charset = US-ASCII。

    内容中引用的外部对象相对于baseUrl定位。 对于要加载的外部对象，baseUrl不能为空。

    数据立即加载； 外部对象是异步加载的。

14. void setHtml(const QString &html, const QUrl &baseUrl = QUrl())
    将Web视图的内容设置为指定的html内容。

    外部对象（例如HTML文档中引用的样式表或图像）相对于baseUrl定位。对于要加载的外部对象，baseUrl不能为空。例如，如果从基本URL http://www.example.com/documents/overview.html检索html，则使用相对URL diagram.png引用的图像应位于http：// www.example.com/documents/diagram.png。

    HTML文档将立即加载，而外部对象则异步加载。

    使用此方法时，除非另有说明，否则Qt WebEngine假定外部资源（例如JavaScript程序或样式表）均以UTF-8编码。例如，可以通过HTML脚本标签的charset属性指定外部脚本的编码。或者，可以由Web服务器指定编码。

    这是一个等效于setContent（html，“ text / html; charset = UTF-8”，baseUrl）的便利函数。

    警告：此功能仅适用于HTML。对于其他MIME类型（例如XHTML或SVG），应改用setContent()。

    注意：无法显示大于2 MB的内容，因为setHtml()会将提供的HTML转换为百分比编码并将数据：放在其前面以创建要导航到的URL。 从而，提供的代码将成为超出Chromium设置的2 MB限制的URL。 如果内容太大，则使用success = false触发loadFinished()信号。

15. void setPage(QWebEnginePage *page)
    使页面成为Web视图的新网页。

    提供的页面的父QObject仍然是对象的所有者。 如果当前页面是Web视图的子页面，则将其删除。

16. void setUrl(const QUrl &url)
    设置此属性将清除视图并加载URL。

17. QUrl url() const
    返回URL

18. void setZoomFactor(qreal factor)
    设置缩放系数

19. qreal zoomFactor() const
    返回缩放因子

20. QWebEngineSettings * settings() const
    返回指向视图或页面特定设置对象的指针。
    它等效于：
    view-> page()-> settings();

21. QString title() const
    等效于： QWebEnginePage::title().

22. void triggerPageAction(QWebEnginePage::WebAction action, bool checked = false)
    触发指定的动作。 如果这是可检查的操作，则假定为指定的检查状态。
    下面的示例触发复制操作，因此将所有选定的文本复制到剪贴板。
    view-> triggerPageAction（QWebEnginePage :: Copy）;
    另请参见pageAction()。

五、重新实现的公共函数

   1. virtual QSize  **sizeHint**() const override
      重新实现属性的访问功能：QWidget :: sizeHint

六、公共槽函数

1. void back()
   便捷插槽，用于通过导航链接构建的文档列表中的上一个文档。 如果没有以前的文档，则不执行任何操作。
   它等效于：
   view-> page()-> triggerAction（QWebEnginePage :: Back）;
   另请参见forward()和pageAction()。
2. void forward()
   便捷插槽，用于通过导航链接构建的文档列表中的下个文档。 如果没有下个文档，则不执行任何操作。
   它等效于：
   view-> page()-> triggerAction（QWebEnginePage :: Forward）;
   另请参见back()和pageAction()。
3. void reload()
   重新加载当前文档
4. void stop()方便插槽，可停止加载文档。
   它等效于：
   view-> page()-> triggerAction（QWebEnginePage :: Stop）;
   另请参见reload()，pageAction()和loadFinished()。

七、信号

1. void iconChanged(const QIcon &icon)
   当与视图关联的图标（“favicon”）更改时，将发出此信号。
2. void iconUrlChanged(const QUrl &url)
   当与视图关联的图标（“图标”）的URL更改时，将发出此信号。
3. void loadFinished(bool ok)
   页面加载完成后发出此信号。 ok将指示加载成功还是发生错误。
4. void loadProgress(int progress)
   每当Web视图中的某个元素完成加载（例如嵌入式图像或脚本）时，都会发出此信号。 因此，它跟踪加载Web视图的总体进度。
   当前值由progress提供，并从0到100缩放，这是QProgressBar的默认范围。
5. void loadStarted()
   当页面的新加载开始时，将发出此信号。
6. void renderProcessTerminated(QWebEnginePage::RenderProcessTerminationStatus terminationStatus, int exitCode)
   当渲染过程以非零退出状态终止时，将发出此信号。 终止状态是进程的终止状态，而退出代码是进程终止的状态代码。
7. void selectionChanged()
   选择更改时，将发出此信号。
   注意：当使用鼠标通过左键单击和拖动来选择文本时，将为选定的每个新字符发出信号，而不是在释放鼠标左键时发出信号。
8. void titleChanged(const QString &title)
   每当视图标题更改时，都会发出此信号。
9. void urlChanged(const QUrl &url)
   视图的URL更改时，将发出此信号。

八、保护函数

1. virtual QWebEngineView *createWindow(QWebEnginePage::WebWindowType type)

   每当QWebEnginePage页面想要创建给定类型的新窗口时，都会从关联的QWebEnginePage的createWindow()方法中调用此函数。 例如，当发出JavaScript请求以在新窗口中打开文档时。
   注意：如果重新实现了关联页面的createWindow()方法，则不会调用此方法，除非在重新实现中明确地这样做。

九、重新实现的受保护函数

都是一些常规的函数，如果要自定义，就自己去子类化实现

1. virtual void closeEvent(QCloseEvent *event) override
2. virtual void contextMenuEvent(QContextMenuEvent *event) override
3. virtual void dragEnterEvent(QDragEnterEvent *e) override
4. virtual void dragLeaveEvent(QDragLeaveEvent *e) override
5. virtual void dragMoveEvent(QDragMoveEvent *e) override
6. virtual void dropEvent(QDropEvent *e) override
7. virtual bool event(QEvent *ev) override
8. virtual void hideEvent(QHideEvent *event) override
9. virtual void showEvent(QShowEvent *event) override

10、总结

QWebEngineView 类从介绍来看，感觉并不难，如果实现一个简单的浏览器视图，应该不算太麻烦。下一章，先用QWebEngineView写一个简单的例子。