qmlformat

qmlformat은 QML 코딩 규약에 따라 QML 파일의 서식을 자동으로 조정하는 도구입니다.

옵션 및 설정

qmlformat은 명령줄 옵션을 사용하여 구성할 수 있습니다. 옵션은 서식과 직접 관련된 옵션과 도구의 동작을 제어하는 옵션, 이렇게 두 가지 그룹으로 나뉩니다.

다음 옵션들은 도구의 동작에만 영향을 미칩니다:

다음 옵션 그룹은 파일의 서식 지정 방식을 제어하며, 설정 파일을 통해서도 제어할 수 있습니다.

부울 옵션의 경우, 명령줄에서 해당 플래그를 전달하거나 설정 파일에서 변수를 true 로 설정하여 해당 동작을 활성화하십시오.

인수

사용법

qmlformat은 유연하며 필요에 따라 구성할 수 있습니다. qmlformat은 신뢰할 수 없는 코드에서 실행될 때(예: 공개 CI 환경에서 테스트 중 QML 파일 서식을 지정할 때) 샌드박스, 컨테이너 또는 기타 안전한 환경에 배포해야 합니다.

출력

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 `가 활성화된 경우, 또는 원본 문서의 순서를 재조정하는 옵션이 사용된 경우에는 지시어가 무시됩니다. 이러한 경우 서식 지정은 항상 적용됩니다.