Delphi XE5教程8：使用Delphi命名空間

// Project file declarations...

//項目文件聲明…

program MyCompany.ProjectX.ProgramY;

 

// Unit source file declaration...

//單元源文件聲明

unit MyCompany.ProjectX.ProgramY.MyUnit1;

 

內容源自Delphi XE5 UPDATE 2官方幫助《Delphi Reference》，本人水平有限，歡迎各位高人修正相關錯誤！

 

也歡迎各位加入到Delphi學習資料漢化中來，有興趣者可QQ：34484690@qq.com

Using Namespaces with Delphi

使用Delphi命名空間

 

Important: RAD Studio now supports a unit scope name or prefix in addition to the namespace or unit name. In order for a name to be considered fully qualified, the unit scope name must be included. For more details, see Unit Scope Names.

重要提示：RAD Studio如今支持爲命名空間或單元名稱添加單元空間名稱或前綴。爲了讓其被認爲是徹底合格的名稱，單元空間名稱必須包括在內。有關詳細信息，請參見單元空間名稱。

 

In Delphi, a unit is the basic container for types. In Delphi, a namespace is a container of Delphi units.

在Delphi中，一個單元是基本容器類型。在Delphi中，一個命名空間是Delphi單元的容器。

 

Unlike traditional Delphi units, namespaces can be nested to form a containment hierarchy. Nested namespaces provide a way to organize identifiers and types, and are used to disambiguate types with the same name. Since they are a container for Delphi units, namespaces may also be used to differentiate between units of the same name, that reside in different packages.

不一樣於傳統的Delphi單元，命名空間能夠嵌套，從而造成一個層次結構。嵌套的命名空間提供了一種組織標識符和類型，以及用於對具備相同名稱的類型消除歧義。由於它們是Delphi單元的一個容器，命名空間也能夠使用具備相同名稱的單元，用其駐留在不一樣的包中進行區分。

 

For example, the class MyClass in MyNameSpace, is different from the class MyClass in YourNamespace.

例如，MyNameSpace命名空間中的MyClass，不一樣於YourNameSpace中的MyClass。

 

This topic describes the following:

本主題介紹瞭如下內容：

 Project default namespaces, and namespace declaration.

項目的默認命名空間，以及命名空間聲明。

 Namespace search scope.

命名空間的搜索範圍。

 Using namespaces in Delphi units.

 在Delphi單元中使用命名空間。

 

1 Declaring Namespaces

1 聲明命名空間

 

In RAD Studio, a project file (program, library, or package) implicitly introduces its own namespace, called the project default namespace. A unit may be a member of the project default namespace, or it may explicitly declare itself to be a member of a different namespace. In either case, a unit declares its namespace membership in its unit header. For example, consider the following explicit namespace declaration:

在RAD Studio中，項目文件（程序，庫或包）隱式地引入了本身的名字空間，項目調用默認的命名空間。單元在它的單元標題中聲明瞭它是哪一個命名空間的成員。例如，下面命名空間的聲明：

unit MyCompany.MyWidgets.MyUnit;

 

First, notice that the parts of namespaces are separated by dots. Namespaces do not introduce new symbols for the identifiers between the dots; the dots are part of the unit name. The source file name for this example is MyCompany.MyWidgets.MyUnit.pas, and the compiled output file name is MyCompany.MyWidgets.MyUnit.dcu.

首先，請注意命名空間是使用.分隔各個部分。命名空間不在.之間引入新的標識符；.做爲單元名稱的一部分。這個例子的源文件的名稱是MyCompany.MyWidgets.MyUnit.pas，而且編譯輸出的文件是MyCompany.MyWidgets.MyUnit.dcu。

 

Second, notice that the dots imply the conceptual nesting, or containment, of one namespace within another. The example above declares the unit MyUnit to be a member of the MyWidgets namespace, which itself is contained in the MyCompany namespace. Again, it should be noted that this containment is for documentation purposes only.

其次，請注意.意味着命名空間中的另外一個嵌套概念，或容器。上面的例子中聲明MyUnit單元是MyWidgets命名空間的一個成員，它自己是包含在MyCompany命名空間中的。再次，應該注意的是，這只是容納文檔的目的。

 

A project default namespace declares a namespace for all of the units in the project. Consider the following declarations:

爲項目中的全部units聲明一個默認的命名空間，請考慮如下聲明：

Program MyCompany.Programs.MyProgram;

Library MyCompany.Libs.MyLibrary;

Package MyCompany.Packages.MyPackage;

 

These statements establish the project default namespace for the program, library, and package, respectively. The namespace is determined by removing the rightmost identifier (and dot) from the declaration.

這些語句爲程序,庫和包分別創建了默認的命名空間，命名空間從聲明的最右邊的標識符（以及.）肯定。

 

A unit that omits an explicit namespace is called a generic unit. A generic unit automatically becomes a member of the project default namespace. Given the preceding program declaration, the following unit declaration would cause the compiler to treat MyUnit as a member of the MyCompany.Programs namespace.

一個沒有顯式聲明的命名空間中的單元稱爲常規單元。一個常規單元自動變爲項目的默認命名空間的成員。在程序前面給出聲明，下列單元聲明會致使編譯器把MyUnit做爲MyCompany.Programs命名空間的成員。

unit MyUnit;

 

The project default namespace does not affect the name of the Delphi source file for a generic unit. In the preceding example, the Delphi source file name would be MyUnit.pas. The same rule applies for the dcu file name. The resulting dcu file in the current example would be MyUnit.dcu.

項目的默認命名空間不影響對一個常規單元的Delphi源文件的名稱。在前面的例子中，Delphi源文件的名稱將是MyUnit.pas。一樣的規則也適用於該DCU文件名。在當前的例子中所獲得的DCU文件將MyUnit.dcu。

 

Namespace strings are not case-sensitive. The compiler considers two namespaces that differ only in case to be equivalent. However, the compiler does preserve the case of a namespace, and will use the preserved casing in output file names, error messages, and RTTI unit identifiers. RTTI for class and type names will include the full namespace specification.

命名空間的字符串是不區分大小寫的。編譯器認爲兩個只有大小寫不一樣的命名空間是等價的。可是，編譯器會在這種狀況下保留命名空間，而且將在輸出文件名，錯誤信息，和RTTI單元標識符中保存。RTTI的類和類型名稱將包含完整命名空間。

 

 

1         Searching Namespaces

2       搜索命名空間

 

A unit must declare the other units on which it depends. The compiler must search these units for identifiers. For units in explicit namespaces the search scope is already known, but for generic units, the compiler must establish a namespace search scope.

單元必須聲明它所依賴的其它單元。編譯器必須經過標識符搜索這些單元。對於明確命名空間的單元，搜索空間是已知的，但對於常規單元，編譯器必須創建一個命名空間搜索範圍。

 

Consider the following unit and uses declarations:

考慮下面的單元並使用聲明：

unit MyCompany.ProjectX.ProgramY.MyUnit1;

uses MyCompany.Libs.Unit2, Unit3, Unit4;

These declarations establish MyUnit1 as a member of the MyCompany.ProjectX.ProgramY namespace. MyUnit1 depends on three other units: MyCompany.Libs.Unit2, and the generic units, Unit3, and Unit4. The compiler can resolve identifier names in Unit2, since the uses clause specified the fully qualified unit name. To resolve identifier names in Unit3 and Unit4, the compiler must establish a namespace search order.

這個聲明創建MyUnit1做爲MyCompany.ProjectX.ProgramY命名空間的一個成員。MyUnit1依賴於3個其它單元：MyCompany.Libs.Unit2和常規單元Unit三、Unit4。編譯器能夠解析Unit2，由於uses子句指定了徹底限制的單元名稱。要解析Unit三、Unit4的單元名稱，編譯器必須創建一個命名空間搜索順序。

 

1.1    Namespace search order

2.1 命名空間搜索順序

 

Search locations can come from three possible sources: compiler options, the project default namespace, and the current unit's namespace.

搜索位置能夠來自三個可能的來源：編譯器選項，項目默認的命名空間，和當前單元的命名空間。

 

The compiler resolves identifier names in the following order:

編譯器將按如下順序解析標識符名稱：

1. The current unit namespace (if any)

當前單元命名空間（若是有的話）

1. The project default namespace (if any)

項目的默認命名空間（若是有的話）

1. Namespaces specified by compiler options.

由編譯器選項指定的命名空間。

 

2.2 A namespace search example

2.2 一個命名空間搜索例子

The following example project and unit files demonstrate the namespace search order:

如下示例項目和單元文件證實命名空間搜索順序：

 

Given this program example, the compiler would search namespaces in the following order:

基於這個程序的例子，編譯器會按以下順序搜索命名空間：

1. MyCompany.ProjectX.ProgramY

2. MyCompany.ProjectX

3. Namespaces specified by compiler options. 由編譯器選項指定的命名空間。

 

Note that if the current unit is generic (i.e. it does not have an explicit namespace declaration in its unit statement), then resolution begins with the project default namespace.

請注意，若是當前單元是常規的（即它沒有一個明確的命名空間聲明在其單元語句中），那麼開始解析項目默認命名空間。

 

2         Using Namespaces

3       使用命名空間

 

Delphi's uses clause brings a module into the context of the current unit. The uses clause must either refer to a module by its fully qualified name (i.e. including the full namespace specification), or by its generic name, thereby relying on the namespace resolution mechanisms to locate the unit.

Delphi的uses子句帶來一個模塊到當前單元的上下文。 uses子句必須引用它的全限定名（即包括完整的命名空間規範），或由它的常規名稱，從而依靠命名空間解析機制來定位單元要指定的模塊。

 

3.1 Fully qualified unit names

3.1徹底合規的單元名稱

 

The following example demonstrates the uses clause with namespaces:

下面示例演示了使用uses子句和命名空間：

 

unit MyCompany.Libs.MyUnit1；

uses MyCompany.Libs.Unit2,  // Fully qualified name.徹底合規的單元名稱

  UnitX;                   // Generic name.常規名稱

Once a module has been brought into context, source code can refer to identifiers within that module either by the unqualified name, or by the fully qualified name (if necessary, to disambiguate identifiers with the same name in different units). The following Writeln statements are equivalent:

一旦模塊被引入上下文，源代碼根據非限定名稱，或者徹底合規的單元名稱去識別模塊內的標識符（若是有必要，要對不一樣單元內的相同名稱去消除岐義）。下面Writeln語句是等價的：

 

uses MyCompany.Libs.Unit2;

 

begin

  Writeln(MyCompany.Libs.Unit2.SomeString);

  Writeln(SomeString);

end.

A fully qualified identifier must include the full namespace specification. In the preceding example, it would be an error to refer to SomeString using only a portion of the namespace:

一個徹底合格的標識符必須包括完整的命名空間規範。在前面的例子中，使用命名空間中一部分去引用SomeString將會形成錯誤：

Writeln(Unit2.SomeString);       // ERROR錯誤!

Writeln(Libs.Unit2.SomeString);  // ERROR錯誤!

Writeln(MyCompany.Libs.Unit2.SomeString);      // Correct正確.

Writeln(SomeString);                           // Correct正確.

It is also an error to refer to only a portion of a namespace in the uses clause. There is no mechanism to import all units and symbols in a namespace. The following code does not import all units and symbols in the MyCompany namespace:

在uses子句中只使用命名空間部分也是一個錯誤。沒有任何機制命名空間中導入全部單元和符號。下面的代碼不會在MyCompany的命名空間中導入全部單元和符號：

uses MyCompany;   // ERROR錯誤!

This restriction also applies to the with-do statement. The following will produce a compiler error:

這些限制也能夠應用於with-do語句。下面過程也將產生一個編譯錯誤：

with MyCompany.Libs do    // ERROR錯誤!

 

3.2 Multi-unit Namespaces

3.2 多單元命名空間

 

Multiple units can belong to the same namespace, if the unit declarations refer to the same namespace. For example, one can create two files, unit1.pas and unit2.pas, with the following unit declarations:

多個units單元能夠同屬於相同的命名空間，若是unit單元聲明引入相同的命名空間。例如，共同建立兩個文件，unit1.pas 和 unit2.pas，會有如下的unit聲明：

// in file 'unit1.pas'

unit MyCompany.ProjectX.ProgramY.Unit1;

 

// in file 'unit2.pas'

unit MyCompany.ProjectX.ProgramY.Unit2;

In this example, the namespace MyCompany.ProjectX.ProgramY logically contains all of the interface symbols from unit1.pas and unit2.pas.

在這個例子中，命名空間MyCompany.ProjectX.ProgramY邏輯上包含全部的unit1.pas和unit2.pas接口符號。

 

Symbol names in a namespace must be unique, across all units in the namespace. In the example above, it is an error for Unit1 and Unit2 to both define a global interface symbol named mySymbol.

在全部命名空間中的單元的命名空間中的名稱必須是惟一的。在上面的例子中，它爲unit1和unit2定義一個名爲mySymbol一個全局性的接口符號是錯誤的。

 

The individual units aggregated in a namespace are not available to source code unless the individual units are explicitly used in the file's uses clause. In other words, if a source file uses only the namespace, then fully qualified identifier expressions referring to a symbol in a unit in that namespace must use the namespace name, not just the name of the unit that defines that symbol.

除非文件uses子句中顯式的使用獨立單元，彙集在一個命名空間中的個別單位不提供源代碼。換句話說，若是一個源文件使用惟一的命名空間，則徹底限定標識符表達式在unit單元中引用一個符號，必須使用命名空間的名稱。而不是隻使用單元符號。

 

A uses clause may refer to a namespace as well as individual units within that namespace. In this case, a fully qualified expression referring to a symbol from a specific unit listed in the uses clause may be referred to using the actual unit name or the fully-qualified name (including namespace and unit name) for the qualifier. The two forms of reference are identical and refer to the same symbol.

Uses子句能夠引用一個命名空間，以及在命名空間中的獨立單元。在這種狀況下，一個徹底合規的標識符指的是從uses子句中列出的特定單元標識符。能夠是實際使用的單元名稱或徹底限定名（包括命名空間和單元名稱）的限定符。這兩種形式的參考是相同的，而且指代相同的符號。

 

Note: Explicitly using a unit in the uses clause will only work when you are compiling from source or dcu files. If the namespace units are compiled into an assembly and the assembly is referenced by the project instead of the individual units, then the source code that explicitly refers to a unit in the namespace will fail.

注：顯式在uses子句使用單元將只能在你要編譯的源代碼或DCU文件工做。若是命名空間單元被編譯成一個組件和組件的項目，而不是個別單元引用，那麼源代碼在命名空間中顯示引用一個單元將失敗。