المكتبات

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

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

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

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

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

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

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

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

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

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

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

إزالة مكتبة

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

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

تعديل مكتبة

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

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

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

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

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

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

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

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

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

اختبار مكتبة

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

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

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

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