元素要点

元素对应于单个建筑或绘图构件，例如门、墙或尺寸标注。此外，元素可以是门类型、视图或材质定义。

元素分类

Revit 图元分为六组：模型、草图、视图、组、注释和信息。每个组都包含相关的元素及其相应的符号。

模型元素

模型元素表示建筑项目中存在的物理项。“模型元素”组中的元素可以细分为以下元素：

族实例 - 族实例包含族实例对象。可以将族对象载入到项目中，也可以从族样板创建族对象。有关更多信息，请参阅系列实例。

主体图元 - 主体图元包含系统族对象，这些对象可以包含其他模型图元，例如墙、屋顶、天花板和楼板。有关主体图元的更多信息，请参见墙、楼板、屋顶和洞口。

结构元素-结构图元包含仅用于 Revit 结构特征的图元。有关 Structure Elements 的更多信息，请参见 Structural Engineering。

视图元素

视图图元表示在 Revit 中查看其他对象并与其他对象交互的方式。有关更多信息，请参阅视图。

组元素

组图元表示辅助图元，例如 Revit 中的“阵列”和“组”对象。有关详细信息，请参阅编辑元素。

注释和基准元素

注释和基准元素包含可见的非物理项。

注释元素表示在图纸上保持比例的二维构件，并且仅在一个视图中可见。有关注释元素的更多信息，请参阅注释元素。
注： 表示 2D 组件的注释元素不仅存在于 2D 视图中。例如，可以在 3D 视图中绘制尺寸，而它们所引用的形状仅存在于 2D 平面中。
基准元素表示用于建立项目上下文的非物理项。这些元素可以存在于视图中。基准元素进一步分为以下几部分：

  • 通用基准元素 - 通用基准元素表示用于存储建模数据的非物理可见项目。
  • 基准 FamilyInstance - 基准 FamilyInstance 表示加载到项目中或从族模板创建的非物理可见项目。注意有关常用基准元素和基准族实例的更多信息，请参阅基准和信息元素;有关 ModelCurve 相关内容，请参阅草绘。
  • 结构基准元素 - 结构基准元素表示用于存储结构建模数据的非物理可见项目。有关结构基准元素的详细信息，请参阅结构工程。

草图元素

草图元素表示用于草绘 2D/3D 形状的临时项目。此组包含族建模和体量分析中使用的以下对象：

SketchPlane 草图平面）

  • Sketch 素描
  • Path3D 路径3D
  • GenericForm. 泛型形式。

有关草图详细信息，请参阅草图绘制。

信息元素

信息元素包含用于存储项目和应用程序数据的非物理不可见项。信息元素进一步分为以下几部分：

  • Project Datum Elements 项目基准元素
  • Project Datum Elements (Unique).项目基准元素 （Unique）。

有关基准元素的更多信息，请参阅基准和信息元素。

其他分类

元素可以按Category, Family, Symbol and Instance.进行分类。

分类之间存在一些关系。例如：

您可以按类别区分不同类型的 FamilyInstances。结构柱等项目位于“结构柱”类别中，梁和支撑位于“结构框架”类别中，依此类推。
您可以通过Symbol来区分结构 FamilyInstance 元素。

Category 类别

Element.Category 属性表示 Element 所属的类别或子类别。它用于标识元素类型。例如，“墙”类别中的任何内容都被视为墙。其他类别包括门和房间。

Category 是最通用的类。 Document.Settings.Categories 属性是一个包含文档中所有 Category 对象的映射，并细分为以下对象：

  • 模型类别 - 模型类别包括梁、柱、门、窗和墙。
  • 注释类别 - 注释类别包括维度、网格、级别和文本注释。

https://help.autodesk.com/cloudhelp/2018/ENU/Revit-API/images/GUID-4C0CA7CF-C5CF-4042-B99D-AE185F64D17F-low.png

图 20：类别

注意：以下指南适用于分类：

  • 一般而言，以下规则适用于类别：

    • 每个族对象都属于一个类别

    • 非族对象（如材质和视图）不属于某个类别

    • 也有例外，例如 ProjectInfo，它属于“项目信息”类别。

  • 元素及其对应的符号通常属于同一类别。例如，基本墙及其墙类型“通用 - 8”都属于“墙”类别。

  • 相同类型的元素可以属于不同的类别。例如，SpotDimensions 具有 SpotDimensionType，但它可以属于两个不同的类别：高程点和高程点坐标。

  • 不同的元素可以由于相似性或体系结构原因而属于同一类别。ModelLine 和 DetailLine 位于 Lines 类别中。

要访问类别，您可以从文档的 Settings 类访问所有类别（例如，插入新的类别集），或者如果您只需要访问与内置类别关联的类别对象，您可以直接从 Category 类的静态重载 GetCategory（） 方法访问类别对象。

要访问类别：

  • 从文档属性中获取类别的完整映射：Document.Settings.Categories 返回一个 CategoryNameMap，其中包含按其名称编制索引的所有 Revit 类别的映射。

  • 通过调用静态方法 Category.GetCategory（） 的相应重载来获取特定的内置类别。

  • 通过调用静态方法 Category.GetCategory（) 的相应重载，按其 ElementId 获取特定类别或子类别。

  • 代码区域 5-1：从文档设置中获取类别

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
     // Get settings of current document
      Settings documentSettings = document.Settings;

    // Get all categories of current document
    Categories groups = documentSettings.Categories;

    // Show the number of all the categories to the user
    String prompt = "Number of all categories in current Revit document:" + groups.Size; 

    // get Floor category according to OST_Floors and show its name
    Category floorCategory = groups.get_Item(BuiltInCategory.OST_Floors);
    prompt += floorCategory.Name;

    // Give the user some information
    MessageBox.Show(prompt, "Revit", MessageBoxButtons.OK);

Category 的使用方式如下：

  • Category 用于对元素进行分类。元素类别确定某些行为。例如，同一类别中的所有图元都可以包含在同一个明细表中。
  • 元素具有基于其类别的参数。
  • 类别还用于控制 Revit 中的可见性和图形外观。

https://help.autodesk.com/cloudhelp/2018/ENU/Revit-API/images/GUID-FD2C68CC-B442-4A39-B507-8965B15B1DCF-low.png
图 21：按类别划分的可见性

元素的类别由 Category ID 确定。

  • 类别 ID 由 ElementId 类表示。
  • 导入的类别 ID 与文档中的元素相对应。
  • 大多数类别都是内置的，它们的 ID 是存储在 ElementId 中的常量。
  • 每个内置类别 ID 在 BuiltInCategory 枚举中都有相应的值。它们可以转换为相应的 BuiltInCategory 枚举类型。

如果类别不是内置类别，则 ID 将转换为 null 值。

代码区域 5-2：获取元素类别

1
2
3
4
5
6
7
8
9
10
11
  Element selectedElement = null;
    foreach (ElementId id in uidoc.Selection.GetElementIds())
    {
        selectedElement = document.GetElement(id);
        break;  // just get one selected element
    }
  
  // Get the category instance from the Category property
  Category category = selectedElement.Category;

BuiltInCategory enumCategory = (BuiltInCategory)category.Id.IntegerValue;

注意：为了避免在使用 Category.Name 时出现全球化问题，BuiltInCategory 是更好的选择。Category.Name 在不同的语言中可能会有所不同。

Family 族

族是类别中的元素类。族可以按以下方式对图元进行分组：

  • 一组通用的参数 （属性）。
  • 相同使用。
  • 类似的图形表示。

大多数族都是构件族文件，这意味着您可以将它们加载到项目中或从族模板创建它们。您可以确定属性集和族图形表示。
另一种族类型是系统 Family。系统族不可用于加载或创建。Revit 预定义了系统族属性和图形表示;它们包括墙、尺寸、屋顶、楼板（或楼板）和标高。

https://help.autodesk.com/cloudhelp/2018/ENU/Revit-API/images/GUID-428BCB2F-3741-4F05-A51A-9D5A9A03813D-low.png

图 22：族

除了用作 Element 类之外，Family 还是用于生成属于 Family 的新项目的模板。

Revit 平台 API 中的族

在 Revit 平台 API 中，Family 类和 FamilyInstance 都属于构件族。其他元素包括 System Family。

Revit 平台 API 中的族由三个对象表示：

  • Family 族
  • FamilySymbol 族符号
  • FamilyInstance 族实例

每个对象在 Family 结构中都起着重要作用。

Family 对象具有以下特征：

  • 表示整个族，例如梁。
  • 表示磁盘上的整个族文件。
  • 包含许多 FamilySymbol。

FamilySymbol 对象表示族中的一组特定族设置，例如类型、混凝土矩形梁：16×32。

FamilyInstance 对象是一个 FamilySymbol 实例，表示 Revit 项目中的单个实例。例如，FamilyInstance 可以是项目中 16×32 混凝土矩形梁的单个实例。

注意：请记住，FamilyInstance 存在于 FamilyInstance 元素、基准元素和注释元素中。

因此，以下规则适用：

  • 每个 FamilyInstance 都有一个 FamilySymbol。
  • 每个 FamilySymbol 都属于一个 Family。
  • 每个 Family 都包含一个或多个 FamilySymbol。

有关更多详细信息，请参阅系列实例。

ElementType 元素类型

在 Revit Platform API 中，符号通常是用于定义实例的不可见图元。Symbols 在用户界面中称为Types。

  • Type可以是族中的特定大小，例如 1730 × 2032 的门，也可以是 8×4×1/2 的角度。
  • Type可以是样式，例如尺寸的默认线性或默认角度样式。

Symbols表示包含一组类似元素的共享数据的元素。在某些情况下，Symbols表示可以从仓库获取的建筑构件，例如门或窗，并且可以在同一建筑物中多次放置。在其他情况下，Symbols 包含主机对象参数或其他元素。例如，WallType Symbol 包含特定墙壁类型的厚度、层数、每层的材料以及其他属性。

FamilySymbol 是 API 中的一个Symbols。它在 Revit 用户界面中也称为族类型。FamilySymbol 是族中的一类图元，其所有属性的值都完全相同。例如，所有 32×78 个六面板门都属于一种类型，而所有 24×80 个六面板门都属于另一种类型。与 Family 一样，FamilySymbol 也是一个模板。FamilySymbol 对象派生自 ElementType 对象和 Element 对象。

Instance 实例

实例是在建筑 （模型实例） 或绘图图纸 （注释实例） 上具有特定位置的项。Instance 表示 ElementType 的转换后的相同副本。例如，如果建筑物包含 20 个特定类型的窗户，则有一个 ElementType 具有 20 个实例。实例在用户界面中称为 Components。

注意：对于 FamilyInstance，可以使用 Symbol 属性而不是 GetTypeId（） 方法来获取相应的 FamilySymbol。它既方便又安全，因为您不需要进行类型转换。

元素检索

Revit中的图元非常常见。在对任何 Element 命令使用 API 之前，必须从 Revit 中检索所需的图元。有几种方法可以使用 Revit API 检索图元：

  • ElementId - 如果元素的 ElementId 已知，则可以从文档中检索该元素。
  • 元素过滤和迭代 - 这是检索文档中一组相关元素的好方法。
  • 选定元素 - 检索用户已选定的元素集
  • 特定元素 - 某些元素可用作文档的属性

以下各节将更详细地讨论这些元素检索方法中的每一种。

按 ID 获取元素

当所需元素的 ElementId 已知时，请使用 Document.Element 属性获取该元素。

筛选 Elements 集合

获取文档中元素的最常见方法是使用筛选来检索元素集合。Revit API 提供了 FilteredElementCollector 类和支持类，用于创建经过过滤的元素集合，然后可以迭代这些元素。有关更多信息，请参阅筛选。

Selection 选择

您可以只访问已选择的元素，而不是获取模型中所有元素的过滤集合。您可以使用 UIDocument.Selection.GetElementIds 方法从当前活动文档中获取所选对象。有关使用活动选择的更多信息，请参阅选择。

从文档中访问特定元素

除了使用常规方式访问图元外，Revit Platform API 还在 Document 类中具有属性，用于从当前活动文档中获取指定的图元，而无需迭代所有图元。下表列出了您可以检索的指定元素。

表 11：从文档属性中检索元素

Element 元素 Document 属性中的访问
ProjectInfo 项目信息 Document.ProjectInformation
ProjectLocation 项目位置 Document.ProjectLocations
SiteLocation 站点位置 Document.SiteLocation
Phase 阶段 Document.Phases

一般属性

以下特性对于使用 Revit 创建的每个图元都是通用的。

ElementId 元素 Id

活动文档中的每个元素都有一个唯一标识符，由 ElementId 存储类型表示。ElementId 对象是项目范围的。它是一个唯一编号，在元素模型中永远不会改变，这使得它可以存储在外部，以便在需要时检索元素。
在 Revit Platform API 中，您可以直接创建 ElementId，然后将唯一整数值与新的 ElementId 关联。默认情况下，新的 ElementId 值为 0。

代码区域 5-3：设置 ElementId

1
2
3
4
5
6
// Get the id of the element
Autodesk.Revit.DB.ElementId selectedId = element.Id;
int idInteger = selectedId.IntegerValue;

// create a new id and set the value
Autodesk.Revit.DB.ElementId id = new Autodesk.Revit.DB.ElementId(idInteger);

ElementId 具有以下用途：

使用 ElementId 从 Revit 中检索特定图元。从 Revit Application 类中，获取对活动文档的访问权限，然后使用Document.GetElement（ElementId） 方法获取指定的元素。

代码区域 5-4：使用 ElementId

1
2
3
4
5
6
7
8
9
// Get the id of the element
Autodesk.Revit.DB.ElementId selectedId = element.Id;
int idInteger = selectedId.IntegerValue;

// create a new id and set the value
Autodesk.Revit.DB.ElementId id = new Autodesk.Revit.DB.ElementId(idInteger);

// Get the element 
Autodesk.Revit.DB.Element first = document.GetElement(id);

如果项目中不存在 ID 号，则检索的元素为 null。

使用 ElementId 检查一个项目中的两个元素是否相等。不建议使用 Object.Equal（） 方法。

UniqueId 唯一 Id

每个元素都有一个 UniqueId，由 String 存储类型表示。UniqueId 对应于 ElementId。但是，与 ElementId 不同，UniqueId 的功能类似于 GUID（全局唯一标识符），它在单独的 Revit 项目中是唯一的。UniqueId 可以帮助您在将 Revit 项目文件导出为其他格式时跟踪元素。

代码区域 5-5：UniqueId

1
String uniqueId = element.UniqueId;

注意：ElementId 仅在当前项目中是唯一的。它在单独的 Revit 项目中不是唯一的。UniqueId 在单独的项目中始终是唯一的。

Location 位置

在建筑建模过程中，对象的位置非常重要。在Revit中，某些对象具有点位置。例如，一个表有一个点位置。其他对象具有线位置，表示位置曲线或根本没有位置。墙是具有线位置的元素。

Revit Platform API 为大多数图元提供 Location 类和位置功能。例如，它具有 Move（） 和 Rotate（） 方法来平移和旋转元素。但是，Location 类没有可以从中获取坐标等信息的属性。在这种情况下，将 Location 对象降级到其子类（如 LocationPoint 或 LocationCurve），以获取更详细的位置信息并使用对象派生进行控制。

在获取对象的几何图形时，检索元素在项目中的物理位置非常有用。检索位置时，以下规则适用：
Wall、Beam 和 Brace 使用 LocationCurve 进行曲线驱动。

Room、RoomTag、SpotDimension、Group、非曲线驱动的 FamilyInstances 以及所有 In-Place-FamilyInstances 都使用 LocationPoint。

在 Revit Platform API 中，曲线驱动意味着元素的几何图形或位置由一个或多个关联的曲线确定。几乎所有的分析模型元素都是曲线驱动的 - 线性荷载和面积荷载、墙、框架元素等。

其他元素无法检索 LocationCurve 或 LocationPoint。他们返回“Location ”，但未提供任何信息。

表 12：元素位置信息

位置信息 Elements 元素
LocationCurve 位置曲线 Wall, Beam, Brace, Structural Truss, LineLoad(without host)
LocationPoint 位置点 Room, RoomTag, SpotDimension, Group, Column, Mass
Only Location 仅位置 Level, Floor, some Tags, BeamSystem, Rebar, Reinforcement, PointLoad, AreaLoad(without Host), Span Direction(IndependentTag)
No Location 无位置 View, LineLoad(with host), AreaLoad(with Host), BoundaryCondition

注意：还有其他没有 Location 信息的元素。例如，LineLoad（带 host）或 AreaLoad（带 host）没有 Location。

某些 FamilyInstance LocationPoints（例如所有就地 FamilyInstances 和 mass）在创建时被指定为点 （0， 0， 0）。如果转换或移动实例，则 LocationPoint 坐标将更改。

若要更改 Group-s LocationPoint，请执行下列操作之一：

  • 在Revit UI中拖动组原点以更改LocationPoint坐标。在此情况下，组 LocationPoint 将更改，而 Group-s 的位置不会更改。
  • 使用 ElementTransformUtils.MoveElement（） 方法移动组以更改 LocationPoint。这将更改 Group location 和 LocationPoint。

有关 LocationCurve 和 LocationPoint 的更多信息，请参阅移动元素。

Level 标高

楼层是有限的水平平面，用作楼层托管或基于楼层的元素（如屋顶、地板和天花板）的参考。Revit Platform API 提供了一个 Level 类，用于表示 Revit 中的标高线。如果元素是基于Level 的，请使用 API 获取元素分配到的 Level 对象。

代码区域 5-6：分配标高

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Get the level object to which the element is assigned.
if (element.LevelId.Equals(ElementId.InvalidElementId))
{
    TaskDialog.Show("Revit","The element isn't based on a level.");
}
else
{
    Level level = element.Document.GetElement(element.LevelId) as Level;

    // Format the prompt information(Name and elevation)
    String prompt = "The element is based on a level.";
    prompt += "\nThe level name is:  " + level.Name;
    prompt += "\nThe level elevation is:  " + level.Elevation;
    
    // Show the information to the user.
    TaskDialog.Show("Revit",prompt);

}

许多元素（如柱）使用标高作为基本参考。当您获取柱标高时，您检索的标高是基础标高。

注意：使用 Reference Level 参数获取 Beam 或 Brace 标高。从 Level 属性中，您只会获得 null，而不是引用标高信息。标高是 Revit 中最常用的图元。在 Revit 平台 API 中，使用“level ”过滤器检索所有标高。

有关更多级别详细信息，请参阅基准和信息元素。

Parameter 参数

每个元素都有一组参数，用户可以在Revit中查看和编辑这些参数。参数在“元素属性”对话框中可见（选择任何元素，然后单击类型选择器旁边的“属性”按钮）。例如，下图显示了房间参数。

https://help.autodesk.com/cloudhelp/2018/ENU/Revit-API/images/GUID-78903670-DCD6-473B-AA90-45A0AA31B65D-low.png

图 25：Room 参数

在 Revit Platform API 中，每个 Element 对象都有一个 Parameters 属性，该属性是附加到 Element 的所有属性的集合。您可以更改集合中的属性值。例如，您可以从房间对象参数中获取房间的面积;此外，您还可以使用房间对象参数设置房间号。Parameter 是提供对元素对象中未公开的属性信息的访问的另一种方法。

通常，每个元素参数都有一个关联的参数 ID。参数 ID 由 ElementId 类表示。对于用户创建的参数，ID 对应于文档中的实际元素。但是，大多数参数都是内置的，其 ID 是存储在 ElementIds 中的常量。

参数是元素中数据存储的通用形式。在 Revit Platform API 中，最好使用内置参数 ID 来获取参数。Revit 具有大量使用 BuiltInParameter 枚举类型的内置参数。

有关详细信息，请参阅参数说明。

注：翻译自Revit API Developers Guide