Application及Document

Revit 平台 API 中的顶级对象是Application和Document。这些类由 Application、UIApplication、Document 和 UIDocument 类表示。

Application对象是指单个 Revit 任务，提供对文档、选项和其他应用程序范围的数据和设置的访问。

Autodesk.Revit.UI.UIApplication - 提供对应用程序的 UI 级界面的访问，包括将 RibbonPanel 添加到用户界面的功能，以及在用户界面中获取活动文档的功能。

Autodesk.Revit.ApplicationServices.Application - 提供对所有其他应用程序级别属性的访问。

Document是表示建筑模型的单个 Revit 项目文件。Revit 可以打开多个项目，并为一个项目打开多个视图。

Autodesk.Revit.UI.UIDocument - 提供对文档的 UI 级界面的访问，例如选择的内容以及提示用户进行选择和选取点的功能。

Autodesk.Revit.DB.Document - 提供对所有其他文档级别属性的访问。

如果打开了多个文档，则活动文档是其视图在 Revit 任务中处于活动状态的文档。

本章介绍了所有Application和Document，然后重点介绍文件管理、设置和单位。有关 Element 类的更多详细信息，请参阅 Elements Essentials和 编辑元素 ，并参阅 视图 以了解有关视图元素的更多详细信息。

Applicaion功能

Application和 UIApplication 成员提供对应用程序范围的数据和设置以及 Revit 的活动会话的访问。

Application 应用

该类表示 Autodesk Revit 应用程序，提供对文档、选项和其他应用程序范围的数据和设置的访问。

应用程序版本信息

应用程序属性包括 VersionBuild、VersionNumber 和 VersionName。这些属性可用于根据 Revit 的发布和内部版本提供附加模块行为，如如何使用应用程序属性为附加模块强制实施正确的版本所示。

应用程序范围的设置

Revit 一次使用一个共享参数文件。Application.OpenSharedParameterFile() 方法访问其路径在 SharedParametersFilename 属性中设置的共享参数文件。有关更多详细信息，请参阅共享参数。

库内容

GetLibraryPaths() 和 SetLibraryPaths() 方法提供对路径信息的访问，用于标识 Revit 搜索内容的位置。

图形显示

BackgroundColor 属性允许读取和写入此会话中用于模型视图的背景颜色。AllowNavigationDuringRedraw 属性启用或禁用允许在重绘期间进行视图操作的选项。这可用于在重绘模型期间优化性能。

文档管理

Application 类提供了用于创建以下类型文档的方法：

  • Family document 族文件
  • Project document 项目文档
  • Project template 项目模板

OpenDocumentFile() 方法可用于打开这些文档类型中的任何一种。所有打开的文档都可以使用 Documents 属性进行检索。
有关更多详细信息，请参阅文档和文件管理。

会话信息

UserName 等属性和GetRevitServerNetworkHosts() 等方法提供对此会话特定信息的只读访问。

登录信息

静态 IsLoggedIn 属性检查用户是否已从此会话登录到其 Autodesk A360 帐户。如果用户已登录，则 LoginUserId 属性将返回当前登录的用户的用户 ID。（如果用户未登录，则用户 ID 将为空。与上一节中的 UserName 不同，LoginUserId 值不是可识别的值，而是内部 ID。结合 Store Entitlement REST API，Autodesk 应用程序的发布者可以验证当前用户是否已从 Autodesk App Store 购买了其应用程序。有关 Store Entitlement API 的更多信息，请参阅 www.autodesk.com/developapps。

共享参数管理

事件

Application 类公开 document 和 application 事件，例如 document open 和 save。订阅这些事件会在启用事件时通知应用程序并采取相应的措施。有关更多详细信息，请参阅 Add-In Integration 部分中的事件。

创造

“Create ”属性返回一个对象工厂，该对象工厂用于在 Revit 平台 API 中创建应用程序范围的实用程序和几何对象。如果要在 Revit Revit application memory （而不是your application’s memory）中创建对象，则使用“Create ”。

失败发布和处理

包含所有已注册的 FailureDefinitions 的 FailureDefinitionRegistry 可从静态 GetFailureDefinitionRegistry () 方法获得。静态方法 RegisterFailuresProcessor() 可用于注册自定义 IFailuresProcessor。有关发布和处理失败的更多信息，请参阅失败发布和处理。

断开连接警告

以下属性控制是否显示各种类型断开连接的图形警告。

  • ShowGraphicalWarningCableTrayConduitDisconnects
  • ShowGraphicalWarningDuctDisconnects
  • ShowGraphicalWarningElectricalDisconnects
  • ShowGraphicalWarningHangerDisconnects

UIApplication

此类表示 Autodesk Revit 用户界面的活动会话，提供对 UI 自定义方法、事件和活动文档的访问。
文档管理

UIApplication 使用 UIActiveDocument 属性提供对活动文档的访问。此外，可以使用重载的 OpenAndActivateDocument() 方法打开 Revit 文档。文档将在默认视图处于活动状态的情况下打开。此方法不能在事务中调用，并且只能在事件期间调用 Revit 中尚未打开活动文档，并且该事件未嵌套在其他事件中。

插件管理

ActiveAddInId 属性获取当前活动的外部应用程序或外部命令 ID，而 LoadedApplications 属性返回成功加载的外部应用程序的数组。

功能区面板实用程序

使用 UIApplication 对象将新的功能区面板和控件添加到 Revit。
有关更多详细信息，请参阅“加载项集成”部分中的 Ribbon 面板和控件。

范围

DrawingAreaExtents 属性返回一个矩形，该矩形表示绘图区域的屏幕像素坐标，而 MainWindowExtents 属性返回一个矩形，该矩形表示 Revit 主窗口的屏幕像素坐标

事件

UIApplication 类公开与 UI 相关的事件，例如显示对话框时。订阅这些事件会在启用事件时通知应用程序并采取相应的措施。有关更多详细信息，请参阅 Add-In Integration 部分中的事件。

学科控制

The properties:

  • Application.IsArchitectureEnabled
  • Application.IsStructureEnabled
  • Application.IsStructuralAnalysisEnabled
  • Application.IsMassingEnabled
  • Application.IsEnergyAnalysisEnabled
  • Application.IsSystemsEnabled
  • Application.IsMechanicalEnabled
  • Application.IsMechanicalAnalysisEnabled
  • Application.IsElectricalEnabled
  • Application.IsElectricalAnalysisEnabled
  • Application.IsPipingEnabled
  • Application.IsPipingAnalysisEnabled

提供对可用学科的 READ 和 MODIFY 访问权限。应用程序可以读取属性以确定何时启用或禁用其 UI 的各个方面。

切换领域状态时，Revit 的 UI 将进行调整，并且将根据需要启用或禁用某些操作和功能。启用分析模式仅在启用相应专业时生效。例如，除非还启用了机械专业，否则启用 Mechanical Analysis 不会生效。

如何使用Application属性为外接程序强制实施正确的版本

有时，由于存在特定的修复或兼容的 API，您需要仅在存在特定的 Revit Update Release 的情况下运行附加模块。

使用“Application”的属性可以检查 Revit 的特定版本。属性 VersionNumber 将返回表示主版本号的字符串，而 VersionBuild 属性将返回 Autodesk Revit 应用程序的内部内部版本号。

另一个有用的属性是 Application.SubVersionNumber 属性。它返回一个字符串，该字符串表示 Revit 应用程序的主要-次要版本号，例如“2018.0.0”。Autodesk 会针对所有主要和次要更新更新更新此字符串。小版本（如 2018.1.0）可能具有初始客户版本（如 2018.0.0）中未提供的其他 API 和功能。为支持初始版本而编写的加载项可能与订阅更新兼容，但在订阅更新中使用新功能的加载项将与初始版本不兼容。

以下示例代码演示了一种技术，用于确定 Revit 版本是否为初始已知 Revit 版本之后的任何 Update Release。

代码区域：使用 VersionBuild 确定您的外接程序是否兼容

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public void GetVersionInfo(Autodesk.Revit.ApplicationServices.Application app)
{ 
   // 20110309_2315 is the datecode of the initial release of Revit 2012 
   if (app.VersionNumber == "2012" && 
       String.Compare(app.VersionBuild, "20110309_2315") > 0)
   {
       TaskDialog.Show("Supported version", 
                      "This application supported in this version.");
   }
   else
   {
       TaskDialog dialog = new TaskDialog("Unsupported version.");
       dialog.MainIcon = TaskDialogIcon.TaskDialogIconWarning;
       dialog.MainInstruction = "This Revit 2012 application is supported in UR1 and later releases.";
       dialog.Show();
   }
}

Document功能

Document存储 Revit 图元、管理数据并更新多个数据视图。Document 类主要提供以下功能。

Document

Document 类表示打开的 Autodesk Revit 项目。

Settings 属性

Settings 属性返回一个对象，该对象提供对 Revit 项目中常规组件的访问。有关更多详细信息，请参阅设置。

地点和位置

每个项目只有一个场地位置，用于标识 Earth 上的物理项目位置。一个工程可以有多个工程位置。每个位置都是站点位置的偏移或旋转。有关更多详细信息，请参阅地点和位置。

视图管理

一个项目文档可以有多个视图。ActiveView 属性返回表示活动视图的 View 对象。您可以过滤项目中的图元以检索其他视图。有关更多详细信息，请参阅 视图。

元素检索

Document 对象将元素存储在项目中。使用 Element 属性按 ElementId 或 UniqueId 检索特定元素。
有关更多详细信息，请参阅 Elements Essential。

文件管理

每个 Document 对象都代表一个 Revit 项目文件。Document 提供如下功能：
检索文件信息，例如文件路径名和项目标题。
提供 Close() 和 Save() 方法来关闭和保存文档。
有关更多详细信息，请参阅文档和文件管理。

元素管理

Revit 会保留项目中的所有图元对象。要创建新图元，请使用“Create”属性，该属性返回用于在 Revit 平台 API 中创建新项目图元实例（如 FamilyInstance 或 Group）的对象工厂。
Document 类还可用于删除元素。使用 Delete() 方法删除项目中的元素。已删除的元素和任何从属元素不会显示，并且会从文档中删除。对已删除元素的引用无效，并会导致异常。有关更多详细信息，请参阅编辑元素。

事件

某些操作会引发事件，例如当您使用 Save 或 Save As 保存项目时。要在应用程序中捕获事件并做出响应，必须注册事件处理程序。有关更多详细信息，请参阅 事件。

文档状态

多个属性提供有关文档状态的信息：

  • IsModifiable - 当前是否可以修改文档（这意味着文档中有一个活动事务，并且更改不会被其他任何内容暂时阻止）
  • IsModified - 文档在打开或保存后是否发生更改
  • IsReadOnly - 如果为 true，则文档当前为只读且无法修改
  • IsReadOnlyFile - 文档是否以只读模式打开
  • IsFamilyDocument - 文档是否为家庭文档
  • IsWorkshared - 是否已在文档中启用工作集

其他

Document 还提供其他功能：

  • ParameterBindings 属性 - 参数定义和类别之间的映射。有关更多详细信息，请参阅共享参数。
  • ReactionsAreUpToDate 属性 - 报告反作用载荷是否发生变化。有关更多详细信息，请参阅负载。
  • Default Types - 访问族和非族元素的默认类型。有关更多详细信息，请参阅默认类型。

UIDocument

UIDocument 类表示在 Revit 用户界面中打开的 Autodesk Revit 项目。

元素检索

使用 UIDocument 中的 Selection 属性检索所选元素。此属性返回一个对象，该对象表示包含所选项目元素的活动选择。它还提供了 UI 交互方法，用于在 Revit 模型中拾取对象。有关更多详细信息，请参阅 Elements Essentials。

元素显示

ShowElements() 方法使用来关注多个元素。

视图管理

通过调用 RefreshActiveView() 方法，可以使用 UIDocument 类来刷新活动文档中的活动视图。ActiveView 属性可用于检索或设置文档的活动视图。更改活动视图有一些限制。它只能在活动文档中使用，该文档不得处于只读状态，也不得位于事务中。此外，在 ViewActivating 或 ViewActivated 事件期间，或任何操作前事件 （如 DocumentSaving、DocumentClosing 或其他类似事件） 期间，不得更改活动视图。

UIDocument.ActiveGraphicalView 属性检索文档的活动图形视图。与 UIDocument.ActiveView 不同，如果用户碰巧在其中一个视图中进行选择，则此属性将永远不会返回辅助视图（如 Project Browser 或 System Browser）。

UIDocument 还可用于获取 Revit 用户界面中所有打开的视图窗口的列表。GetOpenUIViews 方法返回一个 UIViews 列表，其中包含有关 Revit 用户界面中视图窗口的数据。

Default Types 默认类型

Revit 具有不同类别的默认类型。调用相关工具创建此类别的图元时，此默认类型将显示在 Revit 用户界面中。Revit API 通过 Document 类公开族和非族类型的默认类型。

族类型

方法 描述
GetDefaultFamilyTypeId() 获取与给定族类别 ID 关联的默认系列类型 ID。
SetDefaultFamilyTypeId() 设置与给定族类别 ID 关联的默认族类型 ID。
IsDefaultFamilyTypeIdValid() 检查族类型 ID 是否有效，可设置为给定族类别 ID 的默认值。

此外，给定 ElementType，ElementType.IsValidDefaultFamilyType() 标识它是否是给定族类别 ID 的有效默认族类型。 以下示例演示了如何获取结构柱类别的默认族类型 ID。然后，它获取默认类型的族符号并将其分配给给定的柱。

1
2
3
4
5
6
7
8
9
10
11
12
13
private void AssignDefaultTypeToColumn(Document document, FamilyInstance column)
{
    ElementId defaultTypeId = document.GetDefaultFamilyTypeId(new ElementId(BuiltInCategory.OST_StructuralColumns));

    if (defaultTypeId != ElementId.InvalidElementId)
    {
        FamilySymbol defaultType = document.GetElement(defaultTypeId) as FamilySymbol;
        if (defaultType != null)
        {
            column.Symbol = defaultType;
        }
    }
}

下一个示例在首先检查给定门是否为有效的默认族类型 ID 后，为给定门的门类别设置默认类型。

代码区域：设置默认族类型 ID

1
2
3
4
5
6
7
8
9
10
11
12
private void SetDefaultTypeFromDoor(Document document, FamilyInstance door)
{
    ElementId doorCategoryId = new ElementId(BuiltInCategory.OST_Doors);

    // It is necessary to test the type suitability to be a default family type, for not every type can be set as default. 
    // Trying to set a non-qualifying default type will cause an exception
    if (door.Symbol.IsValidDefaultFamilyType(doorCategoryId))
    {
        document.SetDefaultFamilyTypeId(doorCategoryId, door.Symbol.Id);
    }

}

非族类型

下表中的文档成员提供对非 Family 元素类型的默认类型的访问。

方法 描述
GetDefaultElementTypeId() 获取给定非 Family 元素类型的默认元素类型 ID。
SetDefaultElementTypeId() 为给定的非 Family 元素类型设置默认元素类型 ID。
IsDefaultElementTypeIdValid() 检查元素类型 ID 是否对给定的非 Family 元素类型有效。

下面的示例检查给定的墙壁是否使用墙壁类型的默认元素类型。

代码区域：获取默认元素类型 ID

1
2
3
4
5
private bool IsWallUsingDefaultType(Document document, Wall wall)
{
    ElementId defaultElementTypeId = document.GetDefaultElementTypeId(ElementTypeGroup.WallType);
    return (wall.WallType.Id == defaultElementTypeId);
}

文档和文件管理

文档和文件管理使创建和查找文档变得容易。

文档检索

Application 类维护所有文档。如前所述，您可以在一个会话中打开多个文档。使用 UIApplication 类属性 ActiveUIDocument 检索活动文档。所有打开的文档（包括活动文档）都使用 Application 类 Documents 属性进行检索。该属性返回一个包含 Revit 任务中所有打开的文档的集。

文档文件信息

Document 类为每个相应的文件提供两个属性，即 PathName 和 Title。

PathName 返回文档的完全限定文件路径。如果项目自创建以来尚未保存，则 PathName 将返回空字符串。

Title 是项目标题，通常从项目文件名派生而来。返回值因您的系统设置而异。

打开文档

Application 类提供了一个重载的方法来打开现有项目文件：

表 3：在 API 中打开文档

Method 方法 Event 事件
Document OpenDocumentFile(string filename )
Document OpenDocumentFile(ModelPath modelPath, OpenOptions openOptions)		 DocumentOpened 文档已打开

指定具有完全限定文件路径的字符串时，Revit 将打开该文件并创建一个 Document 实例。使用此方法可以通过为此方法分配文件通用命名转换 （UNC） 名称，在其他计算机上打开文件。该文件可以是扩展名为 .rvt 的项目文件、扩展名为 .rfa 的族文件或扩展名为 .rte 的样板文件。第二个重载将模型的路径作为 ModelPath 而不是字符串，并且 OpenOptions 参数提供用于打开文件的选项，例如从中心分离打开的文档（如果适用）的功能，以及与工作共享相关的选项。有关打开工作共享文档的更多信息，请参阅打开工作共享文档。这些方法在发生故障时引发特定的记录异常。例外情况分为 4 大类。

表 4：引发的异常类型

Type 类型 Example 例
Disk errors 磁盘错误 文件不存在或版本错误
Resource errors 资源错误 没有足够的内存或磁盘空间来打开文件
Central model file errors 中心模型文件错误 文件已锁定或损坏
Central model/server errors 中心模型/服务器错误 与服务器发生网络通信错误

如果文档打开成功，则会引发 DocumentOpened 事件。

创建文档

使用下表中的 Application 方法创建新文档。
表 5：在 API 中创建文档

Method 方法 Event 事件
Document NewProjectDocument(string templateFileName); DocumentCreated
Document NewProjectDocument(UnitSystem unitSystem); DocumentCreated
Document NewFamilyDocument(string templateFileName); DocumentCreated
Document NewProjectTemplateDocument(string templateFilename); DocumentCreated

对于需要模板文件名作为参数的方法，将基于模板文件返回创建的文档。NewProjectDocument（UnitSystem）将创建一个没有指定模板的新英制或公制项目文档。

保存并关闭文档 Document 类提供了保存或关闭实例的方法。

表 6：在 API 中保存和关闭文档

Method 方法 Event 事件
Save() 保存 DocumentSaved 文档已保存
SaveAs() 保存为 DocumentSavedAs
Close() 关闭 DocumentClosed 文档已关闭

Save() 有 2 个重载，一个没有参数，另一个带有 SaveOptions 参数，可以指定是否强制操作系统从磁盘上的文件中删除所有死数据。如果之前未保存该文件，则必须改为调用 SaveAs()。

SaveAs() 有 3 个重载。一个重载仅将文件名作为参数，如果存在另一个具有给定文件名的文件，则会引发异常。其他 2 个重载将文件名作为参数（在一种情况下以 ModelPath 的形式）以及第二个 SaveAsOptions 参数，该参数可用于指定是否覆盖现有文件（如果存在）。SaveAsOptions 还可用于指定其他相关选项，例如是否删除磁盘上与文件相关的死数据和工作共享选项。 Save() 和 SaveAs() 在与打开文档时相同的 4 个类别中引发特定的记录异常，如上面的表 4 所示。

Close() 有两个重载。一个参数采用 Boolean 参数，该参数指示是否在关闭文件之前保存文件。第二个重载不带任何参数，如果文档被修改，系统会询问用户是否要在关闭之前保存文件。如果尚未设置文档的路径名，或者保存的目标文件是只读的，则此方法将引发异常。

注： Close() 方法不会影响活动文档或引发 DocumentClosed 事件，因为该文档由外部应用程序使用。您只能对非活动文档调用此方法。UIDocument 类还提供了保存和关闭实例的方法。

表 7：在 API 中保存和关闭 UIDocument

Method 方法 Event 事件
SaveAndClose() DocumentSaved, DocumentClosed
SaveAs() 保存为 DocumentSavedAs

SaveAndClose() 在保存文档后关闭文档。如果尚未设置文档的路径名称，则向 Revit 用户显示“另存为”对话框，以设置其名称和位置。 SaveAs() 方法将文档保存为通过“另存为”对话框从 Revit 用户处获取的文件名和路径。

文档预览

可以从 Document 获取 DocumentPreviewSettings 类，该类包含与保存给定文档的预览图像相关的设置。

代码区域：文档预览

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
public void SaveActiveViewWithPreview(UIApplication application)
{
    // Get the handle of current document.
    Autodesk.Revit.DB.Document document = application.ActiveUIDocument.Document;

    // Get the document's preview settings
    DocumentPreviewSettings settings = document.GetDocumentPreviewSettings();
    
    // Find a candidate 3D view
    FilteredElementCollector collector = new FilteredElementCollector(document);
    collector.OfClass(typeof(View3D));
    
    Func<View3D, bool> isValidForPreview = v => settings.IsViewIdValidForPreview(v.Id);
    
    View3D viewForPreview = collector.OfType().First(isValidForPreview);
    
    // Set the preview settings
    using (Transaction setTransaction = new Transaction(document, "Set preview view id"))
    {
        setTransaction.Start();
        settings.PreviewViewId = viewForPreview.Id;
        setTransaction.Commit();
    }
    
    // Save the document
    document.Save();

}

荷载族

Document 类使您能够将整个族及其所有符号加载到项目中。由于加载整个族可能需要很长时间和大量内存，因此 Document 类提供了类似的方法 LoadFamilySymbol() 来仅加载指定的符号。有关更多详细信息，请参阅 族。

设置

下表标识了 Revit Platform UI“管理”选项卡中的命令以及相应的 API。

表 7：API 和 UI 中的设置

UI 命令 关联 API 参考
设置 img 项目信息 Document.ProjectInformation 请参阅以下注释
设置 img 项目参数 Document.ParameterBindings (Only for Shared Parameter) 请参阅共享参数
“项目位置”面板 Document.ProjectLocations 查看地点和位置
设置 img 其他设置 img 填充图案 FilteredElementCollector filtering on class FillPatternElement 请参阅以下注释
设置 img 材质 FilteredElementCollector filtering on class Material 请参阅物料管理
设置 img 对象样式 Document.Settings.Categories 请参阅以下注释
阶段划分 img 阶段 Document.Phases 请参阅以下注释
设置 img 结构设置 Loads and related structural settings are available in the API 参见 Structural Engineering
设置 img 项目单位 Document.GetUnits() 见单位
面积和体积计算（在房间和面积面板上） AreaVolumeSettings.GetAreaVolumeSettings() 请参阅以下注释

注意：项目信息 - API 提供 ProjectInfo 类，该类使用 Document.ProjectInformation 检索，以表示 Revit 项目中的项目信息。下表标识了 Project Information 参数的相应 API。

表 8：项目信息

参数 对应 API 内置参数
Project Issue Date 项目发布日期 ProjectInfo.IssueDate PROJECT_ISSUE_DATE
Project Status 项目进展 ProjectInfo.Status PROJECT_STATUS
Client Name 客户端名称 ProjectInfo.ClientName CLIENT_NAME
Project Address 项目地址 ProjectInfo.Address PROJECT_ADDRESS
Project Name 项目名称 ProjectInfo.Name PROJECT_NAME
Project Number 项目编号 ProjectInfo.Number PROJECT_NUMBER

使用 ProjectInfo 公开的属性来检索和设置所有字符串。这些属性由相应的内置参数实现。您可以直接通过内置参数获取或设置值。有关如何通过内置参数访问这些参数的更多信息，请参阅“Elements Essentials”部分中的参数。获取项目信息的推荐方法是使用 ProjectInfo 属性。

Fill Patterns

使用对类 FillPatternElement 的 FilteredElementCollector 过滤来检索当前文档中的所有填充图案。可以使用静态方法 FillPatternElement.GetFillPattern（Document， ElementId） 或 FillPatternElement.GetFillPatternByName （Document， string） 来检索特定的 FillPattern。

Object Styles

使用 Settings.Categories 检索 Category 对象中除 Line Style 之外的所有信息。有关更多详细信息，请参阅 Elements Essentials和 Material 部分中的 Other Classifications。

Phases

Revit 按阶段维护图元生命周期，阶段是项目生命周期中的不同时间段。文档中的所有阶段都使用 Document.Phases 属性进行检索。该属性返回一个包含 Phase 类实例的数组。但是，Revit API 不会公开 Phase 类中的函数。

Options

“Options”命令用于配置项目全局设置。您可以使用 Application.Options 属性检索 Options.Application 实例。目前，Options.Application 类仅支持访问库路径和共享参数文件。

Area and Volume Calculations

AreaVolumeSettings 类允许您启用或禁用体积计算，以及更改房间边界位置。

单位

Revit API 中用于处理单位的两个主要类是 Units 和 FormatOptions。Units 类表示文档的默认设置，用于将带有单位的数字格式设置为字符串。它包含每个单位类型的 FormatOptions 对象以及与小数符号和数字分组相关的设置。

Units 类为每个有效的 Unit 类型存储一个 FormatOptions 对象，但并非所有 Unit 类型都可以直接修改。有些 （如 UT_Number 和 UT_SiteAngle）具有固定的定义。其他单位的定义是从其他单位类型自动派生的。例如，UT_SheetLength 派生自 UT_Length UT_ForceScale 派生自 UT_Force。

FormatOptions 类包含一些设置，这些设置控制如何将带有单位的数字格式设置为字符串。它包含通常由最终用户在“格式”对话框中选择并存储在文档中的设置，例如舍入、准确性、显示单位以及是否禁止空格或前导零或尾随零。

FormatOptions 类以两种不同的方式使用。Units 类中的 FormatOptions 对象表示文档的默认设置。在其他位置使用的 FormatOptions 对象表示可以选择性地覆盖默认设置的设置。

UseDefault 属性控制 FormatOptions 对象是表示默认格式还是自定义格式。如果 UseDefault 为 true，则格式设置将根据 Units 类中的默认设置进行，并且对象中的其他设置都没有意义的。如果 UseDefault 为 false，则对象包含替代 Units 类中的默认设置的自定义设置。对于 Units 类中的 FormatOptions 对象，UseDefault 始终为 false。

Revit API 中与单元相关的重要枚举包括：

  • UnitType - 要测量的物理量类型，例如长度或力（UT_Length 或 UT_Force）
  • DisplayUnitType - 用于将数字格式化为字符串或转换单位（即 DUT_METERS）的单位和显示格式
  • UnitSymbolType - 以数字的格式化字符串表示形式显示的单位符号，以指示值的单位（即 UST_M）

单位换算
Revit API 提供了实用程序类，以便于在 Revit 中处理数量。使用 UnitUtils 类，可以轻松地将单位数据与 Revit 的内部单位相互转换。
Revit 有七个基本单位，每个基本单位都有自己的内部单位。下表列出了这些内部单位。

表 9：Revit Unit System 中的 7 个基本单元

基本单位 Revit 中的单位 单位制
Length 长度 Feet (ft) 英尺（英尺） Imperial 英制
Angle 角度 Radian 弧度 Metric 公制
Mass 质量 Kilogram (kg) 千克 （kg） Metric 公制
Time 时间 Seconds (s) 秒 （s） Metric 公制
Electric Current 电流 Ampere (A) 安培 （A） Metric 公制
Temperature 温度 Kelvin (K) 开尔文 （K） Metric 公制
Luminous Intensity 发光强度 Candela (cd) 坎德拉 （cd） Metric 公制

注意：由于 Revit 以英尺为单位存储长度，以公制单位存储其他基本量，因此涉及长度的派生单位将是基于英制和公制的非标准单位。例如，由于力是以“每时间平方的质量长度”来测量的，因此它以 kg-ft / s2 为单位存储。以下示例使用 UnitUtils.ConvertFromInternalUnits() 方法获取材料的最小屈服应力（以 kips/平方英寸为单位）。

代码区域：从 Revit 的内部单位转换

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
double GetYieldStressInKsi(Material material)
{
    double dMinYieldStress = 0;
    // Get the structural asset for the material
    ElementId strucAssetId = material.StructuralAssetId;
    if (strucAssetId != ElementId.InvalidElementId)
    {
        PropertySetElement pse = material.Document.GetElement(strucAssetId) as PropertySetElement;
        if (pse != null)
        {
            StructuralAsset asset = pse.GetStructuralAsset();

            // Get the min yield stress and convert to ksi
            dMinYieldStress = asset.MinimumYieldStress;
            dMinYieldStress = UnitUtils.ConvertFromInternalUnits(dMinYieldStress,
                DisplayUnitType.DUT_KIPS_PER_SQUARE_INCH);
        }
    }    
    return dMinYieldStress;
}

UnitUtils 还可用于将值从一种单位类型转换为另一种单位类型，例如平方英尺到平方米。在以下示例中，以英寸为单位输入的墙的顶部偏移值将转换为英尺，这是设置该值的预期单位。

代码区域：在单位之间转换

1
2
3
4
5
6
7
8
9
10
11
void SetTopOffset(Wall wall, double dOffsetInches)
{
    // convert user-defined offset value to feet from inches prior to setting
    double dOffsetFeet = UnitUtils.Convert(dOffsetInches,
                                            DisplayUnitType.DUT_DECIMAL_INCHES,
                                            DisplayUnitType.DUT_DECIMAL_FEET);

    Parameter paramTopOffset = wall.get_Parameter(BuiltInParameter.WALL_TOP_OFFSET);
    paramTopOffset.Set(dOffsetFeet);

}

单元格式设置和解析

另一个实用程序类 UnitFormatUtils 可以格式化数据或分析格式化单元数据。

重载方法 Format() 可用于根据格式设置选项将值格式化为字符串，如以下示例所示。检索材料密度，然后使用 Format() 方法将该值转换为用户友好的单位值。

代码区域：将值格式化为字符串

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
void DisplayDensityOfMaterial(Material material)
{
    double density = 0;
    // get structural asset of material in order to get the density
    ElementId strucAssetId = material.StructuralAssetId;
    if (strucAssetId != ElementId.InvalidElementId)
    {
        PropertySetElement pse = material.Document.GetElement(strucAssetId) as PropertySetElement;
        if (pse != null)
        {
            StructuralAsset asset = pse.GetStructuralAsset();

            density = asset.Density;
            // convert the density value to a user readable string that includes the units
            Units units = material.Document.GetUnits();
            // false for maxAccuracy means accuracy specified by the FormatOptions should be used
            // false for forEditing since this will be for display only and no formatting modifications are necessary
            string strDensity = UnitFormatUtils.Format(units, UnitType.UT_UnitWeight, density, false, false);
            string msg = string.Format("Raw Value: {0}\r\nFormatted Value: {1}", density, strDensity);
            TaskDialog.Show("Material Density", msg);
        }
    }

}

重载的 UnitFormatUtils.TryParse() 方法使用指定单位类型的 Revit 内部单位（如果可能）将格式化字符串（包括单位）解析为值。以下示例采用用户输入的长度值（假定为数字和长度单位），并尝试将其分析为长度值。出于演示目的，将结果与 TaskDialog 中的输入字符串进行比较。

代码区域：解析字符串

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
double GetLengthInput(Document document, String userInputLength)
{
    double dParsedLength = 0;
    Units units = document.GetUnits();
    // try to parse a user entered string (i.e. 100 mm, 1'6")
    bool parsed = UnitFormatUtils.TryParse(units, UnitType.UT_Length, userInputLength, out dParsedLength);
    if (parsed == true)
    {
        string msg = string.Format("User Input: {0}\r\nParsed value: {1}", userInputLength, dParsedLength);
        TaskDialog.Show("Parsed Data", msg);
    }

    return dParsedLength;

}

注：翻译自Revit API Developers Guide