qmlformat

qmlformat es una herramienta que formatea automáticamente archivos QML de acuerdo con las convenciones de codificación QML.

Utilización:
qmlformat[opciones] argumentos

Opciones y configuración

qmlformat puede configurarse mediante opciones en la línea de comandos. Existen dos grupos de opciones: Las que están directamente relacionadas con el formateo, y las que controlan el comportamiento de la herramienta.

Las siguientes opciones sólo afectan al comportamiento de la herramienta:

Línea de comandos Opción	Descripción
`-h`, `--help`	Muestra la ayuda sobre las opciones de la línea de comandos.
`--help-all`	Muestra ayuda, incluyendo opciones genéricas de Qt.
`-v`, `--version`	Muestra información sobre la versión.
`-V`, `--verbose`	Modo detallado. Muestra información más detallada.
`--write-defaults`	Escribe la configuración por defecto en .qmlformat.ini y sale (Advertencia: ¡Esto sobrescribirá cualquier configuración y comentarios existentes!)
`--output-options`		Imprime todas las opciones disponibles, su valor por defecto y una sugerencia de valores o tipos
`--ignore-settings`	Ignora todos los archivos de configuración y sólo tiene en cuenta las opciones de la línea de comandos
`-i`, `--inplace`	Edita el archivo en su lugar en lugar de enviarlo a stdout.
`-f`, `--force`	Continúa aunque se produzca un error.
`-F`, `--files <file>`	Formatea todos los archivos listados en el archivo, en su lugar

El siguiente grupo de opciones controla cómo deben formatearse los archivos, y también puede controlarse adicionalmente a través de un archivo de configuración.:

Opción de línea de comandos	Configuración Nombre	Estado/Valor por defecto	Descripción
`-t`, `--tabs`	UseTabs	desactivado/falso	Utiliza tabuladores en lugar de espacios. En una invocación de línea de comandos, el comportamiento puede activarse pasando la bandera. En un archivo de configuración, el comportamiento puede activarse estableciendo la variable correspondiente en "true".
`-w`, `--indent-width <width>`	Anchura de sangría	4	Cuántos espacios se utilizan al sangrar.
`-W`, `--column-width <width>`	MaxColumnWidth	-1	Rompe la línea en múltiples líneas si excede el ancho especificado. Utilice -1 para desactivar el ajuste de línea. (por defecto).
`-n`, `--normalize`	NormalizarOrden	disabled/false	Reordena los atributos de los objetos de acuerdo con las Directrices de Codificación QML. En una invocación de línea de comandos, el comportamiento puede habilitarse pasando la bandera. En un archivo de configuración, el comportamiento puede activarse estableciendo la variable correspondiente en "true".
`-l`, `--newline <newline>`	NewlineType	nativo	Anula el formato de nueva línea a utilizar (`native`, `macos`, `unix`, `windows`).
`-S`, `--sort-imports`	OrdenarImportar	disabled/false	Ordena las importaciones alfabéticamente (Advertencia: esto puede cambiar la semántica si un nombre dado identifica tipos en múltiples módulos). En una invocación de línea de comandos, el comportamiento puede activarse pasando la bandera. En un archivo de configuración, el comportamiento puede activarse estableciendo la variable relevante a "true".
`--objects-spacing`	Espaciado entre objetos	disabled/false	Asegura espacios entre objetos (sólo funciona con `normalize`). En una invocación de línea de comandos, el comportamiento puede activarse pasando el indicador. En un archivo de configuración, el comportamiento puede activarse estableciendo la variable correspondiente en "true".
`--functions-spacing`	FuncionesEspaciado	disabled/false	Asegura espacios entre funciones (sólo funciona con `normalize`). En una invocación de línea de comandos, el comportamiento puede activarse pasando el indicador. En un archivo de configuración, el comportamiento puede activarse estableciendo la variable correspondiente en "true".
`--group-attributes-together`	AgruparAtributos	disabled/false	Reordena y agrupa los atributos de los objetos según las directrices de codificación QML. Implica `--normalize`. En una invocación de línea de comandos, el comportamiento puede activarse pasando el indicador. En un archivo de configuración, el comportamiento puede activarse estableciendo la variable correspondiente en "true".
`--single-line-empty-objects`	SingleLineEmptyObjects	disabled/false	Escribe objetos vacíos en una sola línea (sólo funciona con `normalize`). En una invocación de línea de comandos, el comportamiento puede activarse pasando el indicador. En un archivo de configuración, el comportamiento puede activarse estableciendo la variable correspondiente en "true".
`--semicolon-rule`	Regla del punto y coma	siempre	Personaliza la adición de punto y coma al final de las sentencias JS (`always`, `essential`). Nota: Véase Semicolon Rule para más detalles.

Argumentos

Argumentos:
nombres de archivo

Detalles

qmlformat es flexible y puede configurarse según sus necesidades.

Salida

qmlformat escribe la versión formateada del archivo en stdout. Si desea que el archivo se actualice in situ, especifique la opción -i.

Agrupación de propiedades, funciones y señales

Con -n o --normalize, qmlformat agrupa todas las propiedades, funciones y señales, en lugar de mantener el orden especificado.

Archivo de configuración

Puede configurar qmlformat incluyendo un archivo de configuración .qmlformat.ini en el código fuente del proyecto o en los directorios principales de la carpeta de código fuente del proyecto. Se puede obtener un archivo de configuración por defecto pasando la bandera --write-defaults. Esto genera el archivo .qmlformat.ini en el directorio de trabajo actual.

Advertencia: --write-defaults sobrescribirá cualquier configuración y comentarios existentes.

Formatear una lista de archivos

Aunque puede pasar una lista de archivos a formatear como argumentos, qmlformat proporciona la opción -F para formatear un conjunto de archivos almacenados en un archivo. En este caso, el formateo se realizará in situ.

// FileList.txt
main.qml
mycomponent.qml

Entonces, utilícelo como

qmlformat -F FileList.txt

Nota: Si el archivo contiene una entrada no válida, por ejemplo, una ruta de archivo que no existe o una ruta de archivo válida pero el contenido es un documento qml no válido, entonces qmlformat dará error para esa entrada en particular. No obstante, dará formato a las entradas válidas del archivo.

Advertencia: Si proporciona la opción -F, qmlformat ignorará los argumentos posicionales.

Regla del punto y coma

La opción --semicolon-rule permite personalizar la adición de punto y coma al final de las sentencias JS. Se aceptan los siguientes valores:

always - Añadir siempre punto y coma (por defecto).
essential - Quitar puntos y comas a menos que omitirlos cause problemas.

Desactivar el formato con comentarios

Puede desactivar temporalmente qmlformat mediante comentarios especiales.

// qmlformat off desactiva el formato a partir de esa línea
// qmlformat on activa el formato después de desactivarlo

Esto le permite conservar el código ajustado a mano o las estructuras complejas sin que qmlformat cambie su disposición. El formato permanece desactivado hasta el siguiente comentario de // qmlformat on, o hasta el final del archivo si no se encuentra ninguna opción para volver a activarlo.

Nota: Las directivas deben estar en su propia línea.

Nota : No se admiten directivas anidadas. Sólo se tienen en cuenta la primera // qmlformat off y la siguiente // qmlformat on. Cualquier directiva adicional dentro de una región deshabilitada se ignora.

Nota: Las directivas se ignoran en modo de formato normalizado, cuando sortImports está activado o cuando se utiliza cualquier opción que reordene el documento original. En estos casos, siempre se aplica el formato.

qmltc qmltyperegistrar

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