En esta página

qmlformat

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

Uso:
qmlformat [opciones] argumentos

Opciones y ajustes

Puedes configurar qmlformat mediante opciones de línea de comandos. Hay dos grupos de opciones: las que están directamente relacionadas con el formato y las que controlan el comportamiento de la herramienta.

Las siguientes opciones solo afectan al comportamiento de la herramienta:

Opción de línea de comandosDescripción
-h, --helpMuestra la ayuda sobre las opciones de la línea de comandos.
--help-allMuestra la ayuda, incluidas las opciones genéricas de Qt.
-v, --versionMuestra información sobre la versión.
-V, --verboseModo detallado. Muestra información más detallada.
--write-defaultsGuarda la configuración predeterminada en .qmlformat.ini y sale.
--output-optionsMuestra todas las opciones disponibles, sus valores por defecto y una sugerencia sobre los valores o tipos.
--ignore-settingsIgnora todos los archivos de configuración y solo tiene en cuenta las opciones de la línea de comandos.
-i, --inplaceEdita el archivo in situ en lugar de enviar la salida a stdout.
-f, --forceContinúa incluso si se produce un error.
-F, --files <file>Formatear todos los archivos que aparecen en «file» directamente en el propio archivo.

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

En el caso de las opciones booleanas, pasa el indicador en la línea de comandos o establece la variable en « true » en el archivo de configuración para habilitar el comportamiento.

Opción de la línea de comandosNombre de la configuraciónValor por defectoDescripción
-t, --tabsUseTabsfalseUtilizar tabulaciones en lugar de espacios.
-w, --indent-width <width>Ancho de sangría4Número de espacios que se utilizan para sangrar.
-W, --column-width <width>AnchoMáx.DeColumna-1Divide la línea en varias líneas si supera la anchura especificada. Utiliza -1 para desactivar el ajuste de línea (por defecto).
-n, --normalizeNormalizeOrderfalseReordena y clasifica los atributos de los objetos según las directrices de codificación de QML. Incompatible con ` --group-attributes-together`.
-l, --newline <newline>NewlineTypenativoSobrescribe el formato de nueva línea que se va a utilizar (native, macos, unix, windows).
-S, --sort-importsSortImportsfalseOrdena las importaciones alfabéticamente (esto podría alterar la semántica si un nombre determinado identifica tipos en varios módulos).
--objects-spacingEspaciado entre objetosfalseAsegura que haya espacios entre los objetos (solo funciona con normalize o group-attributes-together).
--functions-spacingEspaciado entre funcionesfalseGarantiza que haya espacios entre las funciones (solo funciona con normalize o group-attributes-together).
--group-attributes-togetherAtributos de grupo juntosfalseReordena, pero no clasifica, los atributos de los objetos según las directrices de codificación de QML. Incompatible con --normalize.
--single-line-empty-objectsSingleLineEmptyObjectsfalseEscribe los objetos vacíos en una sola línea (solo funciona con « normalize » o « group-attributes-together »).
--semicolon-ruleSemicolonRulesiemprePersonaliza la inserción de puntos y comas al final de las sentencias de JS (always, essential). Consulta la regla del punto y coma para obtener más detalles.

Argumentos

Argumentos:
nombres de archivo

Uso

qmlformat es flexible y se puede configurar según tus necesidades. qmlformat debe implementarse en un entorno aislado, un contenedor u otro entorno seguro cuando se ejecute con código no fiable, por ejemplo, al dar formato a archivos QML durante las pruebas en un CI público.

Resultado

qmlformat escribe la versión formateada del archivo en stdout. Para que el archivo se actualice in situ, especifica el indicador « -i ».

Agrupación de propiedades, funciones y señales

Con el indicador « -n » o « --normalize », qmlformat agrupa y ordena todas las propiedades, funciones y señales por nombre, en lugar de mantener el orden existente.

Por ejemplo:

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 {}
    }
}

se formatea como:

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() {
    }
}

Para agrupar los atributos sin ordenarlos por nombre, utiliza en su lugar --group-attributes-together.

Esto da como resultado el siguiente fragmento de código:

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() {
    }
}

Esta opción tiene prioridad sobre --normalize.

Archivo de configuración

Puedes configurar qmlformat incluyendo un archivo de configuración (.qmlformat.ini) en el código fuente de tu proyecto o en los directorios superiores de la carpeta de código fuente de tu proyecto. Puedes obtener un archivo de configuración por defecto pasando el indicador --write-defaults. Esto genera el archivo .qmlformat.ini en el directorio de trabajo actual.

Advertencia: --write-defaults sobrescribe todos los ajustes y comentarios existentes.

Formateo de una lista de archivos

Aunque se puede pasar como argumentos una lista de archivos que se van a formatear, qmlformat ofrece la opción -F para formatear un conjunto de archivos almacenados en un fichero. En este caso, el formateo se realiza in situ.

// FileList.txt
main.qml
mycomponent.qml

Para utilizar esta lista:

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 válida pero cuyo contenido es un documento QML no válido, qmlformat informa de un error para esa entrada y continúa formateando las entradas válidas restantes en su lugar.

Advertencia: Si se especifica la opción ` -F `, `qmlformat` ignora los argumentos posicionales.

Regla del punto y coma

La opción --semicolon-rule te permite personalizar la inserción de puntos y comas al final de las sentencias JS.

Se aceptan los siguientes valores:

  • always - Añadir siempre puntos y comas (por defecto).
  • essential - Eliminar los puntos y comas, salvo que su omisión provoque problemas.

Desactivar el formato con comentarios

Puedes 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 haberlo desactivado.

Esto te permite conservar el código ajustado manualmente o las estructuras complejas sin que qmlformat modifique su diseño. El formateo permanece desactivado hasta el siguiente comentario « // qmlformat on », o hasta el final del archivo si no se encuentra ningún comando de reactivación.

Ten en cuenta lo siguiente al utilizar directivas de formato:

  • Las directivas deben estar en una línea separada.
  • No se admiten directivas anidadas. Solo se tienen en cuenta el primer « // qmlformat off » y el siguiente « // qmlformat on ». Se ignoran las directivas adicionales que se encuentren dentro de una región desactivada.
  • Las directivas se ignoran en el modo de formato normalizado, cuando está activada la opción « sortImports » o cuando se utiliza cualquier opción que reordene el documento original. En estos casos, siempre se aplica el formato.

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