فلاتر العرض في Revit API: دليل الإنشاء والإدارة

ما الذي ستتعلمه في هذا الدليل؟

يمكن استخدام فلتر العرض في Revit API للتحكم بالعناصر التي تظهر في عرض ما أو بطريقة ظهورها. سنتناول في هذا الدليل نوعين من الفلاتر: ParameterFilterElement الذي يعتمد على شروط الفئات والمعلمات، وSelectionFilterElement الذي يتألف من معرّفات عناصر محددة. سنستعرض خطوة بخطوة إنشاء الفلتر وإضافته إلى عرض وتغيير الظهور وتطبيق إعدادات الرسومات.

في التوثيق المعماري، يمكن الاستفادة من هذا الأسلوب، مثلًا، لإخفاء جدران تستوفي شروطًا محددة من العرض، أو لتمييز عناصر مختارة بلون خط مختلف. هذه سيناريوهات توضيحية للطريقة؛ أما الفئات والقواعد المستخدمة فينبغي تحديدها وفق احتياجات المشروع.

المتطلبات والتحقق من الإصدار

هذا الشرح موجّه إلى تطوير الإضافات باستخدام Revit API، وليس إلى شرح خطوات استخدام القوائم في واجهة Revit. وتشمل شروحات API الواردة في المصادر إنشاء فلتر والعمل عليه ضمن مستند وعرض في Revit. ولا تذكر متطلبات محددة لنوع حساب أو رسوم أو أجهزة إضافية.

من المهم الرجوع إلى وثائق API الخاصة بإصدار Revit المستهدف. توضح وثائق Autodesk الخاصة بـ Revit 2024 API أن المطورين يستطيعون الاستعانة بملف المساعدة RevitAPI.chm المرفق مع SDK، وبالحل Samples\SDKSamples.sln بوصفهما مرجعين. ولا ينبغي افتراض أن الشيفرة المكتوبة لإصدار أقدم ستعمل كما هي في إصدار أحدث.

على سبيل المثال، في Revit 2024، زاد التخزين الداخلي لقيمة ElementId من 32 بت إلى 64 بت. وحلّت الخاصية Value، التي تُرجع القيمة الكاملة ذات 64 بت، محل الخاصية السابقة IntegerValue. وتفيد Autodesk بأن الشيفرات المترجمة وفق إصدارات API السابقة قد تواجه بعض مشكلات تحويل الأنواع، وأنه ينبغي إعادة ترجمتها باستخدام Revit 2024 API. لذلك، يجب التحقق من وثائق الإصدار المستهدف للتعرّف إلى الأصناف والطرائق المستخدمة في تطوير الفلاتر.

خطوة بخطوة: إنشاء فلتر للمعلمات

1. حدّد الفئة والشروط. يستخدم ParameterFilterElement فئة واحدة أو أكثر من الفئات المسموح بها، إلى جانب القواعد المطبقة على العناصر ضمن تلك الفئات. قبل إنشاء الفلتر، حدّد مجموعة العناصر التي تريد تضمينها وقيم المعلمات المطلوب البحث عنها. يختار مثال Autodesk فئة الجدران؛ وتشمل القواعد أن تكون وظيفة الجدار “Exterior”، وأن تكون قيمة طول معينة مساوية لحد معيّن أو أكبر منه.

2. أنشئ عنصر الفلتر وأسند إليه القواعد. تنشئ ParameterFilterElement.Create عنصر الفلتر بالاستناد إلى المستند واسم الفلتر وقائمة الفئات. وبعد إعداد القواعد، تُسنَد إلى الفلتر باستخدام SetRules. ويعرض المصدر أمثلة على شروط المساواة، والقيمة الأكبر من حد أو المساوية له، والنص الذي يبدأ بسلسلة معينة. لا يعني ذلك أن المعلمات نفسها ستُستخدم في كل مشروع؛ إذ يجب أن تتوافق القاعدة مع الفئة والمعلمات المعنية.

3. اربط الفلتر بالعرض. تطبّق View.AddFilter() الفلتر على العرض المستهدف. لكن هذا الاستدعاء يستخدم تجاوزات الرسومات الافتراضية؛ لذلك قد لا يظهر أي اختلاف بصري حتى بعد تطبيق الفلتر. تعامل مع وجود الفلتر ومع النتيجة التي يُحدثها في العرض على أنهما أمران منفصلان.

4. اضبط الظهور. تحدد View.SetFilterVisibility() ما إذا كانت العناصر المطابقة لشروط الفلتر ستظهر أم لا. وإذا لم يكن الفلتر مطبقًا على العرض بعد، فإن هذه الطريقة تضيفه إليه أيضًا؛ لذا ليس من الضروري استدعاء AddFilter() بشكل منفصل. فإذا كان الهدف، مثلًا، إخفاء العناصر المطابقة، اضبط الظهور بما يحقق ذلك.

5. طبّق إعدادات الرسومات. يمكن استخدام View.SetFilterOverrides() لتغيير خصائص العرض، مثل لون الخط، للعناصر المطابقة للفلتر. ويمكن استرجاع الإعدادات الحالية باستخدام View.GetFilterOverrides(). وهكذا لا يقتصر دور الفلتر على التحكم بالظهور، بل يمكن استخدامه أيضًا لتمييز العناصر بصريًا في العرض.

خطوة بخطوة: فلتر التحديد وتعديل الفلاتر

1. حدّد العناصر التي ستدخل في الفلتر. يعمل SelectionFilterElement بالاستناد إلى معرّفات مجموعة من العناصر، بدلًا من قواعد المعلمات. في مثال المصدر، تُجمَع أولًا وسوم الغرف ضمن عرض معين، ثم تُضاف معرّفات الوسوم التي تستوفي شرط رقم الغرفة إلى قائمة. في هذه الطريقة، يتحدد النطاق بمعرّفات العناصر المحددة، لا بقواعد الفلتر.

2. أنشئ فلتر التحديد. يُنشأ عنصر الفلتر باستخدام SelectionFilterElement.Create، ثم تُسنَد معرّفات العناصر إليه باستخدام SetElementIds. وتُضاف هوية الفلتر إلى العرض المستهدف عبر View.AddFilter(). ويساعد التحقق من جمع العناصر المراد تضمينها على الحد من النتائج غير المتوقعة.

3. أضف تجاوزًا للرسومات عند الحاجة. في مثال Autodesk، تُسترجع إعدادات الفلاتر الحالية في العرض، ويُضبط لون الخط على الأزرق، ثم تُطبّق الإعدادات باستخدام View.SetFilterOverrides(). يوضح هذا المثال طريقة إضافة إعداد رسومي إلى فلتر تحديد؛ أما اللون أو الخيارات المرئية الأخرى فينبغي اختيارها وفق معايير المشروع.

4. راجع الفلاتر الحالية. تُرجع View.GetFilters() معرّفات الفلاتر الموجودة في العرض. ويمكن التحقق من ظهور فلتر معين باستخدام View.GetFilterVisibility()، ومن إعداداته الرسومية باستخدام View.GetFilterOverrides(). وتزيل View.RemoveFilter() الفلتر من العرض. لتغيير الإعدادات الحالية، اقرأ قيم الفلاتر أولًا، ثم طبّق إعداد الرسومات المناسب باستخدام View.SetFilterOverrides().

تُنفّذ العمليات التي تغيّر المستند ضمن معاملة (transaction) في أمثلة Autodesk. عند إنشاء الفلاتر أو ربطها بعرض أو تغيير إعدادات الرسومات، ضع في الحسبان أن هذه العمليات تُعدّل المستند. ويسهّل التحقق من كل وظيفة على حدة تحديد ما إذا كانت المشكلة ناتجة عن قاعدة الفلتر أو الظهور أو إعدادات الرسومات.

الأخطاء الشائعة والخطوات التالية

أُضيف الفلتر لكن العرض لم يتغير: تستخدم AddFilter() إعدادات الرسومات الافتراضية، وقد لا يؤدي استدعاؤها وحده إلى تغيير مرئي. تحقّق من إعدادات SetFilterVisibility() للتحكم بالظهور، ومن إعدادات SetFilterOverrides() لإظهار اختلاف رسومي.

القاعدة لا تعثر على العناصر المتوقعة: راجع الفئات المسموح بها في الفلتر والمعلمات المستخدمة في الشروط. وبما أن فلتر المعلمات محصور بفئة معينة، فلن تُضمّن العناصر التابعة لفئة خارج النطاق حتى لو استوفت القاعدة.

يتضمن فلتر التحديد عناصر غير صحيحة: افحص قائمة المعرّفات التي أُنشئت قبل SetElementIds، وشروط التحديد التي أنتجت هذه القائمة. هذا النوع من الفلاتر لا يطبّق قواعد المعلمات تلقائيًا؛ بل يجب إسناد معرّفات العناصر المستهدفة إليه صراحةً.

تواجه الإضافة مشكلة في إصدار آخر من Revit: تحقّق من تغييرات API في الإصدار المستهدف. فقد يتطلب تغيير ElementId إلى 64 بت في Revit 2024 إعادة ترجمة الشيفرات التي بُنيت وفق API أقدم. ومن الخطوات المفيدة التالية العمل في عرض اختباري قبل التطوير أو التحديث، ومطابقة وثائق API المستخدمة مع الإصدار.

يمكن لفرق الهندسة المعمارية والتصميم الداخلي والتصور المعماري الاستفادة من الفلاتر، خصوصًا عند الحاجة إلى إدارة مجموعات العناصر في العروض بطريقة متسقة. يصف فلتر المعلمات المعايير باستخدام الفئات والقواعد، في حين يركّز فلتر التحديد مباشرةً على مجموعات عناصر محددة. ويتوقف اختيار الطريقة المناسبة على معيار العرض وكيفية تحديد العناصر. كما ينبغي التعامل مع توافق الإضافات والانتقال بين الإصدارات بوصفهما جزءًا من سير العمل.

عند البدء بالتطبيق، ابدأ بعرض اختباري صغير: ضيّق النطاق أولًا، ثم تحقّق بشكل منفصل من مطابقة العناصر للفلتر والظهور وإعدادات الرسومات. بعد التأكد من أن النتائج تعمل كما هو متوقع، عدّل النهج ليتوافق مع معايير المشروع.

المصدر والترخيص

أُعدّ هذا الدليل استنادًا إلى شرح “View Filters” في Revit API Developers Guide من Autodesk، وإلى محتوى المساعدة الخاص بتغييرات Revit 2024 API. ووفق معلومات الترخيص المقدمة، فإن المصادر متاحة للاستخدام الحر؛ وهذا النص تكييف باللغة التركية للشروحات التقنية الواردة فيها.