本页内容

svgtoqml

svgtoqml 是 Qt 随附的一个命令行工具,用于将 SVG 文档转换为 QML 文件。生成的 QML 文件随后可作为组件用于Qt Quick 应用程序中。天气预报示例中包含多个使用此工具生成的 QML 文件。

概述

svgtoqml 将把SVG文件转换为使用Qt Quick 基本图形的QML文件。由于Qt Quick 支持可缩放矢量图形,生成的控件将在可能范围内实现平滑变换。作为基准,该工具支持SVG Tiny 1.2规范中的大部分静态功能。 某些附加功能根据具体情况提供支持。交互功能和动画不被支持。

使用方法

svgtoqml 的基本用法是提供一个输入文件和一个输出文件:svgtoqml input.svg output.qml 。这将读取input.svg 文件,并将其转换为output.qml 中对应的Qt Quick 场景,该场景随后可作为Qt Quick 应用程序的一部分使用。

此外,它还支持以下选项:

选项描述
--no-assume-trusted-source表示输入文件为不可信文件,应启用额外的检查和限制。默认情况下,SVG文件将使用AssumeTrustedSource option 进行解析。传递此参数将取消该选项。
--copyright-statement <string>在生成的文件开头添加 <string> 作为注释。
-c,--curve-renderer启用曲线渲染器后端,用于 Qt Quick Shapes。这可在场景中实现平滑、抗锯齿的形状,而无需多采样,但会带来一些额外开销。
-a,--asynchronous-shapes在生成的场景中,为所有Shape 元素启用{QtQuick.Shapes::Shape::asynchronous}{asynchronous}模式。这可能会提高CPU利用率和响应速度。
-p,--optimize-paths在将路径写入 QML 文件之前启用路径优化,这可能会加快后续的加载和渲染速度。
--outline-stroke-mode绘制填充形状的轮廓(边界线),而非原始路径。
-t,--type-name <string>输出将使用类型名称 <string> 代替 `Shape`。这允许使用自定义项来覆盖 `Shape ` 项的默认行为。
-v,--view显示Qt Quick 项生成后的预览效果。

可通过在构建中调用qt_target_qml_from_svg()CMake 函数自动调用该工具。

与其他选项的比较

在Qt Quick 中包含 SVG 内容有多种选项。以下将概述svgtoqml 在其中所处的位置。

与其他方案的比较Qt SVG

Qt SVG 是一个为 SVG 文件提供解析器和软件渲染器的模块。此外,它还包含一个图像加载器插件,因此Image 元素可直接在Qt Quick 中加载 SVG 文件。随后,SVG 将被栅格化并以指定尺寸缓存,重绘操作的开销相当低。 但如果要放大图像而不出现像素化,则需要以不同尺寸重新加载图像,这反而会消耗较多的资源。

svgtoqml (以及 `VectorImage ` 组件)是渲染相同内容的替代方案。一旦加载到 `Qt Quick` 中,即可在保留 GPU 内存中渲染场景所需几何数据的同时更改变换。因此,矢量图像可以在不同比例下重绘,且开销极小。

然而,如果图像尺寸在应用程序生命周期内不会改变,将 SVG 作为Image 加载会更高效。在这种情况下,如果 SVG 始终仅以可能尺寸中的一小部分进行渲染,请考虑将其预栅格化为加载效率更高的图像格式,例如PNG 。

与 VectorImage 的比较

VectorImage 组件提供了与svgtoqml 相同的基本功能,但它不预先生成Qt Quick 场景的QML文件,而是运行时动态创建场景。这使得可以加载在构建时未提供的SVG文件,从而提供了更大的灵活性。 使用svgtoqml 预生成场景,可在加载前对场景进行优化。因此,对于在构建时已有的文件,svgtoqml 是首选方案。

与 PathSvg 的比较

PathSvg 组件是 Qt Quick Shapes 模块的一部分。它提供了一种使用 SVG 语法定义路径的方法,其中路径的控制点以字符串形式指定。 它不支持加载 SVG 文件,因此不能直接替代svgtoqml 。如果一个复杂的 SVG 文件包含应用程序所需的特定形状,那么将该路径描述复制到PathSvg 中,可能比生成完整的文件更为便捷。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.