QML Language Server

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

目前，它能让你的编辑器

• 自动完成代码
• 显示 qmllint 警告
• 导航到 QML 文件中的定义
• 查找 JavaScript 变量和 QML 对象的用法
• 重命名 JavaScript 变量和 QML 对象
• 格式化 QML 文件
• 从 Qt 文档获取帮助

支持的功能

检查

QML Language Server 可自动检查打开的 QML 文件，并在编辑器中直接显示警告或错误。有关检查过程的更多信息，请参阅qmllint，有关如何修复警告和错误，请参阅QML Lint Warning and Errors。

格式化

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 Quick 文档。要使用此功能，您的 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 环境变量

你也可以通过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 会尝试触发 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_NO_CMAKE_CALLSCMake 变量（如果启用了QT_QML_GENERATE_QMLLS_INI）。

要控制 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 文件上建议自动完成。
• 导航到 C++ 中定义的对象的定义。
• 自动完成上下文属性

QML Language Server 可能会对项目发出错误警告

• 自动补全上下文属性可能会在使用 QMake 或命令式类型注册的项目中发出错误的正向警告--请参阅将未内置的QML 模块移植到 CMake-。
• QML Language Server 使用联编信息来查找 QML 模块。
• 在 QML 模块不遵循Modernizing QML Modules中的准则的情况下