QML Language Server

QML Language Server est un outil fourni avec Qt qui vous aide à écrire du code dans votre éditeur préféré (prenant en charge le protocole LSP). Consultez la page « Language Server Protocol » pour plus d’informations.

Actuellement, il permet à votre éditeur de :

• compléter automatiquement votre code
• d'afficher les avertissements de qmllint
• Accéder aux définitions dans les fichiers QML
• Rechercher les occurrences des variables JavaScript et des objets QML
• Renommer des variables JavaScript et des objets QML
• Mettre en forme les fichiers QML
• Consulter la documentation Qt

Fonctionnalités prises en charge

Analyse syntaxique

QML Language Server peut analyser automatiquement les fichiers QML ouverts et afficher les avertissements ou les erreurs directement dans l'éditeur. Consultez qmllint pour plus d'informations sur le processus d'analyse, et Avertissements et erreurs de QML Lint pour savoir comment corriger les avertissements et les erreurs.

Mise en forme

QML Language Server permet de formater des fichiers entiers depuis l’éditeur. Consultez qmlformat pour plus d’informations sur le processus de formatage.

Recherche de définitions

QML Language Server permet de rechercher les définitions des variables JavaScript, des fonctions, des identifiants d’objets QML et des propriétés QML à partir de leurs utilisations.

QML Language Server peut également trouver la définition des types utilisés dans les annotations de type pour les fonctions JavaScript, les propriétés d’objets QML et l’instanciation d’objets QML.

Recherche d'utilisations

QML Language Server peut rechercher les utilisations des variables JavaScript, des propriétés d’objets QML, des fonctions JavaScript, des méthodes d’objets QML et des identifiants d’objets QML.

Renommer

QML Language Server Vous pouvez renommer des variables et des fonctions JavaScript, ainsi que des propriétés, des méthodes et des identifiants d’objets QML, à condition qu’ils soient définis dans un fichier QML.

Suggestions d’autocomplétion

QML Language Server fournit des suggestions de complétion automatique pour les variables, expressions et instructions JavaScript, ainsi que pour les propriétés, méthodes et identifiants d'objets QML.

Suivi des modifications dans les fichiers C++

QML Language Server permet de suivre les modifications apportées aux fichiers C++ définissant des types QML. Il recompile automatiquement les modules QML CMake afin de fournir des avertissements et des suggestions de complétion précis et à jour pour les types QML définis en C++.

Vous pouvez désactiver cette fonctionnalité.

Astuces de documentation

QML Language Server comprend une fonctionnalité de conseils de documentation qui permet aux programmeurs d’accéder rapidement à la documentation de Qt en survolant un mot-clé. Pour utiliser cette fonctionnalité, votre kit Qt doit contenir la documentation Qt et votre projet doit être compilé avec la variable QT_QML_GENERATE_QMLLS_INI.

Configuration d’ QML Language Server dans votre éditeur

Cette section décrit comment développer le client « QML Language Server » ou comment utiliser votre propre client « QML Language Server ».

Vous trouverez le binaire d’ QML Language Server sous <Qt installation folder>/bin/qmlls dans les installations de Qt XML réalisées avec Qt Online Installer. Si vous souhaitez que votre client QML Language Server télécharge directement le fichier binaire, vous pouvez télécharger la version autonome depuis GitHub via https://github.com/TheQtCompanyRnD/qmlls-workflow/releases ou https://qtccache.qt.io/QMLLS/LatestRelease.

Configuration du répertoire de compilation

QML Language Server doit connaître l'emplacement du dossier de compilation du projet. Vous pouvez indiquer le dossier de compilation de différentes manières.

Extension LSP AddBuildDirs

Pour indiquer les répertoires de compilation via l’extension LSP, envoyez une notification à QML Language Server pour la méthode $/addBuildDirs. $/addBuildDirs accepte un paramètre sous la forme suivante :

interface AddBuildDirsParams {
    buildDirsToSet: UriToBuildDirs[];
}

où ` UriToBuildDirs ` contient une URI d’espace de travail et une liste de répertoires de compilation. L’URI d’espace de travail doit désigner un espace de travail signalé à ` QML Language Server ` via ` workspaceFolders ` ou `didChangeWorkspaceFolders`. Les répertoires de compilation sont des chemins d’accès aux fichiers, et non des URI.

interface UriToBuildDirs {
    baseUri: URI;
    buildDirs: string[];
}

Option de ligne de commande –build-dir

Si vous n’avez pas besoin de prendre en charge plusieurs espaces de travail, vous pouvez passer les répertoires de compilation via l’option de ligne de commande --build-dir. Dans ce cas, votre éditeur doit appeler qmlls comme suit :

<path/to/qmlls> ... --build-dir <path/to/build-directory> ...

Le répertoire de compilation s’appliquera à tous les espaces de travail si vous utilisez plusieurs espaces de travail dans le même fichier ` QML Language Server`. Les valeurs définies dans ` addBuildDirsMethod ` ont priorité sur l’option de ligne de commande.

Variable d’environnement QMLLS_BUILD_DIRS

Vous pouvez également passer les répertoires de compilation via la variable d’environnement QMLLS_BUILD_DIRS. Le répertoire de compilation s’appliquera à tous les espaces de travail si vous utilisez plusieurs espaces de travail dans la même QML Language Server. Les valeurs de --build-dir ont priorité sur la variable d’environnement.

.qmlls.ini Fichier de configuration

Si vous ne parvenez pas à passer les répertoires de compilation à l’aide de l’une des options précédentes, vous pouvez essayer de les transmettre à QML Language Server via un fichier de configuration. Voir également Fichier de configuration. Les valeurs du fichier de configuration ont une priorité inférieure à celles de --build-dir, QMLLS_BUILD_DIRS et addBuildDirsMethod.

Configuration des compilations CMake automatiques

QML Language Server tentera de déclencher une recompilation CMake lorsqu’il détectera que le code source d’un type QML défini en C++ a été modifié.

Pour désactiver cette fonctionnalité, procédez de l’une des manières suivantes :

• L’option de ligne de commande « --no-cmake-calls ». Dans ce cas, votre éditeur doit appeler qmlls comme suit :

  <path/to/qmlls> --build-dir <path/to/build-directory> --no-cmake-calls

• La variable d’environnement ` QMLLS_NO_CMAKE_CALLS `.
• Le fichier de paramètres « .qmlls.ini » ; voir Fichier de configuration.
• La variable CMake ` QT_QML_GENERATE_QMLLS_INI_NO_CMAKE_CALLS ` si ` QT_QML_GENERATE_QMLLS_INI ` est activée.

Pour contrôler le nombre de tâches utilisées par CMake, utilisez

• l'option de ligne de commande ` --cmake-jobs `. Dans ce cas, votre éditeur doit appeler ` qmlls ` comme suit :

  <path/to/qmlls> --build-dir <path/to/build-directory> --cmake-jobs <jobs>

• La variable d'environnement ` QMLLS_CMAKE_JOBS `.
• Le fichier de paramètres « .qmlls.ini » (voir Fichier de configuration).

Les valeurs acceptées sont des nombres entiers supérieurs à 0 et max pour utiliser tous les cœurs disponibles.

Modification du nombre maximal de fichiers à rechercher

QML Language Server permet de limiter le nombre de fichiers à parcourir lors de la recherche d’en-têtes dans les dossiers sources, par exemple lorsque l’on accède à la définition d’un composant QML défini dans un en-tête C++.

Pour définir le nombre maximal de fichiers à rechercher, entrez une valeur numérique dans la variable d’environnement QMLLS_MAX_FILES_TO_SEARCH. 0 désactive la fonctionnalité de recherche de fichiers ; 20 000 est la valeur par défaut.

Fichier de configuration

QML Language Server peut être configuré via un fichier de configuration .qmlls.ini. Ce fichier doit se trouver dans le répertoire source racine du projet. Il doit s’agir d’un fichier texte au format ini.

Le fichier de configuration peut contenir les entrées suivantes :

// .qmlls.ini
[General]
no-cmake-calls=<true-or-false>
CMakeJobs=<some integer value>

buildDir=<path/to/build-directory> # not required in Qt 6.10 and later
docDir=<path/to/qt-documentation>  # not required in Qt 6.10 and later
importPaths=<path/to/imports>      # not required in Qt 6.10 and later

Pour utiliser le fichier de configuration afin de désactiver la fonctionnalité de reconstruction automatique de CMake, définissez no-cmake-calls sur true.

Pour contrôler le nombre de tâches utilisées par les recompilations automatiques de CMake, définissez la valeur CMakeJobs.

Pour prendre en charge les clients qui ne peuvent pas transmettre le répertoire de compilation à ` QML Language Server`, comme décrit dans la section « Configuration du répertoire de compilation », définissez la valeur `buildDir` ou laissez CMake générer le fichier `.qmlls.ini` via `QT_QML_GENERATE_QMLLS_INI`.

Limitations connues

Bien qu’il couvre de nombreuses fonctionnalités QML courantes, QML Language Server est encore en cours de développement et certaines fonctionnalités ne sont pas encore prises en charge :

• Proposition de complétions automatiques pour les fichiers QML non valides.
• La suggestion de propriétés de contexte

QML Language Server peut générer des avertissements erronés sur les projets

• utilisant QMake ou l’enregistrement de type impératif — voir Porter des modules QML vers CMake
• qui n’ont pas été compilés —QML Language Server utilise les informations de compilation pour identifier les modules QML
• lorsque les modules QML ne respectent pas les directives décrites dans Modernisation des modules QML