QML Language Server

QML Language Server est un outil fourni avec Qt Help qui vous aide à écrire du code dans votre éditeur favori (supportant le LSP). Voir Language Server Protocol pour plus d'informations.

Actuellement, il permet à votre éditeur de

• Autocompléter votre code
• Afficher les avertissements qmllint
• Naviguer vers les définitions dans les fichiers QML
• Trouver des utilisations de variables JavaScript et d'objets QML
• Renommer les variables JavaScript et les objets QML
• Formater les fichiers QML
• Obtenir de l'aide auprès de la documentation de Qt Help

Fonctionnalités prises en charge

Analyse de la qualité

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

Formatage

QML Language Server peut formater des fichiers entiers depuis l'éditeur. Voir qmlformat pour plus d'informations sur le processus de formatage.

Recherche de définitions

QML Language Server permet de trouver les définitions des variables JavaScript, des fonctions, des identifiants d'objets QML et des propriétés QML à partir de leur utilisation.

QML Language Server Vous pouvez é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'usages

QML Language Server permet de trouver 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 permet de renommer les variables et fonctions JavaScript, ainsi que les propriétés, méthodes et identifiants des objets QML, pour autant qu'ils soient définis dans un fichier QML.

Suggestion d'éléments d'autocomplétion

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

Suivi des modifications dans les fichiers C

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

Vous pouvez désactiver cette fonctionnalité.

Indices de documentation

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

Configuration de 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 pouvez trouver le binaire QML Language Server sous <Qt installation folder>/bin/qmlls dans les installations de Qt faites avec Qt Online Installer. Si vous voulez que votre client QML Language Server télécharge le binaire directement, vous pouvez télécharger la version autonome sur github via https://github.com/TheQtCompanyRnD/qmlls-workflow/releases ou https://qtccache.qt.io/QMLLS/LatestRelease.

Configuration du répertoire de construction

QML Language Server a besoin de connaître l'emplacement du dossier de construction du projet. Vous pouvez transmettre le dossier de construction de la manière suivante.

AddBuildDirs Extension LSP

Pour transmettre des répertoires de construction via l'extension LSP, envoyez une notification à QML Language Server pour la méthode $/addBuildDirs. $/addBuildDirs accepte un paramètre de la forme :

interface AddBuildDirsParams {
    buildDirsToSet: UriToBuildDirs[];
}

où UriToBuildDirs contient un URI d'espace de travail et une liste de répertoires de construction. L'URI de l'espace de travail doit désigner un espace de travail annoncé à 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 transmettre les répertoires de construction via l'option de ligne de commande --build-dir. Dans ce cas, votre éditeur doit invoquer qmlls comme suit :

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

Le répertoire de construction sera appliqué à tous les espaces de travail si vous utilisez plusieurs espaces de travail dans le même QML Language Server. Les valeurs de addBuildDirsMethod ont une priorité plus élevée que l'option de ligne de commande.

Variable d'environnement QMLLS_BUILD_DIRS

Vous pouvez également transmettre les répertoires de compilation via la variable d'environnement QMLLS_BUILD_DIRS. Le répertoire de construction sera appliqué à tous les espaces de travail si vous utilisez plusieurs espaces de travail dans le même QML Language Server. Les valeurs de --build-dir ont une priorité supérieure à la variable d'environnement.

.qmlls.ini Fichier de configuration

Si vous ne pouvez pas transmettre les répertoires de compilation en utilisant l'une des options précédentes, vous pouvez essayer de transmettre les répertoires de compilation à QML Language Server par l'intermédiaire d'un fichier de configuration. Voir aussi Fichier de configuration. Les valeurs du fichier de configuration sont moins prioritaires que --build-dir, QMLLS_BUILD_DIRS, et addBuildDirsMethod.

Configuration des constructions automatiques de CMake

QML Language Server CMake essaiera de déclencher une reconstruction 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é, utilisez les moyens suivants :

• L'option de ligne de commande --no-cmake-calls. Dans ce cas, votre éditeur doit invoquer 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 configuration de .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é.

Pour contrôler le nombre de jobs utilisés par CMake, utilisez

• L'option de ligne de commande --cmake-jobs. Dans ce cas, votre éditeur doit invoquer 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 configuration .qmlls.ini, voir Fichier de configuration.

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

Modifier la quantité maximale de fichiers à rechercher

QML Language Server respecte une limite de fichiers à rechercher lors de la recherche d'en-têtes dans les dossiers source, par exemple lorsqu'il s'agit d'aller à la définition d'un composant QML défini dans un en-tête C++.

Pour définir la quantité maximale de fichiers à rechercher, écrivez une valeur numérique dans la variable d'environnement QMLLS_MAX_FILES_TO_SEARCH. 0 désactive la fonction de recherche de fichiers, 20000 est la valeur par défaut.

Fichier de configuration

QML Language Server peut être configuré à l'aide d'un fichier de configuration .qmlls.ini. Ce fichier doit se trouver dans le répertoire source racine du projet. Il s'agit 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 à true.

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

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

Limites 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 :

• Suggestion d'autocomplétions pour les fichiers QML non valides.
• Navigation vers les définitions d'objets définis en C++.
• L'autocomplétion des propriétés du contexte

QML Language Server peut émettre des avertissements faussement positifs sur les projets

• utilisant QMake ou l'enregistrement de type impératif - voir Porter dans CMake des modules QML qui n'ont pas été compilés - utilise des modules QML non compilés.
• qui n'ont pas été compilés -QML Language Server utilise les informations de compilation pour trouver les modules QML
• lorsque les modules QML ne suivent pas les directives de la section Modernisation des modules QML.