بدء تطوير الإضافات باستخدام SketchUp Ruby API: دليل خطوة بخطوة

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

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

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

المتطلبات وما ينبغي معرفته قبل البدء

• SketchUp: تعمل Ruby API من داخل SketchUp ولا يمكن استخدامها بمفردها. لذا تحتاج إلى تطبيق SketchUp خلال التطوير والتجربة.

• معرفة Ruby: تصف المصادر API بأنها تعمل عبر Ruby. ولا تذكر اشتراط معرفة متقدمة بـ Ruby، لكن شيفرة الإضافة التي ستكتبها تستخدم Ruby.

• مصادر المطورين: تشمل المصادر المناسبة للبدء الوثائق الرسمية لـ SketchUp Ruby API، وRuby API Overview، وSketchUp Developer Center.

• بيئة IDE وتصحيح الأخطاء: توفر SketchUp واجهة لتصحيح الأخطاء يمكن استخدامها مع بيئات IDE والمحررات الداعمة لبروتوكول Ruby Debug. وتتوفر إرشادات إعداد لـ RubyMine ومثال مشروع لـ VSCode.

• الاختبار: قد يكون اختبار الشيفرة التي تعمل داخل SketchUp صعبًا باستخدام مسارات الاختبار القياسية المصممة لوحدة تحكم Ruby خارج SketchUp. يوفر TestUp غلافًا مبنيًا على Minitest لهذه الحالة، وواجهة رسومية لإدارة الاختبارات.

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

خطوات التطوير باستخدام SketchUp Ruby API

1. حدّد المهمة المراد أتمتتها

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

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

2. ابدأ بالنظرة العامة الرسمية والأمثلة

تُعد Ruby API Overview في وثائق SketchUp Ruby API نقطة الانطلاق الأساسية. كما تربط الوثائق الرسمية بأمثلة ودروس تعليمية تشرح المفاهيم والسيناريوهات الشائعة. في أول تطبيق لك، راجع الأمثلة واختر ما يرتبط بهدف الإضافة؛ وتحقق من الشرح بدلًا من افتراض وجود صنف أو طريقة أو سلوك لا توضحه الوثائق.

يجمع SketchUp Developer Center أيضًا محتوى للمبتدئين وإضافات نموذجية ومصادر API. وقد تساعدك هذه المواد على فهم كيفية توفير الإضافات أدوات ووظائف جديدة داخل SketchUp. وإذا كنت تخطط لمشاركة الإضافة مع الآخرين، يتيح مركز المطورين أيضًا خيار النشر عبر Extension Warehouse.

3. جهّز بيئة IDE لاستخدام API

تتوفر ملفات Ruby API stubs لمساعدة بيئة التطوير على التعرّف إلى SketchUp API. وتشمل المصادر الرسمية شرحًا لإعداد مشروع على RubyMine، ومثالًا لمشروع على VSCode. اختر المثال الملائم لبيئة IDE التي تستخدمها، واتبع خطوات الإعداد الموثقة.

يمكن استخدام واجهة SketchUp Ruby Debugger لتصحيح الأخطاء. وقد صُممت هذه الواجهة للعمل مع ميزات تصحيح الأخطاء في المحررات وبيئات IDE التي تدعم بروتوكول Ruby Debug. ولا تحدد المصادر بيئة IDE إلزامية، لذا يمكن اختيارها وفقًا للأدوات التي يستخدمها فريق التطوير بالفعل.

4. نفّذ استدعاءات API على الخيط الرئيسي

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

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

5. شغّل الاختبارات داخل SketchUp

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

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

6. تحقّق من النطاق إذا كنت تحتاج إلى دعم LayOut

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

أخطاء شائعة

• محاولة تشغيل API بشكل مستقل: Ruby API ليست أداة مستقلة يمكن استخدامها دون SketchUp.

• تجاهل التنبيه المتعلق بالخيط الرئيسي: يجب إجراء تفاعلات API على الخيط الرئيسي؛ وقد يؤدي عدم الالتزام بذلك إلى عدم استقرار التطبيق.

• اعتبار الاختبارات خارج SketchUp كافية: اختبر خيارات الاختبار داخل التطبيق، مثل TestUp، للشيفرة التي تعمل داخل SketchUp.

• افتراض تفاصيل غير موثقة: راجع وثائق API الرسمية للتحقق من معلومات الإصدارات والطرق والتوافق.

• تجاوز إعداد بيئة IDE: تتوفر ملفات API stubs وأمثلة لبيئات IDE وأدلة لتصحيح الأخطاء لإعداد بيئة التطوير.

الخطوات التالية

بعد الانتهاء من الإضافة الأولى، قيّم خيار النشر إذا كان يتناسب مع هدف استخدامها. يذكر SketchUp Developer Center إمكانية مشاركة الإضافات عبر Extension Warehouse. وإذا كنت تخطط للتوزيع خارج Extension Warehouse، فيوجهك مركز المطورين أيضًا إلى عملية التوقيع الرقمي وشهادة الأمان.

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

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

أُعد هذا الدليل باللغة التركية بالاستناد إلى الوثائق الرسمية لـ SketchUp Ruby API ومصادر المطورين في SketchUp Developer Center. وتُصنّف صفحتا المصدر على أنهما «حرتان» في سجلات المصادر؛ ولم يُذكر ترخيص محدد من Creative Commons.