Import Statements

Syntax of an Import Statement

import语句允许客户端告诉引擎, QML文档使用哪些模块, JavaScript资源和组件目录.

import类型

import有三种不同类型. 每种类型有略微不同的语法, 不同的语义适用不同的类型.

模块(命名空间)导入

最常见的import类型是模块导入. 客户端可以导入 QML模块 , 这会将QML对象类型和JavaScript资源注册到给定命名空间.

import模块的一般语法如下:

  import <ModuleIdentifier> <Version.Number> [as <Qualifier>]

• <ModuleIdentifier> i是一个URI形式的标识符, 它唯一标识模块的类型命名空间.
• <Version.Number> 是 MajorVersion.MinorVersion 的一个版本, 它指定哪些对象类型和JavaScript资源可用. 它可以省略, 这时, 导入模块的最新版本. 也可以省略次要版本, 导入主版本的最新次要版本.
• <Qualifier> 是一个可选的本地命名空间标识符, 如果给定, 模块提供的对象类型和JavaScript资源将初始化这个标识符. 如果省略, 模块提供的对象类型和JavaScript资源初始化到全局命名空间.

下面展示无限制的模块导入:

  import QtQuick 2.0

这里导入 QtQuick 模块的所有类型, 且没有限定符. 如, 下面代码创建一个矩形客户端:

  import QtQuick 2.0

  Rectangle {
      width: 200
      height: 100
      color: "red"
  }

下面代码导入特定版本的QtQuick模块:

  import QtQuick 2.0 as Quick

在这种情况下, 只能使用QtQuick 2.11版本的类型, 无法使用更高版本.

下面代码展示具有限定标识的导入示例:

  import QtQuick 2.0 as Quick

  Quick.Rectangle {
      width: 200
      height: 100
      color: "red"
  }

有关限定标识符的更多信息, 参见 Importing Into A Qualified Local Namespace.

注意: 如果QML文档没有导入包含QML对象类型的模块, 那么, 尝试使用对象类型时, 会发生错误. 例如, 下面代码没有导入QtQuick模块, 使用 Rectangle 类型时将失败:

  Rectangle {
      width: 200
      height: 100
      color: "red"
  }

在这种情况下, QML引擎将发出错误, 拒绝加载这个文件.

C++模块导入

通常, C++类型使用QML_ELEMENT和QML_NAMED_ELEMENT()宏声明, 并使用QML_IMPORT_NAME和QML_IMPORT_MAJOR_VERSION注册. 采用这种方式, 可以在QML文件中导入给定名称和版本的模块, 并访问模块类型.

这个最常见的用法是: 在客户端采用C++自定义QML对象类型.

导入到限定命名空间

import 语句支持可选的本地命名空间, 以 as 关键字指定命名空间限定符. 如果指定命名空间, 使用任何类型时都必须以本地命名空间限定符作为前缀.

下面代码, 将 QtQuick 模块导入命名空间 "CoreItems". 使用 QtQuick 模块的任意类型必须添加 CoreItems 命名空间限定符:

  import QtQuick 2.0 as CoreItems

  CoreItems.Rectangle {
      width: 100; height: 100

      CoreItems.Text { text: "Hello, world!" }

      // WRONG! No namespace prefix - the Text type won't be found
      Text { text: "Hello, world!" }
  }

命名空间作为当前文件范围内模块的标识符. 命名空间不是根对象的一个属性, 可以像使用属性, 信号和方法那样从外部引用.

当需要使用位于不同模块, 具有相同的名称的QML类型时, 命名空间是非常有用. 这种情况下, 将两个模块导入不同的命名空间, 确保代码引用正确类型:

  import QtQuick 2.0 as CoreItems
  import "../textwidgets" as MyModule

  CoreItems.Rectangle {
      width: 100; height: 100

      MyModule.Text { text: "Hello from my custom text item!" }
      CoreItems.Text { text: "Hello from Qt Quick!" }
  }

注意: 多个模块可以导入相同的命名空间. 例如:

  import QtQuick 2.0 as Project
  import QtMultimedia 5.0 as Project

  Project.Rectangle {
      width: 100; height: 50

      Project.Audio {
          source: "music.wav"
          autoPlay: true
      }
  }

导入目录

包含QML文档的目录可以导入到当前QML文档中. 这为QML类型分组提供一种简单方法: 文件系统上的目录.

目录导入的一般形式如下:

  import "<DirectoryPath>" [as <Qualifier>]

注意: 导入路径是网络透明的: 应用程序可以从远程路径导入文档, 跟本地路径导入一样简单. 详见 Network Transparency. 如果目录是远程目录, 它必须包含一个 directory import listing qmldir file 因为如果qmldir不存在, QML引擎无法确定远程目录的内容.

<Qualifier> 语义也适用目录导入. 详见上一节 Importing into a Qualified Local Namespace.

有关目录导入的更多信息, 参见 directory imports.

JavaScript 资源导入

JavaScript资源也可以直接导入到QML文档中. 每个JavaScript资源必须有一个访问标识符.

JavaScript资源导入的一般形式如下:

  import "<JavaScriptFile>" as <Identifier>

注意: 在QML文档中, <Identifier> 必须唯一. 这与本地命名空间不一样.

JavaScript Resources from Modules

JavaScript文件可以由模块提供, 通过将标识符定义到模块的qmldir文件.

例如, 如果使用qmldir目录下的 projects.MyQMLProject.MyFunctions 模块, 并将其初始化到QML导入路径:

  module projects.MyQMLProject.MyFunctions
  SystemFunctions 1.0 SystemFunctions.js
  UserFunctions 1.0 UserFunctions.js

客户端应用程序导入模块, 并使用与声明的资源相关联的标识符来导入在模块中声明的JavaScript资源:

  import QtQuick 2.0
  import projects.MyQMLProject.MyFunctions 1.0

  Item {
      Component.onCompleted: { SystemFunctions.cleanUp(); }
  }

如果模块被导入到文档本地命名空间, 则JavaScript资源标识符必须以命名空间限定符为前缀才能使用:

  import QtQuick 2.0
  import projects.MyQMLProject.MyFunctions 1.0 as MyFuncs
  import org.example.Functions 1.0 as TheirFuncs

  Item {
      Component.onCompleted: {
          MyFuncs.SystemFunctions.cleanUp();
          TheirFuncs.SystemFunctions.shutdown();
      }
  }

更多信息

有关JavaScript资源的更多信息, 参见 defining JavaScript resources in QML, 有关如何导入JavaScript资源及如何从JavaScript资源导入的更多信息, 参见 importing JavaScript resources in QML.

QML导入路径

导入已识别的模块 时, QML引擎搜索导入路径, 并匹配模块.

QQmlEngine::importPathList(), 返回导入路径, 定义QML引擎搜索的默认位置. 默认情况下, 返回目录包含:

• 当前文件目录
• QLibraryInfo::QmlImportsPath指定目录
• QML_IMPORT_PATH 环境变量配置目录
• qrc:/qt-project.org/imports 目录.

调用 QQmlEngine::addImportPath() 或配置 QML2_IMPORT_PATH 环境变量添加其他导入路径. 运行 qmlscene 工具程序时, 你也可以使用 -I 添加导入路径.

你可以在环境变量QML_IMPORT_PATH中指定多个导入路径, 使用路径分隔符将它们连接起来. 在Windows上, 路径分隔符是分号(;), 其他平台上是冒号(:). 这意味着你不能在QML_IMPORT_PATH中指定资源路径或URL, 因为它们本身包含冒号. 然而, 你可以调用QQmlEngine::addImportPath()添加资源路径和URL.

调试

环境变量 QML_IMPORT_TRACE 对于查找和加载模块时出现问题的调试非常有用, 详见 Debugging module imports.