模块定义 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>]

声明模块将提供插件。

• 可选表示插件本身不包含任何相关代码，仅用于加载它链接到的库。如果给出，并且如果模块已经提供了任何类型，则表示已通过其他方式加载了库，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>

为模块声明一个类型描述文件，该文件可以被Qt Creator等QML工具读取，以访问由模块的插件定义的类型信息。<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 设计器支持，则设置此属性。默认情况下，插件不支持。

由 Qt Quick 设计器支持的插件必须经过适当测试。这意味着插件在 Qt Quick 设计器使用的 qml2puppet 运行时不会崩溃。通常，插件应在 Qt Quick 设计器中运行良好，不会引起任何阻止问题，例如占用过多内存、大幅减慢 qml2puppet 或其他使其在 Qt Quick 设计器中几乎无法使用的情况。

不支持插件的项在 Qt Quick 设计器中不会绘制，但它们仍作为空框可用，并且可以编辑属性。

首选路径声明

prefer <Path>

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

例如，您可以添加模块的 QML 文件作为资源到资源路径 :/my/path/MyModule/。然后，将 prefer :/my/path/MyModule 添加到 qmldir 文件中，以在资源系统中使用文件，而不是在文件系统中使用。如果您为这些文件使用 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 版本的客户端可以像使用最新版本的类型一样使用 MyButton 类型定义，它是由 MyButton11.qml 提供的，并且使用由 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 对象类型，每个版本都有不同的实现。它指定了一个引擎在客户端导入模块时必须加载的插件，该插件可以登记 QML 类型系统中定义的各种 C++ 类型。在类 Unix 系统上，QML 引擎尝试将 libexamplemodule.so 作为 QQmlExtensionPlugin 加载，而在 Windows 上将其加载为 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 的文件，与实际的插件二进制文件一起生成。

将以下行添加到 /tmp/imports/My/Module/qmldir

typeinfo plugins.qmltypes

以注册它。