المكتبات

المكتبة هي مشروع نص برمجي يمكن إعادة استخدام الدوالّ الخاصة به في نصوص برمجية أخرى.

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

الوصول إلى مكتبة

لتضمين مكتبة في مشروعك، يجب أن يكون لديك إذن وصول على مستوى العرض على الأقل. إذا لم تكن أنت مؤلف المكتبة التي تريد تضمينها، يُرجى التواصل مع المؤلف وطلب الوصول إليها.

تحتاج إلى رقم تعريف النص البرمجي للمكتبة التي تريد تضمينها. عندما يصبح بإمكانك الوصول إلى المكتبة، ابحث عن رقم تعريف النص البرمجي في صفحة إعدادات المشروع .

إضافة مكتبة إلى مشروع النص البرمجي

1. على يمين محرّر "برمجة التطبيقات"، انقر على "إضافة مكتبة " بجانب "المكتبات".
2. في حقل "رقم تعريف النص البرمجي"، الصِق رقم تعريف النص البرمجي للمكتبة.
3. انقر على بحث.
   في حال حدوث خطأ، تأكَّد من أنّ لديك إذن وصول على مستوى العرض على الأقل إلى المشروع الذي تحاول تضمينه.
4. انقر على القائمة المنسدلة الإصدار واختَر إصدار المكتبة المطلوب استخدامه.
5. تحقَّق مما إذا كان اسم "المعرّف" التلقائي هو الاسم الذي تريد استخدامه مع هذه المكتبة. هذا هو الاسم الذي يستخدمه النص البرمجي للإشارة إلى المكتبة. على سبيل المثال، إذا ضبطته على Test ثم استدعيت طريقة من هذه المكتبة على النحو التالي: Test.libraryMethod.
   إذا كنت تستخدم اسم معرّف يتطابق مع اسم خدمة حالية، مثل MailApp، أو مكتبة تمت إضافتها سابقًا، فإنّ المكتبة التي أضفتها مؤخرًا تحل محل الخدمة أو المكتبة الحالية.
6. انقر على إضافة.

استخدام مكتبة

استخدِم المكتبة المضمّنة بالطريقة نفسها التي تستخدم بها خدمة تلقائية. على سبيل المثال، إذا كان Test هو المعرّف الخاص بمكتبتك، اكتب Test متبوعًا بنقطة مباشرةً للاطّلاع على قائمة الطرق في المكتبة.

افتح المستند المرجعي لمكتبة مضمّنة باتّباع الخطوات التالية:

على يسار أداة تعديل النصوص البرمجية، بجانب اسم المكتبة، انقر على "المزيد" > الفتح في علامة تبويب جديدة.

إزالة مكتبة

على يسار أداة تعديل النصوص البرمجية، بجانب اسم المكتبة، انقر على "المزيد" > إزالة > إزالة المكتبة.

إذا حذف المؤلف مكتبة، عليك إزالتها من قائمة المكتبات المضمّنة.

تعديل مكتبة

يمكنك تغيير إصدار المكتبة أو تعديل المعرّف الخاص بها.

1. على يمين المحرّر، انقر على اسم المكتبة ضمن "المكتبات".
2. أدخِل التغييرات التي تريدها، وانقر على حفظ.

إنشاء مكتبة ومشاركتها

لاستخدام مشروع النص البرمجي ومشاركته كمكتبة، اتّبِع الخطوات التالية:

1. أنشِئ عملية نشر تستند إلى إصدار من النص البرمجي.
2. شارك إذن الوصول على مستوى العرض على الأقل مع جميع المستخدمين المحتملين للمكتبة.
3. زوِّد هؤلاء المستخدمين برقم تعريف النص البرمجي الذي يمكن العثور عليه في صفحة المشروع الإعدادات .

أفضل الممارسات

في ما يلي بعض الإرشادات التي يجب اتّباعها عند كتابة مكتبة:

1. اختَر اسمًا ذا معنى لمشروعك لأنّه يُستخدَم كمعرّف تلقائي عندما يضمّن الآخرون مكتبتك.
2. لإخفاء طريقة واحدة أو أكثر من طرق النص البرمجي عن مستخدمي المكتبة (وعدم السماح لهم باستخدامها)، يجب أن ينتهي اسم الطريقة بشرطة سفلية. على سبيل المثال، myPrivateMethod_.
3. لا يظهر لمستخدمي المكتبة سوى الخصائص العامة القابلة للتعداد. ويشمل ذلك إعلانات الدوالّ والمتغيّرات التي تم إنشاؤها خارج دالة باستخدام var والخصائص التي تم ضبطها بشكل صريح على الكائن العام. على سبيل المثال، يؤدي استخدام Object.defineProperty() مع ضبط enumerable على false إلى إنشاء رمز يمكنك استخدامه في مكتبتك، ولكن لا يمكن للمستخدمين الوصول إلى هذا الرمز.

4. لضمان إمكانية استخدام مستخدمي المكتبة لميزة الإكمال التلقائي في أداة تعديل النصوص البرمجية والمستندات التي يتم إنشاؤها تلقائيًا، يجب تضمين مستندات بأسلوب JSDoc لجميع الدوالّ. في ما يلي مثال:

   /**
    * Raises a number to the given power, and returns the result.
    *
    * @param {number} base the number we're raising to a power
    * @param {number} exp the exponent we're raising the base to
    * @return {number} the result of the exponential calculation
    */
   function power(base, exp) { ... }
   

تحديد نطاق الموارد

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

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

  function getLibraryProperty(key) {
    const scriptProperties = PropertiesService.getScriptProperties();
    return scriptProperties.getProperty(key);
  }

يوضّح المخطّط التالي موردًا غير مشترَك باستخدام مثال "خصائص النص البرمجي":

يسرد هذا الجدول الموارد المشترَكة وغير المشترَكة للرجوع إليها:

المورد	مشترَك*	غير مشترَك**	ملاحظات
قفل			يظهر المثال نفسه لجميع النصوص البرمجية المضمّنة عند إنشائه في المكتبة.
خصائص النص البرمجي			يظهر المثال نفسه لجميع النصوص البرمجية المضمّنة عند إنشائه في المكتبة.
ذاكرة التخزين المؤقت			يظهر المثال نفسه لجميع النصوص البرمجية المضمّنة عند إنشائه في المكتبة.
العوامل التي تؤدي إلى الظهور			لا يتم تفعيل العوامل التي تؤدي إلى الظهور البسيطة التي تم إنشاؤها في المكتبة من خلال النص البرمجي المضمّن.
ScriptApp
UiApp
خصائص المستخدمين
سجلّ الأخطاء ونص التنفيذ
المواقع الإلكترونية وجداول البيانات والحاويات الأخرى			تعرض استدعاء getActive حاوية النص البرمجي المضمّن.
MailApp وGmailApp
* يعني ذلك أنّ المكتبة ليس لديها مثال خاص بها من الـ ميزة أو المورد، بل تستخدم المثال الذي أنشأه النص البرمجي الذي استدعاها. ** يعني ذلك أنّ المكتبة لديها مثال خاص بها من المورد أو الميزة وأنّ جميع النصوص البرمجية التي تستخدم المكتبة تشارك هذا المثال نفسه وتستطيع الوصول إليه.

اختبار مكتبة

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

يجب أن يكون لديك إصدار واحد على الأقل من المكتبة تم حفظه.

تحديد الأخطاء في مكتبة وحلّها

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

لا يؤدي استخدام الرئيسي (وضع التطوير) لإصدار المكتبة إلى إتاحة الانتقال إلى المكتبة أو الوصول إلى نقاط التوقف بداخلها.

لتحديد الأخطاء في رمز المكتبة وحلّها، استخدِم إحدى الطريقتَين التاليتَين:

• تصحيح الأخطاء من مشروع المكتبة: افتح مشروع النص البرمجي للمكتبة في أداة تعديل النصوص البرمجية. لاختبار دوالّ المكتبة باستخدام وسيطات معيّنة، أنشِئ دالة "اختبار" مؤقتة داخل مشروع المكتبة تستدعي دوالّ المكتبة، ثم شغِّل دالة الاختبار هذه في وضع تصحيح الأخطاء.
• تسجيل الأحداث: استخدِم console.log() داخل دوالّ المكتبة لعرض المعلومات في سجلّات التنفيذ. عندما يستدعي نص برمجي آخر المكتبة، تظهر هذه السجلّات في سجلّات التنفيذ الخاصة بالنص البرمجي الذي يستدعيها.