QML Language Server

QML Language Server 是 Qt 随附的一款工具，可帮助您在喜欢的（支持 LSP 的）编辑器中编写代码。有关更多信息，请参阅语言服务器协议。

目前，它可使您的编辑器实现以下功能：

• 为您的代码提供自动补全功能
• 显示 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 可以重命名 JavaScript 变量和函数，以及 QML 对象的属性、方法和 ID，只要它们是在 QML 文件中定义的。

提供自动完成建议

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 客户端直接下载该二进制文件，可以通过https://github.com/TheQtCompanyRnD/qmlls-workflow/releases或https://qtccache.qt.io/QMLLS/LatestRelease 从 GitHub 下载独立版本。

设置构建目录

QML Language Server 需要知道项目构建文件夹的位置。您可以通过以下方式指定构建文件夹。

AddBuildDirs LSP 扩展

若要通过 LSP 扩展传递构建目录，请向QML Language Server 发送通知，调用$/addBuildDirs 方法。$/addBuildDirs 接受一个参数，格式如下：

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 环境变量

QML Language Server您还可以通过QMLLS_BUILD_DIRS 环境变量传递构建目录。如果您在同一个 中使用多个工作区，则该构建目录将应用于所有工作区。来自--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值，或让CMake通过QT_QML_GENERATE_QMLLS_INI生成.qmlls.ini文件。

已知限制

尽管QML Language Server 涵盖了许多常见的QML功能，但它仍处于开发阶段，部分功能尚未得到支持：

• 针对无效 QML 文件提供自动补全建议。
• 对上下文属性的自动补全

QML Language Server 在

• ——参见《将 QML 模块移植到 CMake》
• （即未构建的项目）——QML Language Server 会利用构建信息来查找QML模块
• 其中QML模块未遵循《现代化QML模块》中的指南