如何阅读Revit的API文档——Dynamo Python系列教程（十）

好消息：“BIM的乐趣”微信群恢复运营了，有兴趣的小伙伴可以在文章底部扫码入群哦~
Revit的API很大，其文档也很大，本次文章简单教你如何阅读它。

虽然Autodesk的官方文档Revit API可以在其SDK中找到一个.chm文件，但我建议大家访问http://APIDocs.co来了解Revit API。

这个由软件开发人员Gui Talarico创建的站点记录了Revit、Rhino、Grasshopper等api。访问APIDocs（https://apidocs.co/）以获得阅读API文档的感觉；作为一名程序员，这是你经常要做的事情。

使用http://APIDocs.Co

该网站对于想要学习Revit API的人来说是非常宝贵的资源，这里我简单截了个图：

image

一个基本的工作流程包括确保你已经为所使用的产品选择适当的API版本（在左窗格中），然后在API文档中搜索您需要的相关主题。

例如，如果要了解有关FamilyCreate类的更多信息，只需在搜索栏中搜索它，然后从自动完成选项中选择它即可。然后，有关此类的详细信息将显示在右侧的详细信息栏中。有关此窗格的更多详细信息（如上图所示）：

1、这是你正在查看的页面的名称。Revit API拥有超过22,000页，尽管其中大多数你可能永远都不需要查看!

2、右上角这个<>按钮将在几个常用的Github存储库中搜索有关该类的任何代码示例。

3、“Members”按钮将带你到显示该类的所有方法、属性、接口或构造函数的整个页面。

基本术语
为了阅读Revit的API文档，您需要熟悉一些技术术语。首先，回顾一下我们在这里使用的术语，例如类和对象：

这里涉及到“面向对象编程”的一些知识，这里简单叙述下：

面向对象的编程（称为OOP）是一种非常流行的编程范式，已在软件开发中广泛使用了数十年。它由用户在其代码中定义抽象的“类”组成，这些类具有各种属性和功能。这些类旨在表示现实生活中的特定事物，可能是汽车或个人的银行帐户。

一旦为任务定义了必要的类，程序员便会创建它们的可用实例，称为“对象”。

这就是族在Revit中的工作方式。用户首先定义一个抽象族（.rfa文件），然后将其实例放置在他们的模型中。

类是抽象定义，例如.rfa文件

对象是这些类的实例

一旦你掌握了面向对象的编程术语，在你凭直觉了解它们之前，学习更多的术语将会很有帮助。

Menbers：一个类的成员页就是它的所有方法、属性等集合在一个页面上。如果你不确定某个类是否具有特定功能，这将非常有用。

Methods：类方法是它可以运行的函数。这些可以被看作类似于动词——这个类的实例可以做什么？例如，FamilyInstance类型的对象具有flipHand()方法，可以让你翻转族的方向。

#示例代码
my_family_instance.flipHand()
#这将翻转类型为familyinstance的对象

请注意：对Revit文档所做的任何更改都必须在打开的Transaction中进行。

Properties：属性更像是类的“形容词”，可帮助你理解有关该类的特定对象（即实例）的更多特性。例如，FamilyInstance类具有一个“ HandFlipped”属性，你可以查询该属性，该属性将告诉你该特定实例的操作是否已翻转完成。

#示例代码
is_it_handflipped = my_family_instance.HandFlipped
#这将返回真或假取决于它是否翻转!

Contructors（构造函数）

API中的构造函数实质上是在告诉你如何创建类的实例。例如，XYZ类用于定义Revit中的一个点。我们可以使用其构造函数来创建一个新的点，如下所示：

#示例代码
my_point = XYZ(0,0,0) #在原点处创建一个新的点
#注意:Revit几何图形是不可见的，不像Dynamo几何图形

Enumerations（枚举）

这些列表也称为枚举，它们是硬编码的列表，通常不会更改，并将选择限制在一组选项中。例如：交通信号灯状态的枚举应类似于：

因此，用户创建的任何交通信号灯对象都需要将其交通信号灯状态设置为软件供应商定义的预先编写的状态之一。你可以这样选择枚举值：

#示例代码
traffic_light_value = TrafficLightState.FlashingOrange
#这将在enum中选择一个预定义的状态

Revit API中的一些关键枚举是：

注意：版本变更

Revit API随每个子发行版本变化。这些通常是每几个月进行的微小更改。TheBuildingCoder博客非常出色地记录了每个API版本所做的更改。

https://thebuildingcoder.typepad.com/blog/2019/04/whats-new-in-the-revit-2020-api.html