المكتبات

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

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

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

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

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

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

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 مع ضبط 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
* يعني ذلك أنّ المكتبة لا تتضمّن نسخة خاصة بها من الميزة أو المورد، بل تستخدم النسخة التي أنشأها النص البرمجي الذي استدعاها. ** هذا يعني أنّ المكتبة تتضمّن نسخة خاصة بها من المورد/الميزة وأنّ جميع النصوص البرمجية التي تستخدم المكتبة تشارك هذه النسخة نفسها ويمكنها الوصول إليها.

اختبار مكتبة

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

يجب أن يكون لديك نسخة واحدة على الأقل من المكتبة محفوظة.

تصحيح أخطاء مكتبة

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

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

لتصحيح أخطاء رمز المكتبة، استخدِم إحدى الطرق التالية:

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