qmlformat
qmlformat
qmlformat是一种按照QML 编码约定自动格式化 QML 文件的工具。
选项和设置
qmlformat 可以通过命令行选项进行配置。有两组选项：与格式化直接相关的选项，以及控制工具行为的选项。
以下选项只影响工具行为：
| 命令行选项 | 说明 | |
|---|---|---|
-h,--help | 显示命令行选项的帮助。 | |
--help-all | 显示帮助，包括 Qt 通用选项。 | |
-v,--version | 显示版本信息。 | |
-V,--verbose | 详细模式。输出更详细的信息。 | |
--write-defaults | 将默认设置写入 .qmlformat.ini 并退出（警告：这将覆盖任何现有设置和注释！）。 | |
--output-options | 输出所有可用选项、默认值以及值或类型提示 | |
--ignore-settings | 忽略所有设置文件，只考虑命令行选项 | |
-i,--inplace | 就地编辑文件，而不是输出到 stdout。 | |
-f,--force | 即使出现错误也能继续运行。 | |
-F,--files <file> | 就地格式化文件中列出的所有文件 |
下一组选项控制文件的格式化方式，也可以通过设置文件进行控制：
| 命令行选项 | 设置名称 | 默认状态/值 | 说明 |
|---|---|---|---|
-t,--tabs | 使用标签 | 禁用/假 | 使用制表符代替空格。 在命令行调用中，可以通过传递标志启用该行为。 在设置文件中，可通过将相关变量设置为 "true "来启用该行为。 |
-w,--indent-width <width> | 缩进宽度 | 4 | 缩进时使用多少个空格。 |
-W,--column-width <width> | 最大列宽 | -1 | 如果行宽超过指定宽度，则将行分成多行。使用 -1 可禁用换行。(默认值）。 |
-n,--normalize | 规范化顺序 | 禁用/假 | 根据 QML 编码指南重新排列对象的属性。 在命令行调用中，可通过传递标志启用该行为。 在设置文件中，可通过将相关变量设置为 "true "来启用该行为。 |
-l,--newline <newline> | 换行类型 | 本地 | 重写要使用的换行格式（native,macos,unix,windows ）。 |
-S,--sort-imports | 排序导入 | 禁用/假 | 按字母顺序对导入进行排序（警告：如果给定的名称标识了多个模块中的类型，这可能会改变语义！）。 在命令行调用中，可以通过传递标志启用该行为。 在设置文件中，可通过将相关变量设置为 "true "来启用该行为。 |
--objects-spacing | 对象间距 | 禁用/假 | 确保对象之间有空格（仅适用于normalize ）。在命令行调用中，可以通过传递标志启用该行为。 在设置文件中，可通过将相关变量设置为 "true "来启用该行为。 |
--functions-spacing | 函数间距 | 禁用/假 | 确保函数之间有空格（仅适用于normalize ）。在命令行调用中，可通过传递标志启用该行为。 在设置文件中，可通过将相关变量设置为 "true "来启用该行为。 |
--group-attributes-together | 属性分组 | 禁用/假 | 根据 QML 编码指南对对象的属性进行重新排序和分组。暗示--normalize 。在命令行调用中，可通过传递标志启用该行为。 在设置文件中，可通过将相关变量设置为 "true "来启用该行为。 |
--single-line-empty-objects | 单行空对象 | 禁用/假 | 在单行上写入空对象（仅适用于normalize ）。在命令行调用中，可以通过传递标志启用该行为。 在设置文件中，可通过将相关变量设置为 "true "来启用该行为。 |
--semicolon-rule | 分号规则 | 总是 | 自定义在 JS 语句末尾添加分号 (always,essential)。注： 请参阅分号规则了解更多详情。 |
参数
| 参数： |
|---|
| 文件名 |
详细信息
qmlformat非常灵活，可以根据需要进行配置。
输出
qmlformat 会将格式化后的文件写入 stdout。如果希望就地更新文件，请指定-i 标志。
将属性、函数和信号组合在一起
使用-n 或--normalize 标志，qmlformat会将所有属性、函数和信号分组，而不是保留你指定的顺序。
设置文件
你可以通过在项目源代码或项目源代码文件夹的父目录中包含设置文件.qmlformat.ini 来配置qmlformat。通过--write-defaults 标志可以获得默认设置文件。这会在当前工作目录下生成.qmlformat.ini 文件。
警告： --write-defaults 会覆盖任何现有设置和注释！
格式化文件列表
虽然你可以把要格式化的文件列表作为参数传递，但 qmlformat 提供了-F 选项，用于格式化存储在文件中的一组文件。在这种情况下，格式化将就地进行。
// FileList.txt main.qml mycomponent.qml
那么，使用它就像
qmlformat -F FileList.txt
注意： 如果文件中包含无效条目，例如，文件路径不存在或文件路径有效但内容是无效的 qml 文档，那么qmlformat 将对该特定条目出错。它仍会格式化有效的文件条目。
警告 如果提供 -F 选项，qmlformat 将忽略位置参数。
分号规则
--semicolon-rule 选项允许你自定义在 JS 语句末尾添加分号。可接受以下值：
always- 始终添加分号（默认）。essential- 删除分号，除非省略分号会导致问题。
禁用注释格式
你可以使用特殊注释暂时禁用 qmlformat。
// qmlformat off从该行开始关闭格式化// qmlformat on在关闭格式化后打开
这样，你就可以保留手工调整过的代码或复杂结构，而无需qmlformat 更改它们的布局。在下一个// qmlformat on 注释之前，格式设置一直处于关闭状态；如果找不到重新启用的注释，则一直到文件结束。
注意： 指令必须独立成行。
注意： 不支持嵌套指令。只考虑第一个// qmlformat off 和下一个// qmlformat on 。禁用区域内的任何其他指令都将被忽略。
注意： 在规范化格式化模式下、启用sortImports 时或使用任何对原始文档重新排序的选项时，这些指令将被忽略。在这些情况下，格式化始终会被应用。
© 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.
