مكوّنات SketchUp: دليل استخدام Component Instance وDefinition

تشرح وثائق SketchUp Ruby API كيفية تمثيل نسخ المكوّنات في النموذج، وكيفية إدارة التعريفات المرتبطة بها. يمثّل ComponentInstance نسخة مكوّن موضوعة في النموذج، بينما يمثّل ComponentDefinition تعريف المكوّن الذي تستند إليه هذه النسخة. ويُحدَّد موضع النسخة في النموذج أيضًا بمعلومات التحويل. يساعد فهم هذا التمييز على الفصل بين إجراء تغييرات مشتركة على العناصر المعاد استخدامها وتعديل نسخة واحدة فقط.

يستند هذا الدليل إلى طرق موثّقة في مراجع SketchUp Ruby API الخاصة بـ ComponentInstance وDefinitionList وModel. وتختلف ملاحظات الإصدارات الخاصة بهذه الطرق؛ لذا تُذكر حدود الإصدار ذات الصلة كلما حُدّدت في الوثائق.

1. افهم العلاقة بين النسخة وتعريف المكوّن

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

2. في Ruby API، يعيد Sketchup.active_model النموذج النشط. وتتيح طريقة definitions في كائن Model الوصول إلى مجموعة DefinitionList التي تضم كائنات ComponentDefinition في النموذج. أما طريقة definition في النسخة، فتعيد مباشرةً التعريف المرتبط بها. وبذلك يمكن التعامل مع استعراض التعريفات على مستوى النموذج والعثور على تعريف نسخة محددة كعمليتين منفصلتين.

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

2. افحص النسخة واعزلها باستخدام Ruby API

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

model = Sketchup.active_model
instance = model.active_entities.grep(Sketchup::ComponentInstance).first

if instance
  puts instance.definition.name
  instance.make_unique
end

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

2. تغيير التعريف المرتبط يختلف عن تغيير موضع النسخة. تعيّن الطريقة definition= تعريفًا آخر، وتشير الوثائق إلى أنها تحافظ على التحويل الحالي للنسخة. ويمكن استخدام transformation وtransformation= لقراءة التحويل أو ضبطه. أما transform! فتطبّق Geom::Transformation، بينما تضبط move! التحويل بطريقة مشابهة من دون تسجيل العملية في سجل التراجع. راعِ هذا الفرق عند تصميم تدفّق التحرير والتراجع في الإضافة.

3. تعامل بحذر مع الهندسة ومجموعات التعريفات

1. تحوّل الطريقة explode نسخة المكوّن إلى عناصر رسم منفصلة. وقد تعيد مصفوفة من العناصر عند النجاح أو false عند الإخفاق. إذا كان الحفاظ على بنية المكوّن مهمًا، فقيّم نتيجة العملية في النموذج قبل استخدام هذه الطريقة. وتدرج الوثائق أيضًا عمليات هندسية مثل intersect وouter_shell وsplit وsubtract وtrim وunion؛ وبعضها مخصص للعمل على أجسام صلبة manifold. لذلك، لا تفترض أن نتائجها ستكون واحدة على كل مكوّن.

2. تحسب trim الفرق بين جسمين صلبين manifold بطريقة غير تدميرية؛ أما subtract فهي طريقة أخرى مدرجة لإجراء عملية الفرق. وتشير وثائق API أيضًا إلى أن intersect غير متاحة في SketchUp Make. وقد وُسِمت الطريقة manifold? في ComponentInstance بأنها مهملة؛ ووفقًا للوثائق، يُفضّل استخدام ComponentDefinition#manifold? للتحقق من حالة manifold للتعريف. وتوضح هذه الملاحظات ضرورة مراجعة وصف الطريقة ونوع الكائن قبل تنفيذ العمليات الهندسية.

3. تتضمن DefinitionList طرقًا للعثور على التعريفات بحسب الفهرس أو الاسم أو GUID، وإضافة تعريف جديد، وتحميل مكوّن من ملف، وتنظيف التعريفات غير المستخدمة. تزيل purge_unused التعريفات غير المستخدمة. تجنّب حذف عناصر من المجموعة نفسها أثناء المرور عليها باستخدام each؛ إذ تحذّر الوثائق من احتمال تخطي بعض التعريفات بسبب تغيّر عدد العناصر والفهارس. وإذا كان الحذف ضروريًا، توصي الوثائق أولًا بنسخ المجموعة إلى مصفوفة، ثم متابعة العمل على النسخة.

4. تحقّق من التوافق مع الإصدارات وسلامة الملفات

1. تُستخدم الطريقة load في DefinitionList لتحميل ملف مكوّن SketchUp. ووفقًا للوثائق، يتوفر الخيار allow_newer بدءًا من SketchUp 2021.0، ويسمح بتحميل نماذج محفوظة بإصدار أحدث. لكن قد تُسقط بعض المعلومات أثناء التحميل؛ وتحذّر وثائق API من حفظ الملف المحمّل من نموذج أحدث فوق الملف الأصلي. لذا فإن الاحتفاظ بالنموذج المصدر جزء من سير العمل.

2. توجد أيضًا ملاحظة بشأن سلوك إعادة تحميل مكوّن من مسار الملف نفسه. قبل SketchUp 2023.0، إذا كان النموذج يتضمن مكوّنًا آخر مرتبطًا بالمسار نفسه، فقد يعيد استدعاء التحميل المكوّن الموجود بدلًا من جلب المحتوى الجديد. إذا بدا أن الملف لم يتحدّث، فتحقّق من إصدار SketchUp المستخدم ومسار الملف، وراعِ حدود الإصدارات المذكورة في الوثائق المصدرية عند ضمان توافق كود الإضافة.

التأثير في سير عمل العمارة والتصميم الداخلي والتصور

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

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

أخطاء شائعة

• تعديل تعريف مشترك لنسخة من دون مراعاة احتمال تغيّر النسخ الأخرى.

• افتراض أن الكود اختار كائنًا محددًا، مع أنه يعثر على أول كائن ComponentInstance.

• الخلط بين تعيين تعريف وبين تغيير تحويل الموضع.

• استخدام طرق هندسية تشترط أن تكون الأجسام manifold كما لو كانت تعمل على كل مكوّن.

• حذف عناصر من DefinitionList أثناء المرور عليها.

• تجاهل التحذير من حفظ التغييرات فوق الملف المصدر بعد تحميل نموذج أحدث.