Chia sẽ BCDD lên mạng xã hội nhé !

Trong bài viết này BCDD sẽ hướng dẫn cơ bản cách đọc hiểu RevitAPI. Sở dĩ tôi nói cơ bản vì thực sự tài liệu này rất lớn, khó lòng mà nắm hết được nên BCDD sẽ chỉ hướng dẫn cách đọc, tra một số phương thức, kiểu dữ liệu, thuộc tính, bộ khởi dựng…Việc hiểu tài liệu RevitAPI này sẽ giúp bạn đọc của BCDD tự tra cứu cũng như giúp dễ hiểu hơn khi tham khảo code của người khác và dần dần bước vào thế giới lập trình Revit API.

Revit API là gì

Có thể bạn đã biết, hầu hết các phần mềm đều có một API (Application Programming Interface) cho phép can thiệp sâu hơn vào phần mềm để tạo ra các add-ins, tiện ích giúp giải quyết công việc của chúng ta nhanh và hiệu quả hơn. Bởi tính chất công việc, dự án, quy trình của mỗi công ty là khác nhau nên Autodesk không thể tạo ra quá nhiều công cụ cho Revit mà chỉ tạo ra những thứ chung cho số đông người dùng. Đơn vị hay cá nhân nào muốn có những bộ công cụ riêng cho Revit để giải quyết những vấn đề riêng của mình thì đều tham khảo đến tài liệu này.

Tài liệu RevitAPI nằm trong bộ Revit SDK (Software Development Kit). Tải cái này giải nén ra bạn sẽ thấy một file RevitAPI.chm, đây chính là tài liệu RevitAPI.

Tuy nhiên có một Developer tên là Gui Talarico đã đưa tài liệu này lên nền tảng web. Bạn có thể tra cứu tại https://apidocs.co/ . Trong trang này thì ngoài RevitAPI bạn cũng có thể tra API của các phần mềm khác như Navisworks, Grasshopper hay Rhino. Ngoài ra cũng có một trang khác (cũng do người này tạo ra bằng Python) dùng để tra RevitAPI phổ biến hơn là https://www.revitapidocs.com/ tuy nhiên trang này chỉ dùng để tra cứu API cho mỗi phần mềm Revit thôi.

Đọc hiểu RevitAPI

Khúc này bắt đầu quan trọng rồi này, pha cafe bật nhạc baroque và từ từ chầm chậm đọc hiểu để làm chủ RevitAPI nhé !

Mô-đun/ Assembly

Trước tiên thì tài liệu RevitAPI này chính là nơi để tra cứu của mô-đun (hay còn gọi là assembly) RevitAPI.dll và RevitAPIUI.dll mà chúng ta hay tham chiếu vào Dynamo hay C# khi lập trình Revit API.

Namespace và Class

Dưới đây là giao diện cơ bản khi mới mở RevitAPI. Về tổng quan thì nó có 2 cột, như chúng ta thấy thì cột bên trái là các namespaces của mô-đun RevitAPI, còn cột bên phải là các classes của các namespaces tương ứng bên trái.

Method và Property (phương thức và thuộc tính)

Chọn vào một class bất kỳ ví dụ như Element chẳng hạn rồi chọn vào Members thì chúng ta sẽ thấy các phương thức (methods) và thuộc tính (properties) của class đó.

Constructors (Bộ khởi dựng)

Một số class thì chỉ có methods và properties nhưng cũng có một số classes có thêm Constructors (bộ khởi dựng) như class FilteredElementCollector.

Hệ thống cấp bậc

Tới đây thì BCDD đã cho bạn thấy các cấp bậc trong file RevitAPI rồi đó. Cao nhất là mô-đun (hay còn gọi là assembly) như RevitAPI.dll và RevitAPIUI.dll. Bên trong đó là các namespaces, bên trong mỗi namespace là các classes, bên trong mỗi class là các constructors, methods và properties. Còn nếu bạn muốn hiểu sâu hơn như thế nào là namespace, class, constructors, method, property thì xin mời google. Những blog hay web của dân lập trình chuyên nghiệp sẽ giải thích rõ nghĩa hơn những khái niệm này.

Đọc hiểu RevitAPI

Còn trong phạm vi bài viết này của BCDD chúng tôi sẽ giải thích như này cho bạn dễ hình dung. Mô-đun hay assembly là các file có đuôi dll nằm ở đâu đó trong thư mục Revit của bạn mà cụ thể là nằm ở đây: C:\Program Files\Autodesk\Revit 2022

Bên trong các file dll này có các namespaces, trong đó có hai namespaces mà chúng ta hay import vào Dynamo đó là Autodesk.Revit.DB và Autodesk.Revit.UI

Để dễ hình dung hơn thì bạn có thể tưởng tượng mỗi mô-đun như một thư viện và các namespaces như những cuốn sách trong thư viện. Vậy thì classes là các chương sách, constructors, methods và properties là nội dung trong các chương sách.

Vậy bây giờ BCDD sẽ lấy một cuốn sách và mở ra một chương bất kỳ. Ví dụ như giờ BCDD đi đến một thư viện có tên là RevitAPI.dll lấy một cuốn sách Autodesk.Revit.DB và mở ra chương FilteredElementCollector và xem thử bên trong có gì nhé.

FilteredElementCollector rõ ràng là một class (có chữ class đứng sau nó kìa). Tiếp tục chọn vào Members để xem nội dung bên trong như constructors, methods, properties.

Ok cái đập vào mắt đầu tiên là Constructors (bộ khởi dựng). Như bạn có thể thấy class này có đến 3 bộ khởi dựng. Vậy bộ khởi dựng là gì? xin thưa, giống như tên của nó đó, cái này dùng để tạo dựng/khởi dựng nên cái class FilteredElementCollector.

Trong bài viết này BCDD sẽ dùng bộ khởi dựng đầu tiên để viết tiếp cho phần sau của bài viết (rất tiếc vì thời gian của chúng tôi có hạn nên không thể giải thích hết). Thì bộ khởi dựng đầu tiên có document bên trong, tức là Constructor này sẽ tìm kiếm và lọc những đối tượng trong một document nào đó mà người lập trình cung cấp.

Vậy là xong cái constructors, giờ đi đến method chọn vào một method nào đó ví dụ như Category chẳng hạn.

Tới đây thì chúng ta sẽ quan tâm đến cú pháp C# bên dưới, hiểu luôn cái này là cơ bản hiểu về RevitAPI

OfCategory rõ ràng là một phương thức (method) và phương thức này trả về kiểu dữ liệu FilteredElementCollector. Mức độ truy cập là Public. Phương thức này chỉ có một tham số là category (tức là phải cung cấp tham số này cho phương thức OfCategory) với kiểu dữ liệu là BuiltInCategory.

Vậy với cú pháp này chúng ta sẽ dùng để đi kiếm và lọc những category nhất định trong Revit như Walls, Floors, Doors…nhưng mà khoan, chờ khoảng 2 giây ! kiểu dữ liệu BuiltInCategory là gì? 

Muốn biết là gì thì click vào nó xem sao.

Ohh hóa ra nó là một Enumeration hay giang hồ còn gọi là enum (là một kiểu dữ liệu trả về một danh sách gì đó (list of specific things). Kéo trang RevitAPI xuống một xíu sẽ thấy tất cả các thành viên của enum này. Đem cái này quăng vào method ở trên là ok.

Ví dụ như đoạn python scripts dưới đây được viết trong Dynamo, BCDD đã dùng:

filter_beams = FilteredElementCollector(doc).OfCategory(BuiltInCategory.OST_StructuralFraming).WhereElementIsNotElementType()

Đừng bận tâm quá nhiều, chỉ cần quan tâm đến OST_StructuralFraming là đủ và hiểu rằng nó nằm trong BuiltInCategory ở trên. Và đoạn code trên để lọc ra những category là dầm kết cấu.

Ok tới đây là xong rồi đó và bây giờ việc cần làm của bạn là hãy chuẩn bị một tâm hồn đẹp để bước chân vào thế giới lập trình Revit API.

Để theo đuổi và tiếp tục học về RevitAPI thì đa số mọi người đều tập trung vào các nội dung sau mà nếu có thời gian BCDD sẽ viết tiếp về chúng.

Xem thêm các bài viết:

Nếu thấy bài viết này hữu ích, hãy cân nhắc việc ủng hộ BCDD tại đây

Bài viết do admin 1 Nghia Nguyen và cộng sự BCDD biên soạn.

2 thoughts on “Lập trình Revit API: Cách đọc hiểu Revit API

Comments are closed.