简介

这是《玩转QtQuick》系列文章的第二篇，主要是介绍Qt Quick的默认渲染器。

本文会涉及到一些图形学的基本概念，例如：材质、纹理、光栅化、图元等，建议参考相关资料，本文不做进一步的解释。

因为Qt官方文档写的比较全面，所以本文主要是对官方文档的翻译，同时会补充一些个人理解。

翻译主要参考Qt5.15的文档，适当做了一些调整，尽量信达雅，尽量说人话。

下面翻译开始

Qt Quick的默认渲染器

本文介绍默认渲染器在内部的工作方式，以方便开发者们以最佳的方式

使用它(编写代码)，包括性能和功能。

通常无需了解渲染器的内部结构，就能够获得良好的性能。

但是，在与场景图集成或弄清楚为什么无法从图形芯片中挤出最大效率时，这可能会有所帮助。

(即使在每个帧都是唯一的并且所有内容都是从头开始上传的情况下，默认渲染器也将表现良好)

Qml场景中的Item将填充QSGNode实例树。一旦实例树创建好之后，此树将完整描述如何渲染特定的帧。

它不会包含对任何Item的反向引用，并且在大多数平台上将通过单独的线程进行处理和渲染。

渲染器是“场景图”的自包含部分，它遍历QSGNode树，并使用QSGGeometryNode中定义

的几何形状和QSGMaterial中定义的着色器状态来更新图形状态并生成DrawCall。

如果有需要，可以使用内部的“场景图”后端API完全替换渲染器。

对于希望利用非标准硬件功能的平台供应商来说，这最为有趣。

对于大多数用例，默认渲染器就足够了。

默认渲染器着重于优化渲染的两种主要策略：批量处理调用和在GPU上保留几何图元。

批次渲染

传统的2D API (例如QPainter，Cairo或者Context2D)被设计为每帧处理大量单独的DrawCall,而当DrawCall的次数

非常少且状态更改保持在一定水平时，OpenGL和其它硬件加速的API表现最佳。

考虑以下用例：

绘制此列表的最简单方法是逐行进行。

首先，绘制背景。背景是特定颜色的矩形。在OpenGL术语中，这意味着使用一个着色器程序进行纯色填充，设置填充颜色，

设置包含x和y偏移量的转换矩阵，然后使用例如glDrawArrays绘制组成矩形的两个三角形。

接下来绘制图标。用OpenGL术语来说，这意味着使用一个着色器程序来绘制纹理，激活要使用的纹理，设置转换矩阵，启用alpha混合，

然后使用例如glDrawArrays绘制组成图标边界矩形的两个三角形。

行 之间的文本和分隔线遵循类似的模式。

对于列表中的每一行都重复此过程，因此对于更长的列表，OpenGL状态变更和DrawCall所带来的

开销完全超过了使用硬件加速API所能提供的好处。

当每个图元都很大时，此开销可以忽略不计，但是在典型的UI环境中，有许多小项加起来会产生相当大的开销。

默认的“场景图”渲染器也在这些限制内运行，并且会尝试将单个图元合并到批次中，同时保留完全相同的视觉效果。

结果是更少的OpenGL状态变更和最少的DrawCall调用，从而实现了最佳性能。

不透明图元

渲染器将不透明图元和需要透明度的图元进行了分类。

通过使用OpenGL的Z缓冲为每一个图元赋予唯一的z值，渲染器可以自由地对不透明图元进行重新排序，而无需考虑

它们在屏幕上的位置以及与它们重叠的其它元素。通过查看每个图元的材质状态，渲染器将创建不透明的批次渲染。

在QtQuick的主要Item中，属于不透明图元的包括不透明颜色的Rectangle和完全不透明的Image,主要是JPEG和BMP格式。

使用不透明图元的另一个好处是，不透明图元不需要启用GL_BLEND，这个操作可能会非常耗性能，尤其是在移动端和嵌入式GPU上。

不透明图元在启用glDepthMask和GL_DEPTH_TEST的情况下以从前到后的方式渲染。在内部进行early-z校验的GPU上，这意味着

片元着色器不需要针对被遮盖的像素或像素块运行。

请注意，渲染器仍需要考虑这些节点，并且顶点着色器仍将为这些图元的每个顶点运行，因此，如果应用程序知道某些东西被完全遮盖，则

最好的办法是设置Item::visible或Item::opacity隐藏它。

Item::z用来控制Item相对于其同级元素的“堆叠顺序”，它与渲染器和OpenGL的z缓冲没有直接关系。

Alpha混合图元

一旦绘制了不透明的图元，渲染器将禁用glDepthMask,启用GL_BLEND并以从后到前的方式渲染所有alpha混合图元。

alpha混合图元的批次渲染在渲染器内需要更多的工作，因为重叠的元素需要以正确的顺序进行渲染，以使alpha看起来正确。

仅仅依靠Z缓冲是不够的。渲染器在所有alpha混合图元上进行传递，除了其材质状态外，还将查询其边框，以确定哪些元素

可以批次渲染，哪些元素不能批次。

上图左边的情况，可以在一次DrawCall中渲染蓝色背景，而在另一次DrawCall中渲染两个文本元素，因为这些文本仅与其

同一层的背景重叠。

右边的情况，Item 4的背景覆盖了Item 3的背景，因此每一个背景和文本需要在不同的DrawCall中渲染。

在Z方向上，alpha节点与不透明节点交错，且在可用时触发early-z。同样的，将Item::visible设置为false会快很多。

混合3D图元

“场景图”支持伪3D和适当的3D图元。

例如，可以用ShaderEffect来实现“页面卷曲”效果，或者可以使用QSGGeometry和自定义材质来实现凹凸贴图。实现这

些功能时，开发者需要意识到默认渲染器已经使用了深度缓冲区。

渲染器修改了QSGMaterialShader::vertexShader()返回的顶点着色器，并在应用了模型视图和投影矩阵之后压缩了

顶点的z值，然后在z上添加了一个小平移以将其放置在正确的z位置。

压缩时会假定z值在0到1的范围内。

纹理集

激活的纹理在OpenGL中是个唯一的状态，这意味着使用不同纹理的多个图元无法批次渲染。因此，Qt Quick“场景图”允许

将多个QSGTexture实例分配为较大纹理的较小子区域，也就是“纹理集”。

纹理集的最大好处是多个QSGTexture实例引用同一个OpenGL纹理实例。这样还可以批量处理带纹理的DrawCall，例如

Qml中的Image,BorderImage,ShaderEffect等，以及C++中的QSGSimpleTextureNode和自定义

的QSGGeometryNode都使用了纹理。

尺寸过大的纹理不会进入纹理集。

纹理集使用带参数QQuickWindow::TextureCanUseAtlas的函数调用QQuickWindow::createTextureFromImage()创建。

纹理集没有范围从0到1的坐标。使用QSGTexture::normalizedTextureSubRect()获取纹理坐标。

“场景图”使用试探法来确定纹理集应该多大以及输入大小的阈值。如果需要不同的值，可以通过设置环境变量

QSG_ATLAS_WIDTH=[width], QSG_ATLAS_HEIGHT=[height]和QSG_ATLAS_SIZE_LIMIT=[size]来覆盖试探法。

对于平台供应商而言，更改这些数值通常是有趣的。

批次渲染的根节点

除了将兼容的图元合并到一个批次，默认渲染器还尝试将每帧需要发送到GPU的数据量减到最少。

默认渲染器会标记在一起的子树，并尝试将它们放入单独的批次中。

识别批次后，即可使用顶点缓冲对象将其合并，上传并存储在GPU内存中。

变换的节点

每个QtQuick中的Item会往场景树中插入一个QSGTransformNode来管理其x、y坐标、缩放比例。子Item会

附加在此变换节点之下。默认渲染器会跟踪帧之间变换节点的状态，并将查看子树以确定：变换节点作为一个

批次渲染的根节点是否良好。在帧之间变化且具有相当复杂的子树的变换节点可以成为批次渲染的根节点。

批次渲染根节点的子树中QSGGeometryNodes相对于CPU上的根节点已经预先转换过了，然后讲它们上传

并保留在GPU上。当变换发生时，渲染器仅需要更新根节点的矩阵，而无需更新每个单独的节点，从而使列表

和网格滚动非常快。对于连续的帧，只要不添加或删除节点，就可以快速地、不增加消耗地渲染。当新内容

进入子树时，将对其进行重建，但这仍然相当较快。

在Grid或List中滚动时，会有节点添加或者删除，但也总会有一些帧是不变的。

将变换节点 标记为 批次根节点的另一个好处是，它允许渲染器保留树中未更改的部分。

例如：UI由一个List和一行按钮 组成。滚动List并添加或删除Delegate时，UI的其余

部分(一行按钮)保持不变,可以使用存储在GPU上的几何图元进行绘制。

可以使用环境变量QSG_RENDERER_BATCH_NODE_THRESHOLD=[count]和QSG_RENDERER_BATCH_VERTEX_THRESHOLD=[count]来

覆盖要成为批次根节点的转换节点和顶点阈值。覆盖这些标志对平台供应商最有用。

在批次渲染根节点之下，会为每个唯一的材质状态集和几何图元类型创建一个批次节点。

裁剪

将Item::clip设置为true时，将创建一个QSGClipNode,其几何形状为矩形。

默认渲染器将通过在OpenGL中使用scissoring来应用此裁剪操作。如果将Item

旋转了非90°角，则使用OpenGL的模版缓冲区。QtQuick的Item仅支持通过Qml启用

矩形的裁剪，“场景图”API和渲染器则支持任何形状的裁剪。

将裁剪应用于子树时，该子树需要使用唯一的OpenGL状态进行渲染。这意味着当Item::clip

为true时，该Item的批次渲染仅限于其子Item。当有许多子级(例如ListView或GridView)或

复杂的子级(例如TextArea)时，这是好事。

应该避免在较小的Item上使用裁剪，因为它会阻止批次渲染。这包括Button上面的Label，TextField和Table中的Delegate。

顶点缓冲

每个批次渲染都会使用顶点缓冲区对象(VBO)将其数据存储在GPU上。该顶点缓冲区保留在帧之间，并在“场景图”所

表示的部分发生更改是更新。

默认情况下，渲染器将使用GL_STATIC_DRAW将数据上传到VBO。

通过环境变量QSG_RENDERER_BUFFER_STRATEGY=[strategy]可以选择其它上传策略，有效的策略还包括stream和dynamic。

更改此值对平台供应商最有用。

抗锯齿

“场景图”支持两种类型的抗锯齿。

默认情况下，诸如Rectangle和Image之类的图元，将通过沿图元的边缘添加顶点的方式，使

边缘淡化到透明，以实现抗锯齿。我们称此方法为顶点抗锯齿。

如果用户通过QQuickWindow::setFormat()将QSurfaceFormat设置为大于0的值，请求OpenGL多重采样，“场景图”将首选

基于多重采样的抗锯齿(MSAA)。

这两种技术将影响渲染器的内部实现方式，并且具有不同的限制。

通过设置环境变量QSG_ANTIALIASING_METHOD为msaa或者vertex也可以覆盖使用的抗锯齿方法。

即使两个图元的边在数学上相同，顶点抗锯齿也会在相邻图元的边缘之间产生接缝。多重采样抗锯齿则不会如此。

顶点抗锯齿

可以使用Item::antialiasing属性启用和禁用单个Item的顶点抗锯齿。在硬件支持的前提下，无论是正常渲染的图元，还是捕获到

帧缓冲区对象中的图元(例如使用ShaderEffectSource),顶点抗锯齿都可以正常运行并产生更高质量的抗锯齿功能。

使用顶点抗锯齿的不利之处在于，每个启用了抗锯齿的图元都必须进行混合。在批次渲染方面，这意味着渲染器需要做更多的工作来确定

图元是否可以进行批次渲染。如果和场景中其它元素重叠，也可能导致更少的批次渲染，从而影响性能。

在低端硬件上，混合操作也可能会非常耗性能。对于覆盖屏幕大部分区域的图像或者圆角矩形，这些图元内部所需要的混合操作数量

可能会导致严重的性能损耗，因为必须混合整个图元。

多采样抗锯齿

多采样抗锯齿是一项硬件功能，其中硬件会计算图元中每个像素的覆盖值。一部分硬件可以以非常低的成本进行多次采样，而另一些

硬件需要更多的内存和GPU周期来渲染一帧，

使用多采样可以对许多图元进行抗锯齿（例如圆角矩形和图片），并且在“场景图”中仍然是不透明的。这意味着在创建渲染批次时，

渲染器的工作会更加轻松，并且可以依赖early-z来避免过渡渲染。

使用多重采样抗锯齿时，渲染到帧缓冲区对象中的内容需要额外的扩展以支持帧缓冲区的多重采样。通常是GL_EXT_framebuffer_multisample

和GL_EXT_framebuffer_blit。大多数台式机芯片都具有这些扩展，但是在嵌入式芯片中却很少见。

如果硬件中不提供帧缓冲区多采样，则不会进行多采样抗锯齿，包括ShaderEffectSource。

性能

如文章开头所说，不需要了解渲染器的详细信息就能够获得良好的性能。默认渲染器在设计时就针对常见用例进行了优化，

并且在几乎任何情况下都将表现良好。

• 有效的批次渲染可带来良好的性能，并尽可能少地上传几何图形。通过设置环境变量QSG_RENDERER_DEBUG=render，渲染

  器将输出相应的统计信息，包括：批次渲染进行的程度，使用的批次数量，保留的批次及不透明和透明的批次数量等。

  追求最佳性能时，应仅在真正需要时上传数据，批次数量应该少于10个，且至少3-4个不透明批次。

• 默认渲染器不执行任何CPU端的视口裁剪或遮挡检测。如果某些内容不可见，则不应该显示，使用Item::visible将其设置

  为false。不添加这样的逻辑的主要原因是，它增加了额外的成本，这也将损害那些表现良好的应用程序。

• 确保纹理集被使用。除非图像特别大，否则Image和BorderImage 将使用它。C++代码中想要创建纹理集，需在调用

  QQuickWindow::createTexture()时传递QQuickWindow::TextureCanUseAtlas参数。通过设置环境变量

  QSG_ATLAS_OVERLAY，所有纹理集将被着色,以便在应用程序中轻松识别它们。

• 尽可能使用不透明图元。不透明图元在渲染器中处理速度更快，在GPU上绘制速度更快。例如，即使每个像素都是不透明的，PNG

  文件也会经常具有alpha通道。JPG文件始终是不透明的。当图像提供给QQuickImageProvider或者使用

  QQuickWindow::createTextureFromImage()创建图像时，请尽可能使用QImage::Format_RGB32格式。

• 如前文所示，重叠的复合Item无法批次渲染。

• 裁剪会中断批次渲染。切勿在表格内的单元格，delegate或者类似的元素中使用裁剪。使用省略代替文本裁剪。

创建一个返回裁剪后图像的QQuickImageProvider，代替图像裁剪。

• 批次渲染仅适用于16位索引。所有QtQuick内置的Item都使用了16位索引，但是自定义几何图元也可以自由使用32位索引。

• 一些材质的标志会阻止批次渲染，其中最受限制的一个是QSGMaterial::RequiresFullMatrix,它阻止了所有批次渲染。

• 具有单色背景的应用程序应使用QQuickWindow::setColor()而不是顶级带颜色的Rectangle。

  QQuickWindow::setColor()将在glClear()的调用中使用，这是比较快的。

• 生成Mipmap的Image不会放在纹理集中，也不会进行批次渲染。

• 存在一个OpenGL驱动程序相关的Bug：帧缓冲对象(FBO)回读时发生的一些错误会损坏渲染的字形。如果在环境变量

中设置QML_USE_GLYPHCACHE_WORKAROUND，则Qt会在RAM中保留该字形的其它副本。这意味着当渲染以前

未渲染的字形时，性能会稍低，因为Qt通过CPU访问额外的副本。这也意味着字形缓存将使用两倍的内存。渲染质量不受影响。

如果应用程序性能不佳，需要确认瓶颈是否在渲染。此时可以使用探查器Profiler! 设置环境变量QSG_RENDER_TIMING=1

将输出许多有用的时序参数，这些参数可以用来查明问题所在。

可视化

为了可视化“场景图”默认渲染器的各个方面，可以将QSG_VISUALIZE环境变量设置为下面每个部分中详细介绍的值其中之一。

下面这段Qml代码提供了一些变量输出的示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

import QtQuick 2.2

Rectangle {
    width: 200
    height: 140

    ListView {
        id: clippedList
        x: 20
        y: 20
        width: 70
        height: 100
        clip: true
        model: ["Item A", "Item B", "Item C", "Item D"]

        delegate: Rectangle {
            color: "lightblue"
            width: parent.width
            height: 25

            Text {
                text: modelData
                anchors.fill: parent
                horizontalAlignment: Text.AlignHCenter
                verticalAlignment: Text.AlignVCenter
            }
        }
    }

    ListView {
        id: clippedDelegateList
        x: clippedList.x + clippedList.width + 20
        y: 20
        width: 70
        height: 100
        clip: true
        model: ["Item A", "Item B", "Item C", "Item D"]

        delegate: Rectangle {
            color: "lightblue"
            width: parent.width
            height: 25
            clip: true

            Text {
                text: modelData
                anchors.fill: parent
                horizontalAlignment: Text.AlignHCenter
                verticalAlignment: Text.AlignVCenter
            }
        }
    }
}

左侧的ListView,我们将其clip属性设置为true。右侧的ListView，我们将每个delegate的clip属性设置为true。

以此来说明裁剪对批次渲染的影响。

这是正常的运行结果

可视化元素不考虑裁剪，并且渲染顺序是任意的。

批次可视化

设置环境变量QSG_VISUALIZE为batches可以在渲染器中可视化查看批次。

合并过的批次以纯色渲染，未合并的批次以对角线图案渲染。独立的颜色越少意味着批次分配的越好。

如果未合并的批次中包含许多单独的节点，则是比较糟糕的。

QSG_VISUALIZE=batches

裁剪可视化

设置环境变量QSG_VISUALIZE为clip,渲染器会在“场景图”中渲染红色区域来指示裁剪区域。

默认情况下Item不裁剪，因此不会显示裁剪区域。

QSG_VISUALIZE=clip

变更可视化

设置环境变量QSG_VISUALIZE为changes,可以在“场景图”中看到变更。“场景图”中的变更以随机颜色的

闪烁叠加显示。图元上的变更以纯色显示，而批次渲染根节点的变更以特定的pattern显示。

OverDraw 过渡绘制可视化

设置环境变量QSG_VISUALIZE为overdraw,可以在“场景图”中看到过渡绘制。可视化的3D视图中，

所有过渡绘制的Item会高亮显示。此模式也可以用来检测视口之外的几何图元。不透明的Item以绿色显示，

而半透明的Item以红色显示。视口的边框为蓝色显示。不透明的内容使“场景图”更易于处理，渲染速度更快。

请注意，上面的代码中顶层矩形框Rectangle是多余的，因为窗口也是白色的，在这种情况下渲染矩形框会造成资源浪费。

将其更改为Item会略微提高性能。

QSG_VISUALIZE=overdraw

通过QtRHI(硬件渲染接口) 进行渲染

从Qt5.14开始，默认适配层增加了一个选项，可以使用 QtGui模块提供的图形抽象层Qt Rendering Hardware Interface (RHI)

进行渲染。启用后，将不进行OpenGL调用，而是使用抽象层提供的API来渲染“场景图”，然后将其转换为OpenGL,

Vulkan,Metal或者Direct3D调用。

通过一次编写着色器代码，编译为SPIR-V,然后转换为适用于各种图形API的语法，实现着色器的统一处理。

要启用此功能，代替直接OpenGL调用，可以通过下面的变量:

希望始终使用单个指定的图形API运行应用程序，也可以通过C++代码来设置。

例如，在构造任何QQuickWindow之前，在main函数的早期进行以下调用将强制使用vulkan

1

QQuickWindow::setSceneGraphBackend(QSGRendererInterface::VulkanRhi);

可以查看QSGRendererInterface::GraphicsApi文档。以Rhi结尾的枚举值等价于设置QSG_RHI和QSG_RHI_BACKEND。

除非被QSG_RHI_PREFER_SOFTWARE_RENDERER或特定后端的变量（例如QT_D3D_ADAPTER_INDEX 或者 QT_VK_PHYSICAL_DEVICE_INDEX）覆盖，

否则所有QRhi后端都会选择系统默认的GPU适配器或物理设备。目前没有进一步的适配器相关配置项。

简介

这是《玩转QtQuick》系列文章的第一篇，主要是介绍Qt Quick Scene Graph “场景图”的关键特性、主要架构及实现原理等等。

(不是QWidget 框架中那个 QGraphicsView哦，是Qt Quick的Scene Graph，不一样)

Scene Graph 是QtQuick/Qml所依赖的渲染框架。

本文会涉及到一些图形学的基本概念，例如：材质、纹理、光栅化、图元等，建议参考相关资料，本文不做进一步的解释。

因为Qt官方文档写的比较全面，所以本文主要是对官方文档的翻译，同时会补充一些个人理解。

翻译主要参考Qt5.15的文档，适当做了一些调整，尽量信达雅，尽量说人话。

下面翻译开始

Qt Quick 中的“场景图”

Qt Quick 2 使用了专用的“场景图”，然后遍历并通过图形API(例如OpenGL、OpenGL ES、Vulkan、Metal 或Direct 3D)渲染该“场景图”。

将“场景图”用于图形渲染而不是传统的命令式绘图系统(QPainter之类的)，意味着可以在帧之间保留要渲染的场景，并且在渲染开始之前就知道要

渲染的完整图元集。这为许多优化打开了大门，例如：通过批量渲染最大程度减少状态变化、丢弃被遮挡的图元。

再举个具体的例子，假设用户界面包含一个列表，列表有10个节点，其中每个节点都有背景色、图标和文本。

使用传统的绘图技术，这将导致30次DrawCall和30次状态更改。

而“场景图”可以重组原始图元进行渲染，以便在第一次DrawCall中渲染所有背景，第二次DrawCall渲染所有图标，第三次DrawCall渲染所有文本，

从而将DrawCall的总数减少到3次。这样可以显著提高硬件的性能。

“场景图”与Qt Quick 2.0 紧密相关，不能单独使用。“场景图”由QQuickWindow类管理和渲染，自定义Item类型

可以通过调用QQuickItem::updatePaintNode()将其图元添加到“场景图”中。

“场景图”是Item场景的图形表示，它是一个独立的结构，其中包含足以渲染所有节点的信息。

设置完成后，就可以独立于Item状态对其进行操作和渲染。

在许多平台上，“场景图”会在GUI线程准备下一帧状态时，在专用渲染线程上进行渲染。

注意：本文列出的许多信息特定于 Qt “场景图”的内置默认行为。如果使用替代的方案时，并非所有概念都适用。

Qt Quick “场景图”的结构

“场景图” 由许多预定义的节点类型组成，每种类型都有专门的用途。

尽管我们将其称为“场景图”，但更精确的定义是“节点树”。

该树根据Qml场景中的QQuickItem类型构建，然后在内部对该场景进行渲染，最终呈现该场景。

“节点” 本身不包含任何 绘制 或者 paint() 虚函数。

“节点树”主要由内建的预定义类型组成，用户也可以添加具有自定义内容的完整子树，包括表示3D模型的子树。

Scene Graph API / “场景图”接口

一般是指Qt Quick中 QSG开头的所有类。

节点

对用户而言,最重要的节点是QSGGeometryNode。它用来实现自定义图形中的几何形状和材质。

使用QSGGeometry可以定义几何坐标，并描述形状或者图元网格。它可以是直线，矩形，多边形，许多

不连续的矩形或者复杂的3D网格。材质定义如何填充此图形的每个像素。

一个节点可以有任意数量的子节点，并且几何节点将被渲染，以便它们以子顺序出现，且父级位于其子级之后。

注意：这并未说明渲染器中的实际渲染顺序，仅保证视觉顺序。

有效的节点如下:

自定义节点通过继承QQuickItem类，重写QQuickItem::updatePaintNode()，并且设置 QQuickItem::ItemHasContents 标志的方式，添加到“场景图”。

警告：至关重要的是, 原生图形（OpenGL，Vulkan，Metal等）操作以及与“场景图”的交互只能在渲染线程中进行，主要

在updatePaintNode()调用期间进行。经验法则是仅在QQuickItem::updatePaintNode()函数内使用带有“QSG”前缀的类。

更多详细的信息，可以参考Qt文档： Scene Graph - Custom Geometry

预处理

节点具有虚函数QSGNode::preprocess(),该函数将在渲染“场景图”之前被调用。

节点子类可以设置标志QSGNode::UsePreprocess并重写QSGNode::preprocess()函数以对其节点进行预处理。

例如, 更新纹理的一部分, 或者将贝塞尔曲线划分为当前比例因子的正确细节级别。

节点所有权

节点的所有权归创建者，或者设置标志QSGNode::OwnedByParent后归“场景图”。

通常将所有权分配给“场景图”是可取的，因为这样可以简化“场景图”位于GUI线程之外时的清理操作。

材质

材质描述如何填充QSGGeometryNode中几何图形的内部。它封装了图形管线中顶点和片元阶段的着色器，并提供了足够的灵活性，

尽管大多数Qt Quick 项目本身仅使用了非常基本的材质，例如纯色和纹理填充。

想要对Qml中Item使用自定义着色的用户，可以直接在Qml中使用ShaderEffect。

下面是一个完整的材质类列表：

更多详细的信息，可以参考Qt文档： Scene Graph - Simple Material

便捷的节点

“场景图”API是一套 偏底层的接口，专注于性能而不是易用性。

从头开始编写自定义的几何图形和材质，即使是最基本的几何图形和材质，也需要大量的代码。

因此，“场景图”API包含了一些节点类，以使最常用自定义节点的开发更便捷。

“场景图”和渲染

“场景图”的渲染发生在QQuickWindow类的内部，并且没有公共API可以访问它。

但是，渲染管线中有一些地方可以让用户附加应用程序代码。

可通过直接调用“场景图”使用的图形API(OpenGL、Vulkan、Metal等)来添加自定义“场景图”内容，或插入

任意渲染命令。插入点由“渲染循环”定义。

有关“场景图”渲染器如何工作的详细说明，可以参考Qt文档: Qt Quick Scene Graph Default Renderer。

渲染循环

共有三种渲染循环变体: 基本渲染循环(basic)，窗口渲染循环(windows)和线程渲染循环(threaded)。

其中，基本渲染循环和窗口渲染循环是单线程的，线程渲染循环在专用线程上执行“场景图”渲染。

Qt尝试根据平台及可能使用的图形驱动程序选择合适的渲染循环。如果这不能满足你的需求，或者处于测试的目的，可以使用环境变量

QSG_RENDER_LOOP强制使用指定的渲染循环。要验证使用哪个渲染循环，请启用qt.scenegraph.general日志类别。

注意：线程渲染循环和窗口渲染循环 依赖于图形API实现来进行节流，例如，在OpenGL环境下，“请求交换间隔”为1。

一些图形驱动程序允许用户忽略此设置并将其关闭，而忽略Qt的请求。

在不阻塞“交换缓冲区”操作(或其它位置)的情况下，渲染循环将以尽快的速度运行动画并使CPU 100%运转。

如果已知系统无法提供基于vsync的限制,请通过设置环境变量QSG_RENDER_LOOP = basic使用 基本渲染循环。

线程渲染循环

在许多环境中，“场景图”将在专用渲染线程上进行。这样做是为了增加多核处理器的并行度，并更好地利用停顿时间。

这可以显著提高性能，但是与“场景图”进行交互的位置和时间加了一些限制。

以下是关于OpenGL环境下如何使用线程渲染循环的简单概述。除了OpenGL上下文的特定要求外，其它图形API的步骤也是相同的。

1. Qml场景中发生变化，触发调用QQuickItem::update()， 这可能是动画或者用户操作的结果。

   一个 事件会被post到渲染线程来启动新的一帧。

2. 渲染线程准备渲染新的一帧，GUI线程会启动阻塞。

3. 当渲染线程准备新的一帧时，GUI线程调用QQuickItem::updatePolish() 对场景中节点进行最终的“润色”,再渲染它们。

4. GUI 线程阻塞。

5. QQuickWindow::beforeSynchronizing()信号发出。应用程序可以对此信号进行直连(Qt::DirectConnection),

   以进行QQuickItem::updatePaintNode()之前所需的任何准备工作。

6. 将Qml状态同步到“场景图”中。自上一帧以来，所有已更改的节点上调用QQuickItem::updatePaintNode()函数完成同步。

   这是Qml与“场景图”中的节点唯一的交互时机。

7. GUI线程不再阻塞。

8. 渲染“场景图”：

   a. QQuickWindow::beforeRendering() 信号发出。应用程序可以直连(Qt::DirectConnection)此信号,来

   调用自定义图形API，然后将其可视化渲染在Qml场景之下。

   b. 指定了QSGNode::UsePreprocess标志的节点将调用其QSGNode::preprocess()函数。

   c. 渲染器处理节点。

   d. 渲染器生成状态并记录使用中的图形API的绘制调用。

   e. QQuickWindow::afterRendering 信号发出。应用程序可以直连(Qt::DirectConnection)此信号,来

   调用自定义图形API，然后将其可视化渲染在Qml场景之上。

   f. 新的一帧准备就绪。交换缓冲区(OpenGL)，或者记录当前命令，然后将命令缓冲区提交到图形队列(Vulkan,Metal)。

   QQuickWindow::frameSwapped()信号发出。

9. 渲染线程正在渲染时，GUI可以自由地进行动画、处理事件等。

当前默认情况下，线程渲染循环工作在 带opengl32.dll的Windows平台,具有Metal的MacOS平台，移动平台，

具有EGLFS的嵌入式Linux,以及平台无关的Vulkan环境，但这可能会有所改变。

通过在环境变量中设置QSG_RENDER_LOOP=threaded,可以强制使用线程渲染器。

非线程渲染循环 (基本渲染循环和窗口渲染循环)

当前默认在使用非线程渲染循环的环境，包括使用ANGLE及非默认opengl32实现的windows平台，使用OpenGL的MacOS，

以及一些特殊驱动的linux环境。

这主要是一种预防措施，因为并非所有的OpenGL驱动和窗口系统的组合都经过测试。同时，诸如ANGLE 或

Mesa llvmpipe之类的实现根本无法在线程渲染中正常运行。因此，对于这些环境，不能使用线程渲染。

在MacOS OpenGL环境下，使用XCode 10 (10.14 SDK) 或更高版本进行构建时不支持线程渲染循环，因为这会选择在

MacOS 10.14上使用“基于图层的视图”。你可以使用XCode 9 (10.13 SDK)进行构建，以避开“基于图层的视图”,这种

情况下，线程渲染循环可以用并且默认会启用。

Metal没有这样的限制。

非线程渲染循环默认在使用ANGLE的windows平台，而“基本渲染循环”用于其它需要非线程渲染循环的平台。

即使使用非线程渲染循环，也应像使用线程渲染循环一样编写代码，否则将使代码不可移植。

以下是非线程渲染循环中帧渲染序列的简化图示。

使用QQuickRenderControl自定义渲染控制

使用QQuickRenderControl时，驱动渲染循环的责任将转移到应用程序中。

在这种情况下，不使用内置的渲染循环。

取而代之的是，由应用程序在适当的时候调用 polish synchronize rendering等渲染步骤,实现类似于上述

行为的线程渲染循环或非线程渲染循环。

“场景图”和原生图形API的混合使用

“场景图”提供了两种方法，来集成应用程序提供的图形命令：

直接发出OpenGL、Vulkan、Metal等命令，以及在“场景图”中创建纹理化节点。

通过连接到QQuickWindow::beforeRendering 和 QQuickWindow::afterRendering()信号，应用程序可以直接在“场景图”

渲染的同一上下文中进行OpenGL调用。

使用Vulkan或者Metal之类的API，应用程序可以通过QSGRendererInterface来查询本机对象，例如“场景图”的命令缓冲区，

并在认为合适的情况下，向其记录命令。

如信号的名称所示，用户随后可以在Qt Quick “场景图”下方或者上方渲染内容。

以这种方式集成的好处是不需要额外的帧缓冲区或者内存来执行渲染，并且消除了可能昂贵的纹理化步骤。

缺点是Qt Quick 决定何时调用信号，这也是唯一允许OpenGL应用程序绘制的时间点。

Qt提供了一些 “场景图”相关的示例，可在examples中找到:

另一个替代方式，是创建一个 QQuickFrameBufferObject (当前仅适用OpenGL)，在这个FBO内部渲染，然后将其

作为纹理显示在“场景图”中。

“Scene Graph - Rendering FBOs” 示例如何完成此操作。

还可以组合多个渲染上下文和多个线程以创建要在“场景图”中显示的内容。

“The Scene Graph - Rendering FBOs in a thread” 示例如何完成此操作。

“Scene Graph - Metal Texture Import”示例直接使用基础API创建和渲染纹理，然后在自定义QQuickItem中的

“场景图”中包装和使用此资源。该示例适用了Metal，但是概念也适用于所有其它图形API。

尽管QQuickFrameBufferObject当前不支持，除OpenGL之外的其它图形API也可以采用这种方法。

警告：当在“场景图”中混合渲染OpenGL内容时，重要的一个点是应用程序不要使OpenGL上下文

处在缓冲区绑定状态，“属性启用”，特殊值处在z缓冲区或模板缓冲区等。这样做会导致无法预测的行为。

警告：自定义渲染代码必须具有多线程意识，它不应该假设应用程序在GUI线程中运行。

自定义Item使用QPainter

QQuickItem提供一个子类QQuickPaintedItem,它允许用户使用QPainter渲染内容。

警告: QQuickPaintedItem通过“间接2D 表面”渲染它的内容，“间接2D 表面”可以是软件光栅化，也可以是

“OpenGL帧缓冲对象(FBO)”。这种渲染包含2步操作。第一步是光栅化表面，第二步是渲染表面。

因此，直接使用“场景图” 接口渲染，速度比QQuickPaintedItem快。

日志支持

“场景图”支持很多种日志类别。这些日志除了对Qt贡献者有帮助之外，还可用于追踪性能问题和缺陷。

旧版QSG_INFO环境变量也可以用。将其设置为非零值将启用qt.scengraph.general类别。

注意：遇到图形问题时，或不确定正在使用哪个渲染循环或图形API时，请至少启用qt.scenegraph.general和qt.rhi,或者

设置QSG_INFO=1的情况下启动应用程序。然后这将在初始化期间将一些基本信息打印到调试输出。

“场景图”后端

除了公共API外，“场景图”还具有适配层，该适配层用以实现特定硬件的适配。这是一个未公开的、内部的、私有实现的插件，

可以让硬件适配团队充分利用其硬件。这包括：

• 自定义纹理； 特别是QQuickWindow::createTextureFromImage的实现以及Image和BorderImage类型使用的纹理的内部表示。

• 自定义渲染器；适配层使插件可以决定如何遍历和渲染“场景图”，从而有可能针对特定硬件优化渲染

算法或 使用可提高性能的扩展。

• 许多默认Qml类型的自定义“场景图”实现，包括其文本和字体渲染。

• 自定义动画驱动程序；允许动画系统连接到低级“垂直同步”的显示设备，以获得平滑的渲染。

• 自定义渲染循环；可以更好地控制Qml如果处理多个窗口。

QQuickWidget中文输入法问题的正确解法

本文分享特定问题的解法,用不到的可以忽略。

Qt的bug

使用QQuickWidget的时候，遇到过这个问题：界面的TextInput 或者TextEdit, 鼠标点击聚焦后，切换为光标输入状态，此时切换系统中文输入法，会发现无法输入。

(系统任务栏的输入法状态是正确的,界面上输入字符，直接显示英文，无法显示输入法的候选框)

需要把界面切到其它软件，再切换回来，之后就能够输入了。

可以参考Qt官方bug报告:

https://bugreports.qt.io/browse/QTBUG-61475

旧的解法

这个Bug是2018年报告的，我们当时做项目，也被这个Bug坑到了。

当时我给出了一个弱化版本的解法，原理是在第一次聚焦的时候，清理掉QQuickWidget的焦点。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

QuickWidget::QuickWidget(QWidget *parent)
    : QQuickWidget(parent)
{
    ...
    connect(quickWindow(), &QQuickWindow::activeFocusItemChanged, this, &QuickWidget::onClearFocus);
    ...
}
void QuickWidget::onClearFocus()
{
    QQuickItem *pItem = quickWindow()->activeFocusItem();
    if (pItem && (pItem->inherits("QQuickTextInput") || pItem->inherits("QQuickTextField"))) 
    {
        disconnect(quickWindow(), &QQuickWindow::activeFocusItemChanged, this, &QuickWidget::onClearFocus);
        QuickWidget::clearFocus();
    }
}

此方法勉强能用，一些细节上体验不太好。

当时找不到更好的方法，就这样用着了。

正确的解法

2020年Qt官方终于派出了资深的专家，在Qt5.15.2中，彻底解决了这个问题。

(看到有不少博客、论坛，还在流传我提供的旧版本，于心不忍)

于是我从新版本里面，提炼出来了代码，给使用旧版本的同学解决此问题。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

QuickWidget::QuickWidget(QWidget *parent)
    : QQuickWidget(parent)
{
  ...

#if QT_VERSION < QT_VERSION_CHECK(5, 15, 2)
    connect(quickWindow(), &QQuickWindow::focusObjectChanged, this, &QuickWidget::propagateFocusObjectChanged);
#endif
  
  ...
}

#if QT_VERSION < QT_VERSION_CHECK(5, 15, 2)
bool QuickWidget::event(QEvent *e)
{
    switch (e->type())
    {
        case QEvent::FocusAboutToChange:
            return QCoreApplication::sendEvent(quickWindow(), e);
        default:
            break;
    }
    return Super::event(e);
}
void QuickWidget::propagateFocusObjectChanged(QObject *focusObject)
{
    if (QApplication::focusObject() != this)
        return;
    if (this->window()->windowHandle()) {
        emit this->window()->windowHandle()->focusObjectChanged(focusObject);
    }
}
#endif

简介

很多现代化的软件，都会有向导功能，相信大家并不陌生。

“用户向导”的作用，可以帮助新用户快速了解产品，也可以用来提醒用户该如何操作。

这次涛哥就分享一个Qml制作“用户向导”的方案。

效果预览

看一下最终效果

在整个软件界面上，覆盖一层遮罩，只保留一部分镂空区域，并用箭头指向镂空区域，

以此,将用户的眼球聚焦到镂空区域，并用适当的文字,说明镂空区域的作用。

这个遮罩层是不能操作到软件界面的，点击任意区域，会转到下一步的向导，直到最后向导退出。

源码

《玩转Qml》系列文章，配套了一个优秀的开源项目:TaoQuick

github https://github.com/jaredtao/TaoQuick

访问不了或者速度太慢，可以用国内的镜像网站gitee

https://gitee.com/jaredtao/TaoQuick

原理说明

向导的实现方案有很多，比如贴图之类的。按不同的需求，方案也不尽相同。

这里先列一个涛哥的需求，再讨论方案才有意义。

需求说明

• 窗口大小不固定

• 焦点区域可以是Qml界面中的任意可视组件

• 向导功能要独立实现，且对已有代码改动最小

原理

遮罩的制作，在Qml中就是几个半透明的Rectangle拼在一起，附带一个顶层MouseArea，

将所有鼠标事件都过滤掉，这些都比较简单。

焦点区域才是本文的核心。

Qml对象作用域

先来说一下Qml中的对象作用域吧。

如果你阅读过《Qml Book》或者有一定的Qml经验，就知道Qml中的对象，都是通过id相互引用的。

像html / Android，都有类似findElementById这样的接口，获取任意的组件。

在Qml，省去了find这一步，可以直接使用id进行访问。

不过呢，Qml这个id的可访问性，不是任何场景都能直接用的，有诸多情况下，不能直接使用, 例如：

• 平级的两个组件，它们的子组件不能互相访问到（同一个文件作用域中的除外）

• 各种View的delegate中的组件id，view外部不能直接访问(这是因为delegate有多个实例的情况下，id不能唯一标识)

• Loader/Component动态加载后的子组件，不能被直接访问（动态加载，都不知道它什么时候创建，当然不能用它）

诸如此类，都不能直接访问。

扩展说明:

顶层组件的id，可以被所有子组件访问，因此可以用来存储全局对象；

Qml单例组件，或者C++上下文对象，也可以被所有子组件访问。

这两种方式也可以用来实现向导功能，有兴趣的读者可自己探索。

QObject对象树

Qml中的所有可视化组件，大都是继承于Item，Item的继承关系是 Item ==> QQuickItem ==> QObject

因此呢，Qml中的所有对象，都在一个QObject树上，具有父子关系。

我们可以从任意节点，向上找到根节点，也可以通过根节点的findChild的方式，找到任意一个带objectName的节点。

涛哥的向导方案，便是基于此实现。

实现

最小改动

在已有的Qml代码中，对于想当作焦点区域的组件，最小改动是增加一个objectName

例如涛哥想把已有的标题栏按钮，作为焦点区域：

改动前:

1
2
3
4
5
6
7

...
      SkinBtn {
          width: 24
          height: 24
          anchors.verticalCenter: parent.verticalCenter
      }
...

改动后:

1
2
3
4
5
6
7
8

...
      SkinBtn {
          width: 24
          height: 24
          anchors.verticalCenter: parent.verticalCenter
          objectName: "skinBtn"
      }
...

获取焦点区域

找到对象

像前面的组件，只要有了objectName，就可以从任意位置获取到它了

这需要一点C++代码扩展

1
2
3
4
5
6
7

QQuickItem *getObject(QObject * pRootObject, const QString &targetObjName)
{
    if (!pRootObject) {
        return nullptr;
    }
    return pRootObject->findChild<QQuickItem *>(targetObjName);
}

通过findChild就可以拿到目标对象了, rootObject是根节点，可以从任意节点向上找到，

也可以通过QQmlContex直接获取到。

取坐标

找到了对象，就可以计算它的坐标，用于向导了。

为了方便计算，同时避免处理繁杂的父子关系，可以直接把坐标映射到顶层窗口。向导的坐标也以顶层窗口为准即可。

这里进一步封装了C++代码,直接计算好坐标

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

QRect getItemGeometryToScene(const QString &targetObjName) const
{
    if (!pRootObject) {
        return {};
    }
    auto pItem = pRootObject->findChild<QQuickItem *>(targetObjName);
    if (pItem) {
        if (pItem->parentItem()) {
            //如果有父节点，调用父节点的mapToScene将坐标映射到顶层窗口
            auto pos = pItem->parentItem()->mapToScene(pItem->position());
            return QRectF { pos.x(), pos.y(), pItem->width(), pItem->height() }.toRect();
        } else {
            //如果没有父节点，坐标本身就是相对顶层窗口的
            return pItem->boundingRect().toRect();
        }
    }
    return {};
}

完整的代码，可以在TaoQuick项目中看到, 封装了一个QuickTool类，

所在路径是TaoQuick/3rdparty/TaoCommon/QuickTool

向导页

接下来就是封装一个向导页面了,遮罩围绕在焦点四周，同时带上箭头和文字说明即可

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175

//CusWizardPage.qml

import QtQuick 2.9
import QtQuick.Controls 2.2
 import QtGraphicalEffects 1.0
import ".."
import "../.."

Item {
    id: pageItem
    z: 998
    anchors.fill: parent
    property string wizardName
    property string wizardDescript
    property string targetObjectName
    property int pageType: pageTypeDown

    property color maskColor: "black"
    property real maskOpacity: 0.75

    property rect focusRect

    //int 做枚举，定义4种方向的箭头
    readonly property int pageTypeDown: Qt.DownArrow
    readonly property int pageTypeUp: Qt.UpArrow
    readonly property int pageTypeLeft: Qt.LeftArrow
    readonly property int pageTypeRight: Qt.RightArrow


    Component.onCompleted: {
        //组件创建时，通过C++扩展，获取到焦点区域坐标
        var rect = quickTool.getItemGeometryToScene(targetObjectName)
        focusRect = rect
    }
    //焦点区域的同步item,用来给四周的组件定位
    Item {
        id: focusItem
        x: focusRect.x
        y: focusRect.y
        width: focusRect.width
        height: focusRect.height
        RadialGradient {
            anchors.fill: parent
            gradient: Gradient {
                GradientStop { position: 0.0; color: "transparent" }
                GradientStop { position: 0.6; color: maskColor }
            }
            opacity: maskOpacity / 2
        }
    }
    //left
    Rectangle {
        x: 0
        y: 0
        width: focusRect.x
        height: parent.height
        color: maskColor
        opacity: maskOpacity
    }
    //right
    Rectangle {
        x: focusRect.x + focusRect.width
        y: 0
        width: pageItem.width - x
        height: parent.height
        color: maskColor
        opacity: maskOpacity
    }
    //top
    Rectangle {
        x: focusRect.x
        width: focusRect.width
        y: 0
        height: focusRect.y
        color: maskColor
        opacity: maskOpacity
    }
    //bottom
    Rectangle {
        x: focusRect.x
        width: focusRect.width
        y: focusRect.y + focusRect.height
        height: pageItem.height - y
        color: maskColor
        opacity: maskOpacity
    }
    Row {
        id: leftRow
        spacing: 10
        visible: pageType === pageTypeLeft
        z: 998
        anchors {
            left: focusItem.right
            leftMargin: 5
            verticalCenter: focusItem.verticalCenter
        }
        CusImage {
            source: CusConfig.imagePathPrefix + "arrow-left.png"
            anchors.verticalCenter: parent.verticalCenter
        }
    }
    Row {
        id: rightRow
        spacing: 10
        layoutDirection: Qt.RightToLeft
        visible: pageType === pageTypeRight
        z: 998
        anchors {
            right: focusItem.left
            rightMargin: 5
            verticalCenter: focusItem.verticalCenter
        }
        CusImage {
            source: CusConfig.imagePathPrefix + "arrow-right.png"
            anchors.verticalCenter: parent.verticalCenter
        }
    }
    Column {
        id: downColumn
        spacing: 10
        visible: pageType === pageTypeDown
        width: 300
        z: 998
        anchors {
            bottom: focusItem.top
            bottomMargin: 5
            horizontalCenter: focusItem.horizontalCenter
        }
        CusImage {
            source: CusConfig.imagePathPrefix + "arrow-down.png"
            anchors.horizontalCenter: parent.horizontalCenter
        }
    }
    Column {
        id: upColumn
        spacing: 10
        visible: pageType === pageTypeUp
        width: 300
        z: 998
        anchors {
            top: focusItem.bottom
            topMargin: 5
            horizontalCenter: focusItem.horizontalCenter
        }
        CusImage {
            source: CusConfig.imagePathPrefix + "arrow-up.png"
            anchors.horizontalCenter: parent.horizontalCenter
        }
    }
    CusLabel {
        id: wizardDescriptLabel
        z: 998
        text: qsTr(wizardDescript) + CusConfig.transString
        font.pixelSize: 16
        color: "white"
        anchors {
            horizontalCenter: parent.horizontalCenter
            verticalCenter: parent.verticalCenter
            verticalCenterOffset: 50
            horizontalCenterOffset: -50
        }
    }
    CusLabel {
        z: 998
        text: qsTr(wizardName) +  CusConfig.transString
        font.pixelSize: 26
        color: "white"
        anchors {
            left: wizardDescriptLabel.left
            bottom: wizardDescriptLabel.top
            bottomMargin: 30
        }
    }

}

向导组件

向导一般不止一页，而是很多页，这里就封装了一个向导组件。

使用model-view的方式,数据源由外部设置，组件只管按照model去实例化对应的向导页即可

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

//CusWizard.qml

import QtQuick 2.9
import QtQuick.Controls 2.2
import ".."
import "../.."

Item {
    id: cusWizardItem
    signal wizardFinished
    property string totlaString: qsTr("Wizard %1/%2 >").arg(currentIndex + 1).arg(count) + CusConfig.transString
    property string operatorString: qsTr("Click any area to show next") + CusConfig.transString
    MouseArea {
        anchors.fill: parent
        hoverEnabled: true
        onClicked: {
            currentIndex++
            if (currentIndex >= count) {
                wizardFinished()
            }
        }
    }
    property var model
    property int count: model.count
    property int currentIndex: 0
    Repeater {
        model: cusWizardItem.model
        delegate: CusWizardPage {
            anchors.fill: parent
            visible: index === currentIndex
            wizardName: model.name
            wizardDescript: model.descript
            targetObjectName: model.targetObjectName
            pageType: model.arrowType
        }
    }
    CusLabel {
        z: 999
        id: centerLabel
        anchors {
            centerIn: parent
            horizontalCenterOffset: 300
            verticalCenterOffset: 150
        }
        text: totlaString
        font.pixelSize: 22
        color: "white"
    }
    CusLabel {
        z: 999
        anchors {
            centerIn: parent
            horizontalCenterOffset: 300
            verticalCenterOffset: 150 + centerLabel.height
        }
        text: operatorString
        color: "white"
    }
}

向导数据源

最后来看一下，TaoQuick项目的首页，提供的向导数据model

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

ListModel {
    id:wizardModel
    ListElement {
        name: "TitleBar"
        descript: "drag change window pos, double click change window state"
        targetObjectName: "blankItem"
        arrowType: Qt.UpArrow
    }
    ListElement {
        name: "Control Buttons"
        descript: "minimize, maximize, normal or close main window"
        targetObjectName: "controlButtonsRow"
        arrowType: Qt.UpArrow
    }
    ListElement {
        name: "Skin Button"
        descript: "switch theme"
        targetObjectName: "skinBtn"
        arrowType: Qt.UpArrow
    }
    ListElement {
        name: "Language Button"
        descript: "switch language"
        targetObjectName: "langBtn"
        arrowType: Qt.UpArrow
    }
    ListElement {
        name: "Left Pane"
        descript: "show content list"
        targetObjectName: "leftPane"
        arrowType: Qt.LeftArrow
    }
    ListElement {
        name: "Drawer Button"
        descript: "show or hide left pane"
        targetObjectName: "menuBtn"
        arrowType: Qt.LeftArrow
    }
    ListElement {
        name: "Search Input"
        descript: "search content"
        targetObjectName: "searchInput"
        arrowType: Qt.LeftArrow
    }
    ListElement {
        name: "Home Button"
        descript: "go back home page"
        targetObjectName: "homeBtn"
        arrowType: Qt.LeftArrow
    }
    ListElement {
        name: "Content List"
        descript: "switch content"
        targetObjectName: "contentListView"
        arrowType: Qt.LeftArrow
    }
    ListElement {
        name: "Content Pane"
        descript: "show current selected content by list"
        targetObjectName: "contentRect"
        arrowType: Qt.RightArrow
    }
    ListElement {
        name: "Tool Buttons"
        descript: "special function buttons such as Wizard, View Source Code and so on"
        targetObjectName: "wizardBtn"
        arrowType: Qt.RightArrow
    }
}

简介

最近遇到一些需求，要在Qt/Qml中开发树结构，并能够导入、导出json格式。

于是我写了一个简易的Demo，并做了一些性能测试。

在这里将源码、实现原理、以及性能测试都记录、分享出来，算是抛砖引玉吧，希望有更多人来讨论、交流。

TreeEdit源码

起初的代码在单独的仓库

github https://github.com/jaredtao/TreeEdit

gitee镜像 https://gitee.com/jaredtao/Tree

后续会收录到《玩转Qml》配套的开源项目TaoQuick中

github https://github.com/jaredtao/TaoQuick

gitee镜像 https://gitee.com/jaredtao/TaoQuick

效果预览

看一下最终效果

Qml实现的树结构编辑器, 功能包括:

树结构的缩进
节点展开、折叠
添加节点
删除节点
重命名节点
搜索
导入
导出
节点属性编辑（完善中）

原理说明

数据model的实现，使用C++，继承于QAbstractListModel，并实现rowCount、data等方法。

model本身是List结构的，在此基础上，对model数据进行扩展以模拟树结构，例如增加了 “节点深度”、“是否有子节点”等数据段。

view使用Qml Controls 2中的ListView模拟实现(Controls 1 中的TreeView即将被废弃)。

关键代码

model

基本model的声明如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

template <typename T>
class TaoListModel : public QAbstractListModel {
public:
    //声明父类
    using Super = QAbstractListModel;

    TaoListModel(QObject* parent = nullptr);
    TaoListModel(const QList<T>& nodeList, QObject* parent = nullptr);

    const QList<T>& nodeList() const
    {
        return m_nodeList;
    }
    void setNodeList(const QList<T>& nodeList);

    int rowCount(const QModelIndex& parent) const override;

    QVariant data(const QModelIndex& index, int role) const override;
    bool setData(const QModelIndex& index, const QVariant& value, int role) override;


    bool insertRows(int row, int count, const QModelIndex& parent = QModelIndex()) override;
    bool removeRows(int row, int count, const QModelIndex& parent = QModelIndex()) override;

    Qt::ItemFlags flags(const QModelIndex& index) const override;
    Qt::DropActions supportedDropActions() const override;

protected:
    QList<T> m_nodeList;
};

其中数据成员使用 QList m_nodeList 存储, 大部分成员函数是对此数据的操作。

Json格式的model声明如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

const static QString cDepthKey = QStringLiteral("TModel_depth");
const static QString cExpendKey = QStringLiteral("TModel_expend");
const static QString cChildrenExpendKey = QStringLiteral("TModel_childrenExpend");
const static QString cHasChildendKey = QStringLiteral("TModel_hasChildren");
const static QString cParentKey = QStringLiteral("TModel_parent");
const static QString cChildrenKey = QStringLiteral("TModel_children");

const static QString cRecursionKey = QStringLiteral("subType");
const static QStringList cFilterKeyList = { cDepthKey, cExpendKey, cChildrenExpendKey, cHasChildendKey, cParentKey, cChildrenKey };
class TaoJsonTreeModel : public TaoListModel<QJsonObject> {
    Q_OBJECT
    Q_PROPERTY(int count READ count NOTIFY countChanged)
public:
    //声明父类
    using Super = TaoListModel<QJsonObject>;
    //从json文件读入数据
    Q_INVOKABLE void loadFromJson(const QString& jsonPath, const QString& recursionKey = cRecursionKey);
    //导出到json文件
    Q_INVOKABLE bool saveToJson(const QString& jsonPath, bool compact = false) const;
    Q_INVOKABLE void clear();
    //设置指定节点的数值
    Q_INVOKABLE void setNodeValue(int index, const QString &key, const QVariant &value);
    //在index添加子节点。刷新父级，返回新项index
    Q_INVOKABLE int addNode(int index, const QJsonObject& json);
    Q_INVOKABLE int addNode(const QModelIndex& index, const QJsonObject& json)
    {
        return addNode(index.row(), json);
    }
    //删除。递归删除所有子级,刷新父级
    Q_INVOKABLE void remove(int index);
    Q_INVOKABLE void remove(const QModelIndex& index)
    {
        remove(index.row());
    }
    Q_INVOKABLE QList<int> search(const QString& key, const QString& value, Qt::CaseSensitivity cs = Qt::CaseInsensitive) const;
    //展开子级。只展开一级,不递归
    Q_INVOKABLE void expand(int index);
    Q_INVOKABLE void expand(const QModelIndex& index)
    {
        expand(index.row());
    }
    //折叠子级。递归全部子级。
    Q_INVOKABLE void collapse(int index);
    Q_INVOKABLE void collapse(const QModelIndex& index)
    {
        collapse(index.row());
    }
    //展开到指定项。递归
    Q_INVOKABLE void expandTo(int index);
    Q_INVOKABLE void expandTo(const QModelIndex& index)
    {
        expandTo(index.row());
    }
    //展开全部
    Q_INVOKABLE void expandAll();

    //折叠全部
    Q_INVOKABLE void collapseAll();


    int count() const;

    Q_INVOKABLE QVariant data(int idx, int role = Qt::DisplayRole) const
    {
        return Super::data(Super::index(idx), role);
    }
signals:
    void countChanged();
    ...
};

TaoJsonTreeModel继承于TaoListModel，并提供大量Q_INVOKABLE函数，以供Qml调用。

view

TreeView的模拟实现如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

Item {
    id: root
    readonly property string __depthKey: "TModel_depth"
    readonly property string __expendKey: "TModel_expend"
    readonly property string __childrenExpendKey: "TModel_childrenExpend"
    readonly property string __hasChildendKey: "TModel_hasChildren"

    readonly property string __parentKey: "TModel_parent"
    readonly property string __childrenKey: "TModel_children"
    ...
    ListView {
        id: listView
        anchors.fill: parent
        currentIndex: -1
        delegate: Rectangle {
            id: delegateRect
            width: listView.width
            color: (listView.currentIndex === index || area.hovered) ? config.normalColor : config.darkerColor
            // 根据 expaned 判断是否展开，不展开的情况下高度为0
            height: model.display[__expendKey] === true ? 35 : 0
            // 优化。高度为0时visible为false，不渲染。
            visible: height > 0
            property alias editable: nameEdit.editable
            property alias editItem: nameEdit
            TTextInput {
                id: nameEdit
                anchors.verticalCenter: parent.verticalCenter
                //按深度缩进
                x: root.basePadding + model.display[__depthKey] * root.subPadding
                text: model.display["name"]
                height: parent.height
                width: parent.width * 0.8 - x
                editable: false
                onTEditFinished: {
                    sourceModel.setNodeValue(index, "name", displayText)
                }
            }
            TTransArea {
                id: area
                height: parent.height
                width: parent.width - controlIcon.x
                hoverEnabled: true
                acceptedButtons: Qt.LeftButton | Qt.RightButton
                onPressed: {
                    //单击时切换当前选中项
                    if (listView.currentIndex !== index) {
                        listView.currentIndex = index;
                    } else {
                        listView.currentIndex = -1;
                    }
                }
                onTDoubleClicked: {
                    //双击进入编辑状态
                    delegateRect.editable = true;
                    nameEdit.forceActiveFocus()
                    nameEdit.ensureVisible(0)
                }
            }
            Image {
                id: controlIcon
                anchors {
                    verticalCenter: parent.verticalCenter
                    right: parent.right
                    rightMargin: 20
                }
                //有子节点时，显示小图标
                visible: model.display[__hasChildendKey]
                source: model.display[__childrenExpendKey] ? "qrc:/img/collapse.png" : "qrc:/img/expand.png"
                MouseArea {
                    anchors.fill: parent
                    onClicked: {
                        //点击小图标时，切换折叠、展开的状态
                        if (model.display[__hasChildendKey]) {
                            if( true === model.display[__childrenExpendKey]) {
                                collapse(index)
                            } else {
                                expand(index)
                            }
                        }
                    }
                }
            }
        }
    }
    ...
}

model层并没有扩展role，而是在data函数的role为display时直接返回json数据，

所以delegate中统一使用model.display[xxx]的方式访问数据。

性能测试

测试环境

CPU: Intel i5-8400 2.8GHz 六核

内存: 16GB

OS: Windows10 1909

Qt: 5.12.6

编译器: msvc 2017 x64

测试框架: QTest

测试方法

数据生成

使用node表示根节点的数量，depth表示每个根节点下面嵌套节点的层数。

例如： node 等于 100， depth 等于10，则数据如下：

顶层有100个节点，每个节点下面再嵌套10层，共计节点 100 + 100 * 10 = 1100.

生成json数据的代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

...
//单元测试类
class LoadTest : public QObject {
    Q_OBJECT

public:
    LoadTest();
    ~LoadTest();

    static void genJson(const QPoint& point);

    ...
//私有槽函数会被QTest调用
private slots:
    //初始化
    void initTestCase();
    //清理
    void cleanupTestCase();
    //测试导入
    void test_load();
    //测试导入前，准备数据
    void test_load_data();
    //测试导出
    void test_save();
    //测试导出前，准备数据
    void test_save_data();
};
...
//节点最大值
const int nodeMax = 10000;
//嵌套深度最大值
const int depthMax = 100;

void LoadTest::genJson(const QPoint& point)
{
    using namespace TaoCommon;
    int node = point.x();
    int depth = point.y();
    QJsonArray arr;
    for (int i = 0; i < node; ++i) {
        QJsonObject obj;
        obj["name"] = QString("node_%1").arg(i);
        QVector<QJsonArray> childrenArr = { depth, QJsonArray { QJsonObject {} } };
        //最后一个节点，嵌套层级最深的。
        childrenArr[depth - 1][0] = QJsonObject { { "name", QString("node_%1_%2").arg(i).arg(depth - 1) } };
        //从后往前倒推。
        for (int j = depth - 2; j >= 0; --j) {
            childrenArr[j][0] = QJsonObject { { cRecursionKey, childrenArr[j + 1] }, { "name", QString("node_%1_%2").arg(i).arg(j) } };
        }
        obj[cRecursionKey] = childrenArr[0];
        arr.append(obj);
    }
    writeJsonFile(qApp->applicationDirPath() + QString("/%1_%2.json").arg(node).arg(depth), arr);
}

void LoadTest::initTestCase()
{
    QList<QPoint> list;
    for (int i = 1; i <= nodeMax; i *= 10) {
        for (int j = 1; j <= depthMax; j *= 10) {
            list.append({ i, j });
        }
    }
    auto result = QtConcurrent::map(list, &LoadTest::genJson);
    result.waitForFinished();
}

初始化函数initTestCase中，组织了一个QList，然后使用QtConcurrent::map并发调用genJson函数，生成数据json文件。

node和depth每次扩大10倍。

经过测试，嵌套层数在100以上时，Qt可能会崩溃。要么是QJsonDocument无法解析，要么是Qml挂掉。所以不使用100以上的嵌套级别。

测试过程

QTest十分好用，简单易上手，参考帮助文件即可

例如测试加载的代码如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

void LoadTest::prepareData()
{
    //添加两列数据
    QTest::addColumn<int>("node");
    QTest::addColumn<int>("depth");
    //添加行
    for (int i = 1; i <= nodeMax; i *= 10) {
        for (int j = 1; j <= depthMax; j *= 10) {
            QTest::newRow(QString("%1_%2").arg(i).arg(j).toStdString().c_str()) << i << j;
        }
    }
}
void LoadTest::test_load_data()
{
    //准备数据
    prepareData();
}
void LoadTest::test_load()
{
    using namespace TaoCommon;
    //取数据
    QFETCH(int, node);
    QFETCH(int, depth);
    TaoJsonTreeModel model;
    //性能测试
    QBENCHMARK
    {
        model.loadFromJson(qApp->applicationDirPath() + QString("/%1_%2.json").arg(node).arg(depth));
    }
}

测试结果

一秒内最多可以加载的数据量在十万级别，包括

10000 x 10耗时在 386毫秒，1000 x 100 耗时在671毫秒。

前言

这次讨论Qt与Web混合开发相关技术。

这类技术存在适用场景，例如：Qt项目使用Web大量现成的组件/方案做功能扩展，

Qt项目中性能无关/频繁更新迭代的页面用html单独实现，Qt项目提供Web形式的SDK给

用户做二次开发等等，或者是Web开发人员齐全而Qt/C++人手不足，此类非技术问题，

都可以使用Qt + Web混合开发。

(不适用的请忽略本文)

简介

上次的文章《Qt与Web混合开发》，讨论了Qt与Web混合开发相关技术。

这次通过一个web控制小车的案例，继续讨论相关技术。

本文会先介绍Qt与Web嵌套使用,再介绍Qt与Web分开使用，之后着重讨论分开使用

的一些实现细节，特别是WebChannel通信、WebChannel在Web/typescript中的使用。

Qt与Web嵌套

MiniBrowser

这里以Qt官方的例子MiniBrowser来说明吧。

打开方式如下：

运行效果如下：

这个例子是在Qml中嵌套了WebView。

半透明测试

涛哥做了一个简单的半透明测试。

增加了两个半透明的小方块，蓝色的在WebView上面，红色的在WebView下面。

运行效果也是正确的:

代码是这样的：

红色框中是我增加的代码。

为什么要做半透明测试呢？根据以往的经验,不同渲染方式的两种窗口/组件嵌套在一起，总会出现透明失效之类的问题，例如 qml与Widget嵌套。

渲染原理

涛哥翻了一下Qt源码，了解到渲染的实现方式，Windows平台大致如下：

chromium在单独的进程处理html渲染，并将渲染结果存储在共享内存中；主窗口在需要重绘的时候，从共享内存中获取内容并渲染。

小结

这里的WebView内部封装好了WebEngine，其本身也是一个Item，就和普通的Qml一样，属性绑定、js function都可以正常使用，暂时不深入讨论了。

Qt与Web分离

Qt与Web分离，就是字面意思，Web在单独的浏览器或者App中运行，不和Qt堆在一起。两者通过socket进行通信。

这里用我自己做的例子来说明吧。

先看看效果：

左边是Qt实现的一个简易小车，可以前进和转向。右边是Html5实现的控制端，控制左边的小车。

源码在github上: https://github.com/jaredtao/QtWeb

Qt小车

原版小车

小车来自Qt的D-Bus Remote Controller 例子

原版的例子，实现了通过QDBus 跨进程 控制小车。

(吐槽：这是一个古老的例子,使用了GraphicsView 和QDBus)

(知识拓展1： DBus是unix系统特有的一种进程间通信机制，使用有些复杂。Qt对DBus机制进行了封装/简化，即QDBus模块，

通过xml文件的配置后，把DBus的使用转换成了信号-槽的形式。类似于现在的Qt Remote Objects)

(知识拓展2： Windows本身不支持DBus，网上有socket模拟DBus的方案。参考: https://www.freedesktop.org/wiki/Software/dbus/)

改进小车

我做了一些修改，主要如下：

• 去掉了DBus
• 增加控制按钮
• 增加WebChannel
• 修改Car的实现，导出一些属性和函数。
• 注册Car到WebChannel

这里贴一些关键代码

Car的头文件：

其中要说明的是：

speed和angle属性具备 读、写、change信号。

还有加速、减速、左转、右转四个公开的槽函数。

必要的知识

WebSocket和 QWebSocket

WebSocket 是 HTML5 开始提供的一种在单个 TCP 连接上进行全双工通讯的协议。

WebSocket 使得客户端和服务器之间的数据交换变得更加简单，允许服务端主动向客户端推送数据。在 WebSocket API 中，浏览器和服务器只需要完成一次握手，两者之间就直接可以创建持久性的连接，并进行双向数据传输。

Qt为我们封装好了WebSocket，即QWebSocket和QWebSocketServer，简单易用。

如果你了解socket编程，就看作TCP好了；如果不了解，请先去补充一下知识吧。

WebChannel

按涛哥的理解，WebChannel是在socket上建立的一种通信协议，这个协议的作用是把QObject暴露给远端的HTML。

大致使用流程：

1. Qt程序中，要暴露的QObject全部注册到WebChannel。

2. Qt程序中，启动一个WebSocketServer，等待Html的连接。

3. Html加载好qwebchannel.js文件, 然后去连接WebSocket。

4. 连接建立以后，Qt程序中，由WebChannel接手这个WebSocket，按协议将QObject的各种“元数据”传输给远端Html。

5. Html端，qwebchannel.js处理WebSocket收到的各种“元数据”，用js的Object 动态创建出对应的QObject。

   到这里两边算是做好了准备，可以互相调用了。

   Qt端QObject数据变化只要发出信号，就会由WebChannel自动通知Web端；

   Web端可以主动调用QObject的public的 invok函数、槽函数，以及读、写属性。

Qt启动系统浏览器

在使用WebChannel的时候，Qt端建立了WebSocketServer，之后要把server的路径(例如：ws://127.0.0.1:12345)告诉Html。

一般就是在打开Html的时候带上Query参数，例如： F:\QtWeb\index.html?webChannelBaseUrl=ws://127.0.0.1:12345

Qt的OpenUrl

Qml中有 Qt.openUrlExternally, C++ 中有 QDesktopServices::openUrl，本质一样， 都可以打开一个本地的html网页。

其在Windows平台的底层实现是Win32 API。这里有个Win32 API的缺陷，传Query参数会被丢掉。

C# .net的 Process::Start

涛哥找到了替代的方案:

.net framework / .net core有个启动进程的函数： System.Diagnostics.Process::Start, 可以调用浏览器并传query参数

1
2
3
4
5
6

//C# 启动chrome
System.Diagnostics.Process.Start('chrome', 'F:\QtWeb\index.html?webChannelBaseUrl=ws://127.0.0.1:12345');
//C# 启动firefox
System.Diagnostics.Process.Start('firefox', 'F:\QtWeb\index.html?webChannelBaseUrl=ws://127.0.0.1:12345');
//C# 启动IE
System.Diagnostics.Process.Start('IExplore', 'F:\QtWeb\index.html?webChannelBaseUrl=ws://127.0.0.1:12345');

Qt中直接写C#当然不太好，不过呢，Win7/Win10 系统都带有Powershell，而powershell依赖于.net framework, 我们可以调用powershell来间接使用.net framework。

所以有了下面的代码：

1
2
3
4
5
6
7
8

...
QString psCmd = QString("powershell -noprofile -command \"[void][System.Diagnostics.Process]::Start('%1', '%2')\"").arg(browser).arg(url.toString());
bool ok = QProcess::startDetached(psCmd);
qWarning() << psCmd;
if (!ok) {
    qWarning() << "failed";
}
...

结果完美运行。

Web控制端

目录结构

Web端就按照Web常规流程开发。

Web部分的源码也在前文提到的github仓库，子路径是QtWeb\WebChannelCar\Web

如下是Web部分的目录结构：

脚本用typescript，包管理用npm，打包用webpack，编辑器用vs code, 都中规中矩。

内容比较简单，暂时不需要前端框架，手(复)写(制)的html和css。

Html

html部分比较简单

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

//index.html
<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; chartset=utf-8" />
    <link rel="stylesheet" type="text/css" href="../style/style.css" />
    <link rel="stylesheet" type="text/css" href="../style/layout.css" />
</head>

<body>
    <button id="up" class="green button">加速</button>
    <button id="down" class="red button">减速</button>
    <button id="left" class="blue button">左转</button>
    <button id="right" class="blue button">右转</button>
    <img id="img" src="../img/disconnected.svg" />
    <div>
        <div>
            <label>速度: </label>
            <label id="speed">0</label>
        </div>
        <div>
            <label>角度: </label>
            <label id="angle">0</label>
        </div>
    </div>
</body>
<script src="../out/main.js">

</script>

</html>

样式和布局全靠css,这里就不贴了。

TypeScript

脚本部分需要细说了。

src文件夹为全部脚本，目录结构如下：

TypeScript中的QObject

从main开始, 加点注释：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

//main.ts
import WebChannelCore from "./webchannelCore";
//window加载时回调，入口
window.onload = () => {
    //初始化WebChannel，传参为两个回调，分别对应WebChannel建立连接和连接断开。
    WebChannelCore.initialize(onInit, onUninit);
}
//WebChannel建立连接的处理
function onInit() {
    //换图标
    (window as any).document.getElementById("img").src = "../img/connected.svg";
    //获取QObject对象
    let car = WebChannelCore.SDK.car;
    
    //取dom树上的组件

    let upBtn = (window as any).document.getElementById("up");
    let downBtn = (window as any).document.getElementById("down");
    let leftBtn = (window as any).document.getElementById("left");
    let rightBtn = (window as any).document.getElementById("right");

    let speedLabel = (window as any).document.getElementById("speed");
    let angleLabel = (window as any).document.getElementById("angle");
    //绑定按钮点击事件
    upBtn.onclick = () => {
        //调用QObject的接口
        car.accelerate();
    }
    downBtn.onclick = () => {
        car.decelerate();
    }
    leftBtn.onclick = () => {
        car.turnLeft();
    }
    rightBtn.onclick = () => {
        car.turnRight();
    }
    //QObject的信号连接到js 回调
    car.speedChanged.connect(onSpeedChanged);
    car.angleChanged.connect(onAngleChanged);
}
//WebChannel断开连接的处理
function onUninit() {
    //换图标
    (window as any).document.getElementById("img").src = "../img/disconnected.svg";
}
//异步更新 speed
async function onSpeedChanged() {
    let speedLabel = (window as any).document.getElementById("speed");
    let car = WebChannelCore.SDK.car;
    //获取speed，异步等待。
    //注意这里改造过qwebchannel.js，才能使用await。
    speedLabel.textContent = await car.getSpeed();
}
//异步更新 angle
async function onAngleChanged() {
    let angleLabel = (window as any).document.getElementById("angle");
    let car = WebChannelCore.SDK.car;
    //获取angle，异步等待。
    //注意这里改造过qwebchannel.js，才能使用await。
    angleLabel.textContent = await car.getAngle();
}

可以看到我们从WebChannelCore.SDK 中获取了一个car对象，之后就当作QObject来用了，包括调用它的函数、连接change信号、访问属性等。

这一切都得益于WebSocket/WebChannel.

TypeScript中连接websocket

接下来看一下WebChannelCore的实现

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

//WebChannelCore.ts
import { QWebChannel } from './qwebchannel';

type callback = () => void;
export default class WebChannelCore {
    public static SDK: any = undefined;
    private static connectedCb: callback;
    private static disconnectedCb: callback;
    private static socket: WebSocket;
    
    //初始化函数
    public static initialize(connectedCb: callback = () => { }, disconnectedCb: callback = () => { }) {
        if (WebChannelCore.SDK != undefined) {
            return;
        }
        //保存两个回调
        WebChannelCore.connectedCb = connectedCb;
        WebChannelCore.disconnectedCb = disconnectedCb;

        try {
            //调用link，并传入两个回调参数
            WebChannelCore.link(
                (socket) => {
                  //socket连接成功时，创建QWebChannel
                    QWebChannel(socket, (channel: any) => {
                        WebChannelCore.SDK = channel.objects;
                        WebChannelCore.connectedCb();
                    });
                }
                , (error) => {
                  //socket出错
                    console.log("socket error", error);
                    WebChannelCore.disconnectedCb();
                });
        } catch (error) {
            console.log("socket exception:", error);
            WebChannelCore.disconnectedCb();
            WebChannelCore.SDK = undefined;
        }
    }

    private static link(resolve: (socket: WebSocket) => void, reject: (error: Event | CloseEvent) => void) {
        //获取Query参数中的websocket地址
        let baseUrl = "ws://localhost:12345";
        if (window.location.search != "") {
            baseUrl = (/[?&]webChannelBaseUrl=([A-Za-z0-9\-:/\.]+)/.exec(window.location.search)![1]);
        }
        console.log("Connectiong to WebSocket server at: ", baseUrl);
        
        //创建WebSocket
        let socket = new WebSocket(baseUrl);
        WebChannelCore.socket = socket;
        //WebSocket的事件处理
        socket.onopen = () => {
            resolve(socket);
        };
        socket.onerror = (error) => {
            reject(error);
        };
        socket.onclose = (error) => {
            reject(error);
        };
    }
}
(window as any).SDK = WebChannelCore.SDK;

这部分代码不复杂，主要是连接WebSocket，连接好之后创建一个QWebChannel。

TypeScript中的QWebChannel

观察仔细的同学会发现，src文件夹下面，没有叫‘qwebchannel.ts’的文件，而是‘qwebchannel.js’,和一个‘qwebchannel.d.ts’

这涉及到另一个话题：

TypeScript中使用javaScript

‘qwebchannel.js’是Qt官方提供的，在js中用足够了。

而我们这里是用TypeScript，按照TypeScript的规则，直接引入js是不行的，需要一个声明文件 xxx.d.ts

所以我们增加了一个qwebchannel.d.ts文件。

（熟悉C/C++的同学，可以把d.ts看作typescript的头文件）

内容如下：

1
2

//qwebchannel.d.ts
export declare function QWebChannel(transport: any, initCallback: Function): void;

只是导出了一个函数。

这个函数的实现在‘qwebchannel.js’中:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

//qwebchannel.js
"use strict";

var QWebChannelMessageTypes = {
    signal: 1,
    propertyUpdate: 2,
    init: 3,
    idle: 4,
    debug: 5,
    invokeMethod: 6,
    connectToSignal: 7,
    disconnectFromSignal: 8,
    setProperty: 9,
    response: 10,
};

var QWebChannel = function(transport, initCallback)
{
    if (typeof transport !== "object" || typeof transport.send !== "function") {
        console.error("The QWebChannel expects a transport object with a send function and onmessage callback property." +
                      " Given is: transport: " + typeof(transport) + ", transport.send: " + typeof(transport.send));
        return;
    }
    ...
}
function QObject(name, data, webChannel)
{
  ...
}

这个代码比较长，就不全部贴出来了。主要实现了两个类，QWebChannel和QObject。

QWebChannel就是用来接管websocket的，而QObject是用js Object模拟的 Qt的 QObject。

这一块不细说了，感兴趣的同学可以自己去研究源码。

改进qwebchannel.js以支持await

Qt默认的qwebchannel.js在实际使用过程中，有些不好的地方，就是函数的返回值不是直接返回，而是要在回调函数中获取。

比如car.getAngle要这样用：

1
2
3
4

let angle = 0;
car.getAngle((value:number)=> {
  angle = value;
});

我们的实际项目中，有大量带返回值的api，这样的用法每次都嵌套一个回调函数，很不友好，容易造成回调地狱。

我们同事的解决方案是，在typescript中把这些api再用Promise封装一层，外面用await调用。

例如这样封装一层：

1
2
3
4
5
6
7

function getAngle () {
    return new Promise((resolve)=>{
        car.getAngle((value:number)=> {
            resolve(value);
        });
  });
}

使用和前面的代码一样：

1
2
3
4
5
6
7
8

//异步更新 angle
async function onAngleChanged() {
    let angleLabel = (window as any).document.getElementById("angle");
    let car = WebChannelCore.SDK.car;
    //获取angle，异步等待。
    //注意这里改造过qwebchannel.js，才能使用await。
    angleLabel.textContent = await car.getAngle();
}

这种解决方案规避了回调地狱，但是工作量增加了。

涛哥思考良久，稍微改造一下qwebchannel.js，自动把Promise加进去，也不需要再额外封装了。

改动如下：

QObject to Typescript

我们在Qt 程序中写了QObject，然后暴露给了ts。

在ts这边，一般也需要提供一个声明文件，明确有哪些api可用。

例如我们的car声明：

1
2
3
4
5
6
7
8
9
10
11
12
13

//CarObject.ts
declare class Car {
    get speed():number;
    set speed(value:number);

    get angle():number;
    set angle(vlaue:number);

    public accelerate():void;
    public decelerate():void;
    public turnLeft():void;
    public turnRight():void;
}

这里涛哥写了一个小工具，能够解析Qt中的QObject，并生成对应的ts文件。

当然还是实验阶段，有兴趣的也可以关注一下

https://github.com/jaredtao/QObject2TypeScript

前言

这次讨论Qt与Web混合开发相关技术。

这类技术存在适用场景，例如：Qt项目使用Web大量现成的组件/方案做功能扩展，

Qt项目中性能无关/频繁更新迭代的页面用html单独实现，Qt项目提供Web形式的SDK给

用户做二次开发等等，或者是Web开发人员齐全而Qt/C++人手不足，此类非技术问题，

都可以使用Qt + Web混合开发。

(不适用的请忽略本文)

简介

这篇文章，会先整体介绍一下Qt的各种Web方案,再提供简单的Demo，并做一些简要的说明。

之后的一篇文章，会通过一个Web控制Qt端小车的案例，来做进一步讨论。

Qt的Web方案

Qt提供的Web方案主要包括 WebEngine/WebView、Quick WebGL Stream、QtWebAssembly三种。

Quick WebGL Stream

可以参考Qt官方的WebGL Stream介绍文档

https://resources.qt.io/cn/qt-quick-webgl-release-512
​
resources.qt.io
WebGL Stream在5.12中正式发布，其本质是一种通信技术，将已有的QtQuick程序中渲染指令和数据，通过socket传输给Web端，由WebGL实现界面渲染。

其使用方式非常的简单，无需修改源码，应用程序启动时，带上端口参数，例如：

./your-qt-application -platform webgl:port=8998
(相当于应用程序变成了一个服务器端程序)

这样程序就在后端运行，看不到界面了，之后浏览器打开本地网址 localhost:8998 或者内网地址/映射后的公网地址，就能在浏览器中看到程序页面。

WebGL Stream的应用不多，Qt官方给的案例是：欧洲某工厂的大量传感器监测设备，都以WebGL Stream的方式运行Qt 程序，本身都不带显卡和显示器，而在控制中心的显卡/显示器上，通过Web打开网页的方式，查看每个设备的运行状况。因此节约了大量显卡/显示器的成本。类比于网吧的无硬盘系统。

涛哥相信，未来结合5G技术会有不错的应用场景。

Qt WebAssembly

Qt WebAssembly技术，在5.13中正式发布。本质是把Qt程序编译成浏览器支持的二进制文件，由浏览器加载运行。

一方面可以将现有的Qt程序编译成Web，另一方面可以用Qt/C++来弥补Web程序的性能短板。

Qt WebAssembly在使用细节上还有一些坑的地方，需要踩一踩。后续我再写文章吧。

Qt WebEngine/WebView

Qt提供了WebEngine模块以支持Web功能。

Qt WebEngine基于google的开源浏览器chromium实现，类似的项目还有cef、miniblink等等。

QtWebEngine可以看作是一个完整的chromium浏览器。

（WebView是同类的方案，稍微有些区别。后文再说。）

QtWebEngine的更新情况

浏览器技术十分的庞大，这里先不深入展开，先来关注一下Qt WebEngine对chromium的跟进情况。

数据来源于Qt wiki，Qt每个版本的change log

可以看到Qt在WebEngine模块，一直持续跟进Chromium的更新。

当前(2020/3/4)最新的chromium版本是80。

WebEngine的架构

QtWebEngine提供了C++和Qml的接口，可以在Widget/Qml中渲染HTML、XHTML、SVG，

也支持CSS样式表和JavaScript脚本。

QtWebEngine的架构图如下

基于Chromium封装了一个WebEngineCore模块，在此之上，

WebEngine Widgets模块专门用于Widget项目，

WebEngine 模块用于Qml项目，

WebEngineProcess则是一个单独的进程，用来渲染页面、运行js脚本。

Web在单独的进程里，我们开发的时候知道这一点就好了，不需要额外关注，

只要在发布的时候，带上QTDIR目录下的可执行程序QtWebEngineProcess即可。

(这里提一下底层实现原理，使用了进程间共享OpenGL上下文的方式, 实现多个进程的UI混合在一起)

WebEngine的平台要求

(以Qt5.12为参考)

首先一条是：不支持静态编译 (因为依赖的chromium、chromium本身的依赖库 不能静态编译)

接下来再看看各平台的要求和限制：

Windows

编译器要 Visual Studio 2017 version 15.8 以上

系统环境要 Windows 10 SDK

默认只支持X64版本，如果要x86版本，要自己编译qt源码。

MacOS

• MacOS 10.12以上

• XCode 8.3.3以上

• MacOS 10.12以上 SDK

不支持32-bit

不兼容 Mac App Store (chromium使用了私有api，App Sandbox和chromium Sandbox优先级问题)

Linux

编译器要 clang， 或者 gcc 5以上

需要pkg-config来探测依赖库，dbus-1和 fontconfig是必须的。

如果配置了xcb，还要额外配置相关库。

WebView

Qt还提供了一个WebView组件，可以用来将Web内容嵌入到Qml程序中。(这个没有提供Widget的接口)

WebView组件的实现，使用了平台原生api，在移动端意义重大，特别是在ios平台，使用

原生的web view，这样就能兼容App Store了。

在Windows/MacOS/Linux平台，则是渲染部分还是使用了WebEngine。

WebView的使用可以参考官方例子Minibrowser

WebEngine的使用

WebEngine Widget最简Demo

源代码

这里示例一个最简单的demo, 使用WebEngine Widget模块提供的QWebEngineView：

1
2
3
4
5
6
7

//Demo.pro
QT += core gui webenginewidgets

CONFIG += c++11

SOURCES += \
        main.cpp

注意pro文件中包含的Qt模块

1
2
3
4
5
6
7
8
9
10
11
12
13

//main.cpp
#include <QApplication>
#include <QWebEngineView>
int main(int argc, char **argv)
{
    QApplication app(argc, argv);

    QWebEngineView view;
    view.load(QUrl("https://www.zhihu.com/"));
    view.show();

    return app.exec();
}

运行结果

上面代码以打开知乎首页为例，运行结果如下

最小发布包

涛哥尝试了在Windows平台，做出可用的最小发布包:

尺寸在170M左右。这些依赖项中，除了常见的Qt必备项platforms、Qt5Core、Qt5Gui等，

Qt5WebEngineCore是最大的一个，有70M。QtWebEngineProcess.exe是新增加的一个exe程序，

前文说架构图时提到的单独进程就是这个程序实现。

resources/icudtl.dat在其它浏览器引擎中也常看到。

translations/qtwebengine_locales是WebEngine的翻译项，不带可能会发生翻译问题。

Qt5Positioning、Qt5PrintSupport一般不怎么用，但是不带这两个程序起不来。

同时发现Qml和Quick模块也是必须的，Qt5QuickWidgets也用上了。

涛哥查看源码后发现WebEngineCore模块依赖Quick和Qml模块。

WebEngine Qml最简Demo

再做一个纯Qml的Demo

源码

pro中增加webengine模块即可

1
2
3
4
5
6
7
8
9
10

//WebQml.pro
QT += core gui quick qml webengine

CONFIG += c++11

SOURCES += \
        main.cpp

RESOURCES += \
    Qrc.qrc

注意初始化。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

//main.cpp
#include <QGuiApplication>
#include <QQuickView>
#include <QtWebEngine>
int main(int argc, char *argv[])
{
    QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);

    QGuiApplication a(argc, argv);
    //初始化。时机在QApp之后，Window/View构造之前。
    QtWebEngine::initialize();

    QQuickView view;
    view.setSource(QUrl("qrc:/main.qml"));
    view.show();
    return a.exec();
}

qml导入模块，填入url

1
2
3
4
5
6
7
8
9
10
11

//main.qml
import QtQuick 2.0
import QtWebEngine 1.8
Item {
    width: 800
    height: 600
    WebEngineView {
        anchors.fill: parent
        url: "https://www.zhihu.com"
    }
}

运行结果

运行结果和上一个Demo一样

最小发布包

这回可以去掉Widget模块

同时也去掉不必要的翻译文件。包大小160M左右，和前面的差别不大。

Qt for android 环境搭建，以Windows平台 Qt5.12为基准。

安装Qt

需要先安装Android版的Qt。 一般在Qt的安装包中都有集成，安装的时候勾上就行

安装必备工具链

Android开发必备的工具链包括：

• Java JDK
• Android SDK
• Android NDK

下载链接分别点击QtCreator中的按钮就能跳转到

如果不能访问，找镜像网站。

这里要注意版本，和Qt5.12适配的才能用。Qt官方也没有说，都是自己试出来的。

JDK： OpenJDK没有试过，Oracle 的JDK， LTS版本有 1.8 和1.11，但是目前的Android SDK都是基于1.8开发的，1.11还用不了。

SDK： SDK下最新的就好。

NDK： Qt5.12能用的NDK是R19C，当前最新的是R20，里面工具链修改了，Qt还没有跟上，得后续版本（Qt5.12.5）

都装好就行了，不要去修改环境变量。直接在QtCreator里面选好路径即可。

更新SDK，build Tool

到SDK 管理页面，安装一堆必要的工具和镜像。注意Android SDK Build Tool ， 能用的是28.0.3，最新的29用不了。

创建项目

创建一个Qt项目，使用Andorid kit。

之后在项目管理页面中，点一下 “Create Template”按钮，生成一堆android相关配置文件。

之后去项目路径下，找到build.gradle文件

把buildToolsVersion改成”28.0.3”

最后编译运行就可以了。模拟器或真机连接，就不说了。

简介

在之前两篇文章《github-Actions自动化编译》《github-Actions自动化发行》中，

介绍了github-Actions的一些用法，其中有部分配置，已经有了缓存相关的步骤。

这里专门开一篇文章，来记录github-Actions的缓存优化相关的知识。

原理

缓存actions模板

github-Actions提供了缓存模板cache

缓存文档

官方文档也有说明 缓存文档

缓存大致原理就是把目标路径打包存储下来，并记录一个唯一key。

下次启动时，根据key去查找。找到了就再按路径解压开。

缓存大小限制

注意缓存有大小限制。对于免费用户，单个包不能超过500MB，整个仓库的缓存不能超过2G。

缓存运作流程

一般我们在任务步骤中增加一个cache

1
2
3
4
5
6

steps:
  ...
  - use: actions/cache@v1
    with:
      ...
  ...

那么在这个地方，缓存执行的操作是restore。

在steps的末尾，会自动增加一个PostCache，执行的操作是record。

Qt项目的缓存优化

Qt项目每次运行Actions时，都是先通过install-qt-action模板，安装Qt，之后再获取代码，编译运行。

安装Qt这个步骤，可快可慢，涛哥在windows平台测试下来，平均要1分30秒左右。

加上cache后，平均只有25秒。

无缓存的配置

先看一个Qt项目的编译配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

name: Windows
on: [push,pull_request]
jobs:
  build:
    name: Build
    runs-on: windows-latest
    strategy:
      matrix:
        qt_ver: [5.12.6]
        qt_target: [desktop]
        qt_arch: [win64_msvc2017_64, win32_msvc2017]
        include:
          - qt_arch: win64_msvc2017_64
            msvc_arch: x64
          - qt_arch: win32_msvc2017
            msvc_arch: x86
    # 步骤
    steps:
      # 安装Qt
      - name: Install Qt
        uses: jurplel/install-qt-action@v2.0.0
        with:
          version: ${{ matrix.qt_ver }}
          target: ${{ matrix.qt_target }}
          arch: ${{ matrix.qt_arch }}
      # 拉取代码
      - uses: actions/checkout@v1
        with:
          fetch-depth: 1
      # 编译msvc
      - name: build-msvc
        shell: cmd
        env:
          vc_arch: ${{ matrix.msvc_arch }}
        run: |
          call "C:\Program Files (x86)\Microsoft Visual Studio\2019\Enterprise\VC\Auxiliary\Build\vcvarsall.bat" %vc_arch%
          qmake
          nmake

加缓存

缓存步骤，一般尽量写steps最前面。

1
2
3
4
5
6
7
8
9

# 步骤
steps:
  # 缓存
  - name: cacheQt
    id: WindowsCacheQt
    uses: actions/cache@v1
    with:
      path: ../Qt/${{matrix.qt_ver}}/${{matrix.qt_arch_install}}
      key: ${{ runner.os }}-Qt/${{matrix.qt_ver}}/${{matrix.qt_arch}}

install-qt-action有默认的Qt安装路径${RUNNER_WORKSPACE}，不过这个环境变量不一定能取到。

涛哥实际测试下来，以当前路径的上一级作为Qt路径即可。

环境变量还原

缓存只是把文件还原了，环境变量并没有还原，我们还需要手动还原环境变量。

install-qt-action这个模板增加了一个环境变量Qt5_Dir,值为Qt的安装路径,并把对应的bin添加到了Path。

我们要做的，就是在缓存恢复成功后，重新设置这两个变量，并去掉install-qt的步骤。

1
2
3
4
5
6
7
8
9

- name: setupQt
  if: steps.WindowsCacheQt.outputs.cache-hit == 'true'
  shell: pwsh
  env:
    QtPath: ../Qt/${{matrix.qt_ver}}/${{matrix.qt_arch_install}}
  run: |
    $qt_Path=${env:QtPath}
    echo "::set-env name=Qt5_Dir::$qt_Path"
    echo "::add-path::$qt_Path/bin"