qmlformat

qmlformat是一款根据QML 编码规范自动格式化 QML 文件的工具。

选项和设置

您可以通过命令行选项配置 qmlformat。选项分为两类：一类直接与格式化相关，另一类用于控制该工具的行为。

以下选项仅影响工具的行为：

下一组选项控制文件的格式化方式，也可以通过设置文件进行控制。

对于布尔选项，请在命令行中传递相应标志，或在设置文件中将变量设置为true 以启用该行为。

参数

用法

qmlformat具有灵活性，可根据您的需求进行配置。当在不可信代码环境中运行时（例如在公共持续集成（CI）环境中进行测试时对 QML 文件进行格式化），应将qmlformat部署在沙箱、容器或其他安全环境中。

输出

qmlformat 将文件的格式化版本写入标准输出（stdout）。若要就地更新文件，请指定-i 标志。

将属性、函数和信号分组

使用-n 或--normalize 标志时，qmlformat 会按名称对所有属性、函数和信号进行分组和排序，而不是保留原有的顺序。

例如：

import QtQuick

QtObject {
    signal s2()
    property int h
    function z() {}
    property int w
    function y() {}
    id: asdf
    signal s1()

    property Item myItem2: Item {
        TextEdit {}
        Rectangle {}
    }
    property Item myItem: Item {
        Rectangle {}
        TextEdit {}
    }
}

将被格式化为：

import QtQuick

QtObject {
    id: asdf

    property int h
    property Item myItem: Item {
        Rectangle {
        }
        TextEdit {
        }
    }
    property Item myItem2: Item {
        TextEdit {
        }
        Rectangle {
        }
    }
    property int w

    signal s1
    signal s2

    function y() {
    }
    function z() {
    }
}

若要按属性分组而不按名称排序，请改用--group-attributes-together 。

这会将前面的代码片段格式化为：

import QtQuick

QtObject {
    id: asdf

    property int h
    property int w
    property Item myItem2: Item {
        TextEdit {
        }
        Rectangle {
        }
    }
    property Item myItem: Item {
        Rectangle {
        }
        TextEdit {
        }
    }

    signal s2
    signal s1

    function z() {
    }
    function y() {
    }
}

此选项的优先级高于 `--normalize`。

设置文件

您可以通过在项目源代码或项目源代码文件夹的父目录中包含一个设置文件（.qmlformat.ini ）来配置qmlformat。您可以通过传递--write-defaults 标志来获取默认设置文件。这将在当前工作目录中生成.qmlformat.ini 文件。

格式化文件列表

虽然您可以将待格式化的文件列表作为参数传递，但 qmlformat 还提供了-F 选项，用于格式化存储在文件中的文件集。在这种情况下，格式化操作将就地进行。

// FileList.txt
main.qml
mycomponent.qml

要使用此列表：

qmlformat -F FileList.txt

分号规则

--semicolon-rule 选项允许您自定义在 JS 语句末尾添加分号的行为。

支持以下值：

• always - 始终添加分号（默认）。
• essential - 除非省略分号会导致问题，否则移除分号。

使用注释禁用格式化

您可以使用特殊注释暂时禁用 qmlformat。

• // qmlformat off 将从该行起关闭格式化。
• // qmlformat on 在关闭格式化后，此注释会重新启用格式化。

这使您能够保留手动调整过的代码或复杂结构，而不会被 qmlformat 改变其布局。格式化功能将保持关闭状态，直到遇到下一个// qmlformat on 注释，或者如果未找到重新启用的指令，则保持关闭直至文件结尾。

使用格式化指令时，请注意以下几点：

• 指令必须独占一行。
• 不支持嵌套指令。仅考虑第一个// qmlformat off 和紧随其后的// qmlformat on 。禁用区域内的任何其他指令均会被忽略。
• 在规范化格式化模式下、启用sortImports 时，或使用任何会重新排序原始文档的选项时，指令将被忽略。在这些情况下，始终应用格式化。