模块定义 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> 是插件库名称。这通常与插件二进制文件的文件名不同，后者取决于平台。例如，库 在 Linux 上产生 ，在 Windows 上产生 。MyAppTypes libMyAppTypes.so MyAppTypes.dll
• <Path> (可选）指定
  • 包含插件文件目录的绝对路径，或
  • 从包含qmldir 文件的目录到包含插件文件的目录的相对路径。

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

qmldir 文件中可能存在零个或多个 C++ 插件声明。不过，由于插件加载是一项相对昂贵的操作，建议客户最多指定一个插件。

示例

plugin MyPluginLibrary

插件类名声明

classname <C++ plugin class>

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

所有依赖 C++ 插件实现附加功能的 QML 模块都需要此信息。没有此信息，使用静态链接（static linking）构建的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 为版本，则导入与 QMLimport 语句中指定的本模块版本相同的版本。

设计器支持声明

designersupported

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

Qt Quick Designer 支持的插件必须经过适当测试。这意味着插件在Qt Quick Designer 用来执行 QML 的 qml2puppet 内运行时不会崩溃。一般来说，插件应在Qt Quick Designer 中运行良好，不会导致任何问题，如占用过多内存、严重降低 qml2puppet 的运行速度，或导致插件无法在Qt Quick Designer 中有效使用的任何其他问题。

在Qt Quick Designer 中，不支持插件的项目不会被绘制，但它们仍然可以作为空框使用，属性也可以编辑。

首选路径声明

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 时，只能访问该主要版本，而不能访问之前的主要版本。虽然可以在一个 sigle 目录和一个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

导入1.2 版本的ExampleModule 的客户端可以使用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 对象类型，每个版本都有不同的实现。它指定了一个插件，当客户端导入模块时，引擎必须加载该插件，该插件可在 QML 类型系统中注册各种 C++ 定义的类型。在 Unix-like 系统上，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 的文件。

在

typeinfo plugins.qmltypes

到/tmp/imports/My/Module/qmldir 以注册它。