模块定义文件 qmldir

qmldir 文件有两种不同的类型：

• QML文档目录列表文件
• QML 模块定义文件

本文档仅涵盖第二种形式的qmldir 文件，该文件列出了模块下可用的QML类型、JavaScript文件和插件。有关第一种形式的qmldir 文件的更多信息，请参阅目录列表qmldir文件。

模块定义 qmldir 文件的内容

qmldir 文件是一个纯文本文件，包含以下命令：

• 模块标识符声明
• 对象类型声明
• 内部对象类型声明
• JavaScript 资源声明
• 插件声明
• 插件类名声明
• 类型描述文件声明
• 模块依赖声明
• 模块导入声明
• 设计器支持声明
• 首选路径声明

除了命令外，您还可以添加注释，即以# 开头的行。

模块标识符声明

module <ModuleIdentifier>

声明模块的模块标识符。<ModuleIdentifier> 是该模块的（点分隔 URI 表示法）标识符，必须与模块的安装路径相匹配。

模块标识符指令必须位于文件的第一行。qmldir 文件中只能存在且仅能存在一个模块标识符指令。

示例：

module ExampleModule

对象类型声明

[singleton] <TypeName> <InitialVersion> <File>

声明一个由该模块提供的QML 对象类型。

• [singleton] 可选。用于声明单例类型。
• <TypeName> 是该模块提供的类型
• <InitialVersion> 是该类型将提供的模块版本
• <File> 是定义该类型的 QML 文件的（相对）文件名

qmldir 文件中可以包含零个或多个对象类型声明。但是，在模块的任何特定版本中，每个对象类型都必须具有唯一的类型名称。

示例：

//Style.qml with custom singleton type definition
pragma Singleton
import QtQuick 2.0

QtObject {
    property int textSize: 20
    property color textColor: "green"
}

// qmldir declaring the singleton type
module CustomStyles
singleton Style 1.0 Style.qml

// singleton type in use
import QtQuick 2.0
import CustomStyles 1.0

Text {
    font.pixelSize: Style.textSize
    color: Style.textColor
    text: "Hello World"
}

内部对象类型声明

internal <TypeName> <File>

声明一种位于模块中但不应提供给模块用户的对象类型。

qmldir 文件中可以包含零个或多个内部对象类型声明。

示例：

internal MyPrivateType MyPrivateType.qml

如果模块是远程导入的（参见《远程安装的标识模块》），则此声明必不可少，因为如果某个导出类型依赖于模块内部的未导出类型，引擎也必须加载该未导出类型。

JavaScript 资源声明

<ResourceIdentifier> <InitialVersion> <File>

声明一个由模块提供的 JavaScript 文件。该资源将通过指定的标识符和指定的版本号提供。

qmldir 文件中可以包含零个或多个JavaScript资源声明。但是，在模块的任何特定版本中，每个JavaScript资源都必须具有唯一的标识符。

示例：

MyScript 1.0 MyScript.js

有关定义 JavaScript 资源以及在 QML 中导入 JavaScript 资源的更多信息，请参阅相关文档。

插件声明

[optional] plugin <Name> [<Path>]

声明由模块提供的插件。

• optional 表示该插件本身不包含任何相关代码，仅用于加载其链接的库。如果指定了该参数，且该模块的任何类型已可用（表明该库已通过其他方式加载），则 QML 不会加载该插件。
• <Name> 是插件库的名称。该名称通常与插件二进制文件的文件名不同，后者取决于具体平台。例如，库MyAppTypes 在Linux上会生成libMyAppTypes.so ，在Windows上则会生成MyAppTypes.dll 。
• <Path> （可选）指定以下任一内容：
  • 包含插件文件的目录的绝对路径，或
  • 从包含 `qmldir ` 文件的目录到包含插件文件的目录的相对路径。

默认情况下，引擎会在包含qmldir 文件的目录中搜索插件库。（可通过QQmlEngine::pluginPathList() 查询插件搜索路径，并使用QQmlEngine::addPluginPath() 进行修改。）

qmldir 文件中可以包含零个或多个 C++ 插件声明。但是，由于加载插件是一项相对耗时的操作，建议客户端最多只指定一个插件。

示例：

plugin MyPluginLibrary

插件类名声明

classname <C++ plugin class>

提供模块所使用的 C++ 插件的类名。

对于所有依赖 C++ 插件以实现附加功能的 QML 模块，此信息均为必填项。若缺少此信息，采用静态链接构建的Qt Quick 应用程序将无法解析模块导入。

类型描述文件声明

typeinfo <File>

声明该模块的类型描述文件，QML 工具（例如 Qt Creator 读取，以获取有关该模块插件所定义的类型的信息。<File> 是.qmltypes 文件的（相对）文件名。

示例：

typeinfo mymodule.qmltypes

如果没有此类文件，QML工具可能无法为插件中定义的类型提供代码补全等功能。

模块依赖声明

depends <ModuleIdentifier> <InitialVersion>

声明该模块依赖于另一个模块。

示例：

depends MyOtherModule 1.0

仅当依赖关系被隐藏时才需要此声明：例如，当某个模块的 C++ 代码被用于加载 QML（可能是条件加载）时，而该 QML 又依赖于其他模块。在这种情况下，必须使用 `depends ` 声明，才能将其他模块包含到应用程序包中。

模块导入声明

import <ModuleIdentifier> [<Version>]

声明该模块导入另一个模块。

示例：

import MyOtherModule 1.0

来自另一个模块的类型将在此模块被导入的同一类型命名空间中提供。省略版本号将导入该模块的最新可用版本。指定版本为 `auto ` 时，将导入与 QML 中 `import ` 语句中指定本模块版本相同的版本。

设计器支持声明

designersupported

如果该插件受Qt Quick Designer 支持，请设置此属性。默认情况下，该插件不受支持。

受Qt Quick 设计器支持的插件必须经过充分测试。这意味着该插件在Qt Quick 设计器用于执行 QML 的 qml2puppet 环境中运行时不会崩溃。 通常，插件应在Qt Quick 设计器中运行良好，且不会引发任何严重问题，例如占用过多内存、严重拖慢qml2puppet运行速度，或其他导致该插件在Qt Quick 设计器中实际上无法使用的状况。

不支持的插件中的项目在Qt Quick 设计器中不会显示图形，但仍会以空框的形式存在，且其属性可以进行编辑。

首选路径声明

prefer <Path>

此属性指示 QML 引擎从 <path> 而不是当前目录加载该模块的任何其他文件。这可用于加载使用 qmlcachegen 编译的文件。

例如，您可以将模块的 QML 文件作为资源添加到资源路径:/my/path/MyModule/ 中。然后，在 qmldir 文件中添加prefer :/my/path/MyModule ，以便使用资源系统中的文件，而不是文件系统中的文件。 如果随后对这些文件使用 qmlcachegen，则该模块的任何客户端都将能够访问这些预编译文件。

版本控制语义

所有针对特定主版本导出的 QML 类型，在同一主版本的最新版本中均可使用。例如，如果某个模块在 1.0 版本中提供了MyButton 类型，在 1.1 版本中提供了MyWindow 类型，则导入该模块1.1 版本的客户端可以使用MyButton 和MyWindow 类型。 然而，反之则不成立：针对特定次要版本导出的类型，无法通过导入较旧或更早的次要版本来使用。在前文提到的示例中，如果客户端导入了该模块的1.0 版本，则只能使用MyButton 类型，而无法使用MyWindow 类型。

一个模块可以提供多个主版本，但客户端每次只能访问其中一个主版本。例如，导入MyExampleModule 2.0 仅可访问该主版本，而无法访问之前的主版本。尽管您可以将属于不同主版本的构建产物组织在同一个目录下并使用同一个qmldir 文件进行管理，但建议为每个主版本使用不同的目录。 如果您选择采用前一种方法（一个目录和一个qmldir 文件），请尽量在文件名中使用版本后缀。例如，属于MyExampleModule 2.0 的工件，其文件名可以使用.2 作为后缀。

如果某个版本未显式导出任何类型，则无法导入该版本。如果某个模块在 1.0 版本中提供了MyButton 类型，而在 1.1 版本中提供了MyWindow 类型，则无法导入该模块的 1.2 版或 2.0 版。

同一类型可在不同次版本中由不同的文件定义。在这种情况下，客户端导入时将使用最接近的版本。例如，如果某个模块通过其qmldir 文件指定了以下类型：

module ExampleModule
MyButton 1.0 MyButton.qml
MyButton 1.1 MyButton11.qml
MyButton 1.3 MyButton13.qml
MyRectangle 1.2 MyRectangle12.qml

导入ExampleModule 的1.2 版本的客户端，可以使用MyButton11.qml 提供的MyButton 类型定义（因为这是该类型的最新版本），以及MyRectangle12.qml 提供的MyRectangle 类型定义。

版本系统可确保给定的 QML 文件无论安装的软件版本如何都能正常运行，因为带版本号的导入仅会导入该版本的类型，而保留其他标识符的可用性——即使实际安装的版本本应提供这些标识符。

qmldir 文件示例

以下是一个qmldir 文件的示例：

module ExampleModule
CustomButton 2.0 CustomButton20.qml
CustomButton 2.1 CustomButton21.qml
plugin examplemodule
MathFunctions 2.0 mathfuncs.js

上述qmldir 文件定义了一个名为“ExampleModule”的模块。 它在模块的 2.0 和 2.1 版本中定义了CustomButton QML 对象类型，每个版本的实现各不相同。它指定了一个插件，当客户端导入该模块时，引擎必须加载该插件，该插件可以将各种 C++ 定义的类型注册到 QML 类型系统中。 在类 Unix 系统上，QML 引擎会尝试将libexamplemodule.so 加载为QQmlExtensionPlugin ；而在 Windows 上，则会将examplemodule.dll 加载为QQmlExtensionPlugin 。最后，qmldir 文件定义了一个JavaScript 资源，该资源仅在导入模块的 2.0 版或更高版本（同一主版本下）时才可用。

如果该模块安装在QML 导入路径中，客户端可以按以下方式导入并使用该模块：

import QtQuick 2.0
import ExampleModule 2.1

Rectangle {
    width: 400
    height: 400
    color: "lightsteelblue"

    CustomButton {
        color: "gray"
        text: "Click Me!"
        onClicked: MathFunctions.generateRandom() > 10 ? color = "red" : color = "gray";
    }
}

上文中使用的CustomButton 类型将来自CustomButton21.qml 文件中指定的定义，而由标识符MathFunctions 标识的 JavaScript 资源则定义在mathfuncs.js 文件中。

类型描述文件

QML 模块可在其qmldir 文件中引用一个或多个类型信息文件。这些文件通常具有.qmltypes 扩展名，由外部工具读取以获取关于 C++ 中定义的类型的信息，通常通过插件导入。

因此，qmltypes 文件对 QML 模块的功能没有任何影响。其唯一用途是允许诸如 Qt Creator 等工具为您的模块用户提供代码补全、错误检查及其他功能。

任何在 C++ 中定义 QML 类型的模块都应随附一个类型描述文件。

为您的模块创建 qmltypes 文件的最佳方法是使用构建系统和QML_ELEMENT 宏来生成它。如果您按照相关文档操作，则无需采取进一步行动。qmltyperegistrar 将自动生成.qmltypes 文件。

示例：如果您的模块位于/tmp/imports/My/Module 目录下，则应与实际的插件二进制文件一同生成一个名为plugins.qmltypes 的文件。

在 xml-ph-0000@deepl.internal 中添加以下行

typeinfo plugins.qmltypes

到/tmp/imports/My/Module/qmldir 中以进行注册。