模块定义qmldir文件

Module Definition qmldir Files

模块定义qmldir文件

There are two distinct types of qmldir files:

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

• QML document directory listing files
• 列出文件的QML文档目录
• QML module definition files
• QML模块定义文件

This documentation covers only the second form of qmldir file, which lists the QML types, JavaScript files, and plugins that are available under a module. For more information about the first form of qmldir file, see directory listing qmldir files.

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

Contents of a Module Definition qmldir File

模块定义qmldir文件的内容

A qmldir file is a plain-text file that contains the following commands:

qmldir文件是包含以下命令的纯文本文件：

Syntax 语法	Usage 用法
module <ModuleIdentifier>	Declares the module identifier of the module. The <ModuleIdentifier> is the (dotted URI notation) identifier for the module, which must match the module's install path. 声明模块的模块标识符。<ModuleIdentifier>是模块的（点URI表示法）标识符，必须与模块的安装路径匹配。 The module identifier directive must be the first line of the file. Exactly one module identifier directive may exist in the qmldir file. ​模块标识符指令必须位于文件的第一行。qmldir文件中可能只存在一个模块标识符指令。 Example: 例子： module ExampleModule
[singleton] <TypeName> <InitialVersion> <File>	Declares a QML object type to be made available by the module. ​声明要由模块提供的QML对象类型。 [singleton] Optional. Used to declare a singleton type. [singleton]可选。用于声明单例类型。 <TypeName> is the type being made available <TypeName>是可用的类型 <InitialVersion> is the module version for which the type is to be made available <InitialVersion>是要为其提供类型的模块版本 <File> is the (relative) file name of the QML file that defines the type <File>是定义类型的QML文件的（相对）文件名 Zero or more object type declarations may exist in the qmldir file, however each object type must have a unique type name within any particular version of the module. qmldir文件中可能存在零个或多个对象类型声明，但是每个对象类型在模块的任何特定版本中都必须具有唯一的类型名称。 Note: To declare a singleton type, the QML file defining the type must include the pragma Singleton statement. 注意：要声明单例类型，定义该类型的QML文件必须包含pragma singleton语句。 Example: 例子： //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>	Declares an object type that is in the module but should not be made available to users of the module. 声明模块中的对象类型，但不应提供给模块用户。 Zero or more internal object type declarations may exist in the qmldir file. qmldir文件中可能存在零个或多个内部对象类型声明。 Example: 例子： internal MyPrivateType MyPrivateType.qml This is necessary if the module may be imported remotely (see Remotely Installed Identified Modules) because if an exported type depends on an non-exported type within the module, the engine must also load the non-exported type. ​如果可以远程导入模块（请参阅远程安装的标识模块），这是必要的，因为如果导出类型依赖于模块内的非导出类型，则引擎还必须加载非导出类型。
<ResourceIdentifier> <InitialVersion> <File>	Declares a JavaScript file to be made available by the module. The resource will be made available via the specified identifier with the specified version number. 声明将由模块提供的JavaScript文件。资源将通过具有指定版本号的指定标识符可用。 Zero or more JavaScript resource declarations may exist in the qmldir file, however each JavaScript resource must have a unique identifier within any particular version of the module. qmldir文件中可能存在零个或多个JavaScript资源声明，但是每个JavaScript资源在模块的任何特定版本中都必须具有唯一标识符。 Example: 例子： MyScript 1.0 MyScript.js See the documentation about defining JavaScript resources and Importing JavaScript Resources In QML for more information. ​有关更多信息，请参阅有关在QML中定义JavaScript资源和导入JavaScript资源的文档。
[optional] plugin <Name> [<Path>]	Declares a plugin to be made available by the module. 声明将由模块提供的插件。 optional denotes that the plugin itself does not contain any relevant code and only serves to load a library it links to. If given, and if any types for the module are already available, indicating that the library has been loaded by some other means, QML will not load the plugin. 可选表示插件本身不包含任何相关代码，只用于加载它链接到的库。如果给定，并且模块的任何类型已经可用，表明库已经通过其他方式加载，QML将不会加载插件。 <Name> is the plugin library name. This is usually not the same as the file name of the plugin binary, which is platform dependent; e.g. the library MyAppTypes would produce libMyAppTypes.so on Linux and MyAppTypes.dll on Windows. <Name>是插件库的名称。这通常与插件二进制文件的文件名不同，后者取决于平台；e.g.库MyAppTypes将在Linux上生成libMyAppTypes.so和在Windows上生成MyAppType.dll。 <Path> (optional) specifies either: <Path>（可选）指定： an absolute path to the directory containing the plugin file, or 包含插件文件的目录的绝对路径 a relative path from the directory containing the qmldir file to the directory containing the plugin file. 从包含qmldir文件的目录到包含插件文件的目录的相对路径。 By default the engine searches for the plugin library in the directory that contains the qmldir file. (The plugin search path can be queried with QQmlEngine::pluginPathList() and modified using QQmlEngine::addPluginPath().) ​默认情况下，引擎会在包含qmldir文件的目录中搜索插件库。（可以使用QQmlEngine::pluginPathList（）查询插件搜索路径，并使用QQmlEngine::addPluginPath（）修改插件搜索路径。） Zero or more C++ plugin declarations may exist in the qmldir file, however since plugin loading is a relatively expensive operation, clients are advised to specify at most a single plugin. qmldir文件中可能存在零个或多个C++插件声明，但是由于插件加载是一个相对昂贵的操作，建议客户端最多指定一个插件。 Example: 例子： plugin MyPluginLibrary
classname <C++ plugin class>	Provides the class name of the C++ plugin used by the module. 提供模块使用的C++插件的类名。 This information is required for all the QML modules that depend on a C++ plugin for additional functionality. Qt Quick applications built with static linking cannot resolve the module imports without this information. 所有依赖C++插件实现附加功能的QML模块都需要此信息。使用静态链接构建的Qt Quick应用程序无法解析没有此信息的模块导入。
typeinfo <File>	Declares a type description file for the module that can be read by QML tools such as Qt Creator to access information about the types defined by the module's plugins. <File> is the (relative) file name of a .qmltypes file. ​声明模块的类型描述文件，Qt Creator等QML工具可以读取该文件，以访问有关模块插件定义的类型的信息。<File>是文件的（相对）文件名的qmltypes文件。 Example: 例子： typeinfo mymodule.qmltypes Without such a file, QML tools may be unable to offer features such as code completion for the types defined in your plugins. 如果没有这样的文件，QML工具可能无法为插件中定义的类型提供代码完成等功能。
depends <ModuleIdentifier> <InitialVersion>	Declares that this module depends on another. 声明此模块依赖于另一个模块。 Example: 例子： depends MyOtherModule 1.0 This declaration is necessary only in cases when the dependency is hidden: for example, when the C++ code for one module is used to load QML (perhaps conditionally) which then depends on other modules. In such cases, the depends declaration is necessary to include the other modules in application packages. 只有在依赖项被隐藏的情况下，这个声明才是必要的：例如，当一个模块的C++代码被用来加载QML（可能是有条件的），QML随后依赖于其他模块。在这种情况下，depends声明是在应用程序包中包含其他模块所必需的。
import <ModuleIdentifier> [<Version>]	Declares that this module imports another. 声明此模块导入另一个。 Example: 例子： import MyOtherModule 1.0 The types from the other module are made available in the same type namespace as this module is imported into. Omitting the version imports the latest version available of the other module, specifying auto as version imports the same version as the version of this module specified in the QML import statement. 来自另一个模块的类型在该模块导入到的同一类型命名空间中可用。省略版本将导入其他模块的可用最新版本，指定auto版本号将导入与QML import语句中指定的此模块版本相同的版本。
# <Comment>	Declares a comment. These are ignored by the engine. 声明一条评论。这些都被引擎忽略了。 Example: 例子： # this is a comment
designersupported	Set this property if the plugin is supported by Qt Quick Designer. By default, the plugin will not be supported. 如果Qt Quick Designer支持该插件，请设置此属性。默认情况下，插件将不受支持。 A plugin that is supported by Qt Quick Designer has to be properly tested. This means that the plugin does not crash when running inside the qml2puppet that is used by Qt Quick Designer to execute QML. Generally the plugin should work well in the Qt Quick Designer and not cause any show stoppers, like taking huge amounts of memory, slowing down the qml2puppet heavily or anything else that renders the plugin effectively unusable in the Qt Quick Designer. Qt Quick Designer支持的插件必须经过正确测试。这意味着该插件在Qt Quick Designer用于执行QML的qml2uppet中运行时不会崩溃。一般来说，该插件应该在Qt Quick Designer中运行良好，并且不会导致任何显示中断，比如占用大量内存、严重降低QML2uppet的速度，或者其他任何导致插件在Qt Quick Designer中实际上不可用的事情。 The items of an unsupported plugin are not painted in the Qt Quick Designer, but they are still available as empty boxes and the properties can be edited. Qt Quick Designer中不会绘制不受支持插件的项目，但它们仍然可以作为空框使用，并且可以编辑属性。
prefer <Path>	This property directs the QML engine to load any further files for this module from <path>, rather than the current directory. This can be used to load files compiled with qmlcachegen. 此属性指示QML引擎从<path>而不是当前目录加载此模块的任何其他文件。这可用于加载使用qmlcachegen编译的文件。 For example, you can add a module's QML files as resources to a resource path :/my/path/MyModule/. Then, add prefer :/my/path/MyModule to the qmldir file in order to use the files in the resource system, rather than the ones in the file system. If you then use qmlcachegen for those, the pre-compiled files will be available to any clients of the module. 例如，可以将模块的QML文件作为资源添加到资源路径：/my/path/MyModule/。然后，将preference:/my/path/MyModule添加到qmldir文件中，以便使用资源系统中的文件，而不是文件系统中的文件。如果使用qmlcachegen进行这些操作，则预编译的文件将可供模块的任何客户端使用。

Each command in a qmldir file must be on a separate line.

qmldir文件中的每个命令必须位于单独的行上。

Versioning Semantics

版本语义

All QML types that are exported for a particular major version are available with the latest version of the same major version. For example, if a module provides a MyButton type in version 1.0 and MyWindow type in version 1.1, clients importing version 1.1 of the module get to use the MyButton and MyWindow types. However, the reverse is not true: a type exported for a particular minor version cannot be used by importing an older or earlier minor version. In the example mentioned earlier, if the client had imported version 1.0 of the module, they can use the MyButton type only but not the MyWindow type.

为特定主要版本导出的所有QML类型都可以与同一主要版本的最新版本一起使用。例如，如果模块在版本1.0中提供MyButton类型，在版本1.1中提供MyWindow类型，则导入模块版本1.1的客户端可以使用MyButton和MyWindow类型。然而，情况并非如此：为特定次要版本导出的类型不能通过导入较旧或较早的次要版本来使用。在前面提到的示例中，如果客户机导入了模块的1.0版本，那么他们只能使用MyButton类型，而不能使用MyWindow类型。

A module can offer multiple major versions but the clients have access to one major version only at a time. For example, importing MyExampleModule 2.0 provides access to that major version only and not the previous major version. Although you can organize the artifacts that belong to different major versions under a sigle directory and a qmldir file, it is recommended to use different directories for each major version. If you choose to go with the earlier approach (one directory and a qmldir file), try to use the version suffix for the file names. For example, artifacts that belong to MyExampleModule 2.0 can use .2 suffix in their file name.

一个模块可以提供多个主要版本，但客户端一次只能访问一个主要版本。例如，导入MyExampleModule 2.0只提供对该主要版本的访问，而不提供对以前主要版本的访问。虽然您可以将属于不同主要版本的工件组织在一个单一目录和一个qmldir文件下，但建议对每个主要版本使用不同的目录。如果选择使用前面的方法（一个目录和一个qmldir文件），请尝试使用版本后缀作为文件名。例如，属于MyExampleModule 2.0的工件可以在其文件名中使用.2后缀。

A version cannot be imported if no types have been explicitly exported for that version. If a module provides a MyButton type in version 1.0 and a MyWindow type in version 1.1, you cannot import version 1.2 or version 2.0 of that module.

如果没有为该版本显式导出类型，则无法导入该版本。如果模块在版本1.0中提供MyButton类型，在版本1.1中提供MyWindow类型，则无法导入该模块的版本1.2或版本2.0。

A type can be defined by different files in different minor versions. In this case, the most closely matching version is used when imported by clients. For example, if a module had specified the following types via its qmldir file:

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

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

a client who imports version 1.2 of ExampleModule can use the MyButton type definition provided by MyButton11.qml as it is the latest version of that type, and the MyRectangle type definition provided by MyRectangle12.qml.

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

The version system ensures that a given QML file works regardless of the version of installed software, as a versioned import only imports types for that version, leaving other identifiers available, even if the actual installed version might otherwise provide those identifiers.

版本系统确保给定的QML文件无论安装软件的版本如何都能工作，因为版本化导入只导入该版本的类型，而保留其他可用标识符，即使实际安装的版本可能提供这些标识符。

Example of a qmldir File

qmldir文件的示例

One example of a qmldir file follows:

qmldir文件的一个示例如下：

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

The above qmldir file defines a module called "ExampleModule". It defines the CustomButton QML object type in versions 2.0 and 2.1 of the module, with different implementations for each version. It specifies a plugin that must be loaded by the engine when the module is imported by clients, and that plugin may register various C++-defined types with the QML type system. On Unix-like systems the QML engine attempts to load libexamplemodule.so as a QQmlExtensionPlugin, and on Windows it loads examplemodule.dll as a QQmlExtensionPlugin. Finally, the qmldir file specifies a JavaScript resource, which is only available if version 2.0 or a later version (under the same major version) of the module is imported.

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

If the module is installed into the QML import path, clients could import and use the module in the following manner:

​如果安装了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";
    }
}

The CustomButton type used above would come from the definition specified in the CustomButton21.qml file, and the JavaScript resource identified by the MathFunctions identifier would be defined in the mathfuncs.js file.

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

Type Description Files

类型描述文件

QML modules may refer to one or more type information files in their qmldir file. These usually have the .qmltypes extension and are read by external tools to gain information about types defined in C++ and typically imported via plugins.

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

As such qmltypes files have no effect on the functionality of a QML module. Their only use is to allow tools such as Qt Creator to provide code completion, error checking and other functionality to users of your module.

因此，QML类型文件对QML模块的功能没有影响。它们唯一的用途是允许Qt Creator等工具为模块用户提供代码完成、错误检查和其他功能。

Any module that defines QML types in C++ should also ship a type description file.

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

The best way to create a qmltypes file for your module is to generate it using the build system and the QML_ELEMENT macros. If you follow the documentation on this, no further action is needed. qmltyperegistrar will automatically generate the .qmltypes files.

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

Example: If your module is in /tmp/imports/My/Module, a file caled plugins.qmltypes should be generated alongside the actual plugin binary.

示例：如果您的模块位于/tmp/imports/My/module中，则会显示一个文件为plugins.qmltypes应该与实际的插件二进制文件一起生成。

Add the line

加行

typeinfo plugins.qmltypes

to /tmp/imports/My/Module/qmldir to register it.

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

© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.