المكتبات

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

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

الحصول على إذن بالوصول إلى مكتبة

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

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

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

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

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

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

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

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

إزالة مكتبة

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

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

تعديل مكتبة

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

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

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

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

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

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

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

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
خصائص المستخدمين
أداة التسجيل ونص التنفيذ
المواقع الإلكترونية و"جداول بيانات Google" والحاويات الأخرى			تؤدي الدعوة إلى getActive() إلى عرض حاوية النص البرمجي المضمّن.
MailApp وGmailApp
* هذا يعني أنّ المكتبة لا تحتوي على مثيل خاص بها للعنصر أو المورد، بل تستخدم بدلاً من ذلك المثيل الذي أنشأه النص البرمجي الذي استدعاه. ** يعني ذلك أنّ المكتبة لها مثيل خاص بها للمورد/الميزة وأنّ جميع النصوص البرمجية التي تستخدِم المكتبة تشارك هذا المثيل نفسه ويمكنها الوصول إليه.

اختبار مكتبة

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

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

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

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