qmlformat

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

사용법:
qmlformat[옵션] 인수

옵션 및 설정

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`	사용탭	disabled/false	공백 대신 탭을 사용합니다. 명령줄 호출에서 플래그를 전달하여 이 동작을 활성화할 수 있습니다. 설정 파일에서 관련 변수를 "true"로 설정하여 동작을 활성화할 수 있습니다.
`-w`, `--indent-width <width>`	IndentWidth	4	들여쓰기할 때 사용되는 공백 수입니다.
`-W`, `--column-width <width>`	최대 열 너비	-1	지정된 너비를 초과하는 경우 줄을 여러 줄로 나눕니다. 줄 바꿈을 비활성화하려면 -1을 사용합니다. (기본값).
`-n`, `--normalize`	NormalizeOrder	disabled/false	QML 코딩 가이드라인에 따라 객체의 속성을 재정렬합니다. 명령줄 호출에서 플래그를 전달하여 이 동작을 활성화할 수 있습니다. 설정 파일에서는 관련 변수를 "true"로 설정하여 동작을 활성화할 수 있습니다.
`-l`, `--newline <newline>`	NewlineType	네이티브	사용할 새 줄 형식을 재정의합니다 (`native`, `macos`, `unix`, `windows`).
`-S`, `--sort-imports`	SortImports	disabled/false	가져오기를 알파벳순으로 정렬합니다(경고: 주어진 이름이 여러 모듈의 유형을 식별하는 경우 의미가 변경될 수 있습니다!). 명령줄 호출에서 플래그를 전달하여 이 동작을 활성화할 수 있습니다. 설정 파일에서는 관련 변수를 "true"로 설정하여 동작을 활성화할 수 있습니다.
`--objects-spacing`	ObjectsSpacing	비활성화/거짓	객체 사이의 공백을 보장합니다( `normalize` 에서만 작동). 명령줄 호출에서 플래그를 전달하여 동작을 활성화할 수 있습니다. 설정 파일에서는 관련 변수를 "true"로 설정하여 동작을 활성화할 수 있습니다.
`--functions-spacing`	FunctionsSpacing	비활성화/거짓	함수 사이에 공백이 있는지 확인합니다( `normalize` 에서만 작동). 명령줄 호출에서는 플래그를 전달하여 동작을 활성화할 수 있습니다. 설정 파일에서는 관련 변수를 "true"로 설정하여 동작을 활성화할 수 있습니다.
`--group-attributes-together`	GroupAttributesTogether	disabled/false	QML 코딩 가이드라인에 따라 객체의 속성을 재정렬하고 그룹화합니다. `--normalize` 을 의미합니다. 명령줄 호출에서 플래그를 전달하여 동작을 활성화할 수 있습니다. 설정 파일에서는 관련 변수를 "true"로 설정하여 동작을 활성화할 수 있습니다.
`--single-line-empty-objects`	SingleLineEmptyObjects	비활성화/거짓	빈 객체를 한 줄에 씁니다( `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 가 활성화된 경우 또는 원본 문서를 재정렬하는 옵션이 사용된 경우 지시어는 무시됩니다. 이러한 경우에는 항상 서식이 적용됩니다.

QMLTC QMLTYPE등록자

© 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.