QML Language Server

QML Language Server は、Qtに同梱されているツールで、お好みの（LSP対応の）エディタでコードを記述するのを支援します。詳細については、Language Server Protocolを参照してください。

現在、このツールによりエディタで以下の機能が利用可能になります：

• コードの自動補完
• qmllintの警告を表示する
• QMLファイル内の定義への移動
• JavaScript変数およびQMLオブジェクトの使用箇所の検索
• JavaScript変数およびQMLオブジェクトの名前変更
• QML ファイルの書式設定
• Qt ドキュメントからヘルプを表示する

サポートされている機能

リンティング

QML Language Server は、開いている QML ファイルを自動的にリンティングし、警告やエラーをエディタ上に直接表示することができます。リンティングのプロセスに関する詳細については「qmllint」を、警告やエラーの修正方法については「QML リンティングの警告とエラー」を参照してください。

フォーマット

QML Language Server は、エディタ内からファイル全体の書式設定を行うことができます。書式設定のプロセスに関する詳細については、qmlformat を参照してください。

定義の検索

QML Language Server は、JavaScript変数、関数、QMLオブジェクトID、およびQMLプロパティの使用箇所から、それらの定義を検索できます。

QML Language Server また、JavaScript 関数、QML オブジェクトのプロパティ、および QML オブジェクトのインスタンス化における型注釈で使用されている型の定義も検索できます。

使用箇所の検索

QML Language Server JavaScript変数、QMLオブジェクトのプロパティ、JavaScript関数、QMLオブジェクトのメソッド、およびQMLオブジェクトIDの使用箇所を検索できます。

名前の変更

QML Language Server QML ファイルで定義されている限り、JavaScript の変数や関数、および QML オブジェクトのプロパティ、メソッド、ID の名前を変更できます。

オートコンプリート項目の提案

QML Language Server JavaScript の変数、式、文、および QML オブジェクトのプロパティ、メソッド、ID に対するオートコンプリートの候補を提供します。

C++ ファイルの変更の追跡

QML Language Server QML 型を定義する C++ ファイルの変更を追跡できます。CMake QML モジュールを自動的に再構築し、C++ で定義された QML 型に対して正確かつ最新の警告や補完候補を提供します。

この機能は無効にすることもできます。

ドキュメントヒント

QML Language Server には、キーワードにカーソルを合わせることで、プログラマが Qt のドキュメントにすばやくアクセスできるドキュメントヒント機能が含まれています。この機能を使用するには、Qt キットに Qt ドキュメントが含まれている必要があり、プロジェクトはQT_QML_GENERATE_QMLLS_INI変数を指定してビルドされている必要があります。

エディタでのQML Language Server の設定

このセクションでは、QML Language Server クライアントの開発方法、または独自のQML Language Server クライアントの使用方法について説明します。

Qt Online Installer を使用して構築されたQtのインストール環境では、<Qt installation folder>/bin/qmlls ディレクトリの下にQML Language Server のバイナリがあります。QML Language Server クライアントでバイナリを直接ダウンロードしたい場合は、GitHubからhttps://github.com/TheQtCompanyRnD/qmlls-workflow/releasesまたはhttps://qtccache.qt.io/QMLLS/LatestRelease経由でスタンドアロン版をダウンロードできます。

ビルドディレクトリの設定

QML Language Server には、プロジェクトのビルドフォルダの場所を指定する必要があります。ビルドフォルダは以下の方法で指定できます。

AddBuildDirs LSP 拡張機能

LSP拡張機能経由でビルドディレクトリを指定するには、$/addBuildDirs メソッドに対してQML Language Server に通知を送信します。$/addBuildDirs は、次のような形式のパラメータを1つ受け付けます。

interface AddBuildDirsParams {
    buildDirsToSet: UriToBuildDirs[];
}

ここで、UriToBuildDirs にはワークスペース URI とビルドディレクトリのリストが含まれます。ワークスペース URI は、workspaceFoldersまたはdidChangeWorkspaceFolders を通じてQML Language Server に通知されたワークスペースを指定する必要があります。ビルドディレクトリは URI ではなく、ファイルパスです。

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

–build-dir コマンドラインオプション

複数のワークスペースをサポートする必要がない場合は、--build-dir コマンドラインオプションを介してビルドディレクトリを渡すことができます。この場合、エディタは次のようにqmlls を呼び出す必要があります:

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

同じQML Language Server で複数のワークスペースを使用している場合、そのビルドディレクトリはすべてのワークスペースに適用されます。addBuildDirsMethod で指定された値は、コマンドラインオプションよりも優先されます。

QMLLS_BUILD_DIRS 環境変数

QMLLS_BUILD_DIRS の環境変数を介してビルドディレクトリを指定することもできます。同じQML Language Server 内で複数のワークスペースを使用している場合、ビルドディレクトリはすべてのワークスペースに適用されます。--build-dir の値は、環境変数よりも優先されます。

.qmlls.ini 設定ファイル

前述のいずれのオプションでもビルドディレクトリを指定できない場合は、設定ファイルを介してQML Language Server にビルドディレクトリを指定してみてください。「設定ファイル」も参照してください。設定ファイルの値は、--build-dir 、QMLLS_BUILD_DIRS 、およびaddBuildDirsMethod よりも優先度が低くなります。

CMakeの自動ビルドの設定

QML Language Server は、C++で定義されたQML型のソースコードが変更されたことを検知すると、CMakeの再ビルドをトリガーしようとします。

この機能を無効にするには、次の方法を使用します。

• --no-cmake-calls というコマンドラインオプション。この場合、エディタは次のようにqmlls を呼び出す必要があります：

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

• QMLLS_NO_CMAKE_CALLS 環境変数。
• .qmlls.ini 設定ファイル（「設定ファイル」を参照）。
• QT_QML_GENERATE_QMLLS_INI が有効になっている場合、CMake変数 `QT_QML_GENERATE_QMLLS_INI_NO_CMAKE_CALLS`。

CMake が使用するジョブの数を制御するには、以下を使用します。

• --cmake-jobs コマンドラインオプションを使用します。この場合、エディタは次のように `qmlls ` を呼び出す必要があります:

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

• QMLLS_CMAKE_JOBS 環境変数。
• .qmlls.ini 設定ファイル（「設定ファイル」を参照）。

有効な値は、0より大きい整数、および利用可能なすべてのコアを使用するための `max ` です。

検索対象となるファイルの最大数を変更する

QML Language Server は、ソースフォルダ内でヘッダーを検索する際（たとえば、C++ ヘッダーで定義された QML コンポーネントの定義に移動する場合など）に、検索対象となるファイル数の上限を指定します。

検索するファイルの最大数を設定するには、QMLLS_MAX_FILES_TO_SEARCH 環境変数に数値を指定します。0 を指定するとファイル検索機能が無効になり、20000 がデフォルト値です。

設定ファイル

QML Language Server 設定ファイル `.qmlls.ini` を使用して設定を行うことができます。このファイルは、プロジェクトのソースディレクトリのルートに配置する必要があります。ini 形式のテキストファイルである必要があります。

設定ファイルには、以下のエントリを記述できます。

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

設定ファイルを使用して CMake の自動再ビルド機能を無効にするには、no-cmake-calls をtrue に設定します。

CMakeの自動再ビルドで使用されるジョブの数を制御するには、CMakeJobsの値を設定してください。

「ビルドディレクトリの設定」で説明されているように、QML Language Server にビルドディレクトリを渡せないクライアントをサポートするには、buildDirの値を設定するか、QT_QML_GENERATE_QMLLS_INIを使用してCMakeに.qmlls.iniを生成させます。

既知の制限事項

QML Language Server は多くの一般的なQML機能を網羅していますが、まだ開発中であり、一部の機能は未対応です:

• 無効なQMLファイルに対するオートコンプリートの提案。
• コンテキストプロパティの自動補完

QML Language Server QMakeや命令型登録を使用しているプロジェクトでは

• QMake を使用しているプロジェクトや、命令型登録を行っているプロジェクトでは、誤った警告が発生する可能性があります。詳細は「QML モジュールを CMake に移植する」を参照してください
• ビルドされていないものについては、「QMLモジュールのCMakeへの移植」を参照してください。QML Language Server はビルド情報を使用して、
• QMLモジュールが「QMLモジュールの近代化」のガイドラインに従っていない場合