旧版模块
旧版模块是指其规范文件qmldir 中不包含模块标识符指令的模块。旧版模块既可以安装到 QML 导入路径中(作为已安装的旧版模块),也可以由客户端通过相对导入进行导入(作为已定位的旧版模块)。 建议客户端尽可能避免使用旧版模块。模块开发者应确保创建的是已标识模块,而非旧版模块。
已安装的旧版模块
对于已安装但未标识的模块,QML 引擎会自动为其分配一个标识符。该隐式定义的标识符等于模块的安装路径(相对于 QML 导入路径),其中目录分隔符被替换为句点。
安装在 QML 导入路径中的未标识模块具有以下语义:
- 客户端可通过隐式模块标识符导入该模块
- 客户端在导入该模块时必须指定版本
- 冲突的类型名称将由 QML 引擎任意解决,且不同版本的 QML 中冲突的解决方式不保证保持一致
- 其他遗留模块可能会修改或覆盖已安装的遗留模块所提供的类型定义
已定位的遗留模块
通过相对目录路径导入语句导入的未标识模块,将由引擎作为已定位的旧版模块加载。以下语义适用于已定位的旧版模块:
- 客户端可通过相对导入路径导入该模块
- 客户端在导入该模块时无需指定版本
- 如果客户端在导入语句中未提供导入版本,QML 引擎不保证将导入给定类型名的哪个版本的定义
- 冲突的类型名称由 QML 引擎任意解析,且不同版本的 QML 之间,冲突解析方式不保证保持一致
- 其他遗留模块可能会修改或覆盖被定位的遗留模块所提供的类型定义
已定位的旧版模块可能位于本地文件系统或网络上,并可通过指定文件系统路径或网络 URL 的 URL 进行引用。
另请参阅 《QML 模块现代化》和《将 QML 模块移植到 CMake》。
© 2026 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.