Import Statements 導入語句

Syntax of an Import Statement

導入語句的語法

An import statement allows clients to tell the engine which modules, JavaScript resources and component directories are used within a QML document. The types which may be used within a document depends on which modules, resources and directories are imported by the document.

導入語句容許客戶告訴引擎QML文檔內可以使用哪些模塊、JavaScript資源和組件目錄。文檔內可使用哪些類型依賴於被文檔導入的模塊、資源和目錄。

Import Types

導入類型

There are three different types of imports. Each import type has a slightly different syntax, and different semantics apply to different import types.

有3種不一樣類型的導入。每種導入類型在語法上有細微的差異，不一樣的語義應用到不一樣的導入類型。

Module (Namespace) Imports

模塊的導入

The most common type of import is a module import. Clients can import QML modules which register QML object types and JavaScript resources into a given namespace.

最多見的導入是模塊導入。客戶能夠導入註冊了對象類型的模塊和JavaScript資源到給定的命名空間。

The generic form of a module import is as follows:

模塊導入的通常形式以下：

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

The <ModuleIdentifier> is an identifier specified in dotted URI notation, which uniquely identifies the type namespace provided by the module.

The <Version.Number> is a version of the form MajorVersion.MinorVersion which specifies which definitions of various object types and JavaScript resources will be made available due to the import.

The <Qualifier> is an optional local namespace identifier into which the object types and JavaScript resources provided by the module will be installed, if given. If omitted, the object types and JavaScript resources provided by the module will be installed into the global namespace.

<ModuleIdentifier>是點分URI表示法指定的標識符，此標識符是模塊提供的命名空間類型的惟一識別。

<Version.Number>是大版本.小版本格式的版本號。指定各對象類型和JavaScript資源的哪一個版本哪一個定義將被提供給導入。

<Qualifier>是可選的本地命名空間，若是給出，它做爲模塊提供的對象類型和JavaScript資源的識別(命名空間)被安裝。若是省略，模塊提供的對象類型和JavaScript資源將被安裝到全局命名空間。

An example of an unqualified module import is as follows:

以下是一個無限定的模塊導入的例子：

import QtQuick 2.0

This import allows the use of all of the types provided by the QtQuick module without needing to specify a qualifier. For example, the client code to create a rectangle is as follows:

這樣導入容許使用 QtQuick 模塊提供的全部類型，不須要指定限定(的命名空間)。例如，客戶代碼能夠建立 rectangle 以下：

import QtQuick 2.0

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

An example of a qualified module import is as follows:

以下是一個限定的模塊導入：

import QtQuick 2.0 as Quick

This import allows multiple modules which provide conflicting type names to be imported at the same time, however since each usage of a type provided by a module which was imported into a qualified namespace must be preceded by the qualifier, the conflict is able to be resolved unambiguously by the QML engine.

這樣容許同時導入多個提供的類型有名稱衝突的模塊，因爲每個類型都由被導入限定命名空間的模塊提供，因此在使用時必須在前邊加上限定符(能夠理解爲命名空間)，衝突能夠經過QML引擎明確地解決掉。

An example of client code which creates a rectangle after using a qualified module import is as follows:

以下是一個使用限定式模塊導入的客戶代碼建立一個 rectangle 的例子：

import QtQuick 2.0 as Quick

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

For more information about qualified imports, see the upcoming section on Importing Into A Qualified Local Namespace.

關於限定式導入的更多信息，請看接下來的章節<Importing Into A Qualified Local Namespace>導入到限定的本地命名空間。

Note that if a QML document does not import a module which provides a particular QML object type, but attempts to use that object type anyway, an error will occur.

注意，若是QML文檔不導入提供具體QML對象類型的模塊，可是嘗試使用那個對象類型，將產生錯誤。

For example, the following QML document does not import QtQuick and thus attempting to use the Rectangle type will fail:

例如，以下的QML文檔不導入 QtQuick 並嘗試使用 Rectangle 類型，將失敗：

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

In this case, the engine will emit an error and refuse to load the file.

這種狀況，引擎將發射一個錯誤並拒絕載入文件。

Non-module Namespace Imports

無模塊命名空間導入

Types can also be registered into namespaces directly via the various registration functions in C++ (such as qmlRegisterType()). The types which have been registered into a namespace in this way may be imported by importing the namespace, as if the namespace was a module identifier.

類型也能夠在C++中經過各類註冊函數直接註冊到命名空間(例如 qmlRegisterType() 函數)。被註冊進命名空間的類型能夠經過導入命名空間被導入，如同命名空間是一個模塊標識。

This is most common in client applications which define their own QML object types in C++ and register them with the QML type system manually.

這是客戶端程序中最經常使用，在C++中定義本身的QML對象類型而且在QML類型系統手動地註冊他們。

Importing into a Qualified Local Namespace

導入限定的本地命名空間

The import statement may optionally use the as keyword to specify that the types should be imported into a particular document-local namespace. If a namespace is specified, then any references to the types made available by the import must be prefixed by the local namespace qualifier.

導入語句能夠選擇性的使用關鍵字去指定類型應該被導入特定的的本地文檔命名空間。若是指定命名空間，那麼想引用任何被導入的類型都必須以本地命名空間前綴限定。

Below, the QtQuick module is imported into the namespace "CoreItems". Now, any references to types from the QtQuick module must be prefixed with the CoreItems name:

以下，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!" }
}

A namespace acts as an identifier for a module within the scope of the file. The namespace does not become an attribute of the root object that can be referred to externally as can be done with properties, signals and methods.

命名空間做爲文件範圍內的模塊的標識。命名空間不像屬性、信號和方法同樣被操做，不會變成可引用到外部的根對象的屬性.

The namespaced import is useful if there is a requirement to use two QML types that have the same name but are located in different modules. In this case the two modules can be imported into different namespaces to ensure the code is referring to the correct type:

命名空間入口是有用的,若是須要使用2個QML類型有相同的名字可是位於不一樣的模塊.這種狀況下2個模塊能夠被導入不一樣的命名空間以確保代碼引用正確的類型:

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!" }
}

Note that multiple modules can be imported into the same namespace in the same way that multiple modules can be imported into the global namespace. For example:

注意多模塊能夠被導入同一個命名空間,一樣的多模塊能夠被被導入全局命名空間.例如:

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
    }
}

Directory Imports

目錄的導入

A directory which contains QML documents may also be imported directly in a QML document. This provides a simple way for QML types to be segmented into reusable groupings: directories on the filesystem.

包含QML文檔的目錄也能夠被直接導入到QML文檔。這提供了一個簡單的方法以把QML類型分割成可複用的組：文件系統上的目錄。

The generic form of a directory import is as follows:

目錄導入的格式一般以下：

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

Note: Import paths are network transparent: applications can import documents from remote paths just as simply as documents from local paths. See the general URL resolution rules for Network Transparency in QML documents. If the directory is remote, it must contain a directory import listing qmldir file as the QML engine cannot determine the contents of a remote directory if that qmldir file does not exist.

注意：導入路徑是網絡透明的：應用程序能夠從遠程路徑導入文檔如同從本地路徑導入同樣簡單。查看通用的QML文檔的網絡透明的URL解析規則。若是目錄是遠程的，它必須包含一個(目錄導入清單)qmldir文件，若是qmldir文件不存在QML引擎不能肯定遠程目錄的內容。

Similar semantics for the <Qualifier> apply to directory imports as for module imports; for more information on the topic, please see the previous section about Importing into a Qualified Local Namespace.

<Qualifier>應用到目錄導入和模塊導入有相同的語義；更多信息請查看前一章節<Importing into a Qualified Local Namespace>。

For more information about directory imports, please see the in-depth documentation about directory imports.

關於目錄導入的更多信息，請查看更深刻的文檔<directory imports>。

JavaScript Resource Imports

JavaScript資源的導入

JavaScript resources may be imported directly in a QML document. Every JavaScript resource must have an identifier by which it is accessed.

JavaScript資源能夠被直接導入到QML文檔。每個JavaScript資源必須有一個針對它的訪問者的標識。

The generic form of a JavaScript resource import is as follows:

JavaScript資源的導入格式一般以下：

import "<JavaScriptFile>" as <Identifier>

Note that the <Identifier> must be unique within a QML document, unlike the local namespace qualifier which can be applied to module imports.

注意<Identifier>必須是QML文檔內獨一無二的，不一樣於可應用到模塊入口的本地命名空間限定符。

JavaScript Resources from Modules

來自模塊的JavaScript資源

Javascript files can be provided by modules, by adding identifier definitions to the qmldir file which specifies the module.

模塊能夠提供Javascript文件，經過添加標識說明到qmldir文件，qmldir文件是用來指定模塊的。

For example, if the projects.MyQMLProject.MyFunctions module is specified with the following qmldir file, and installed into the QML import path:

例如，若是projects.MyQMLProject.MyFunctions模塊被以下的qmldir文件指定，而且安裝在QML的入口路徑：

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

a client application is able to import the JavaScript resources declared in the module by importing the module and using the identifier associated with a declared resource:

客戶端應用程序能夠經過導入模塊來導入模塊內的已聲明的JavaScript資源，而且使用標識關聯到對應的已聲明的資源。

import QtQuick 2.0
import projects.MyQMLProject.MyFunctions 1.0

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

If the module was imported into a document-local namespace, the JavaScript resource identifiers must be prefixed with the namespace qualifier in order to be used:

若是模塊被導入到文檔局部的命名空間，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();
    }
}

Further Information

補充信息

For more information about JavaScript resources, please see the documentation about defining JavaScript resources in QML, and for more information about how to import JavaScript resources, and how imports can be used from within JavaScript resources, please see the in-depth documentation about importing JavaScript resources in QML.

關於JavaScript資源的更多信息，請查看QML中文檔<defining JavaScript resources in QML>在QML中定義JavaScript資源，更多的關於導入JavaScript資源的信息，如何在JavaScript資源內部導入，請查看更深刻的文檔<importing JavaScript resources in QML>在QML中導入JavaScript資源。

QML Import Path

QML 導入路徑

When an identified module is imported, the QML engine searches the import path for a matching module.

當識別的模塊被導入，QML 引擎查找匹配的模塊的導入路徑。

This import path, as returned by QQmlEngine::importPathList(), defines the default locations to be searched by the engine. By default, this list contains:

這個導入路徑，做爲 QQmlEngine::importPathList() 的返回值，定義引擎搜索的默認爲止。默認狀況下，列表包含：

1 The directory of the current file

2 The location specified by QLibraryInfo::Qml2ImportsPath

3 Paths specified by the QML2_IMPORT_PATH environment variable

Additional import paths can be added through QQmlEngine::addImportPath() or the QML2_IMPORT_PATH environment variable. When running the qmlscene tool, you can also use the -I option to add an import path.

附加導入路徑能夠經過 QQmlEngine::addImportPath() 或者環境變量 QML2_IMPORT_PATH 添加。當運行 qmlscene 工具，可使用 -I 選項添加導入路徑。

Debugging

The QML_IMPORT_TRACE environment variable can be useful for debugging when there are problems with finding and loading modules. See Debugging module imports for more information.

當查找和載入模塊有問題時，環境變量 QML_IMPORT_TRACE 對調試有用。更詳細的信息請查看調試模塊的導入。