المكتبات

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

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

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

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

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

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

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

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

يمكن فتح الوثائق المرجعية لمكتبة مضمنة باتباع الخطوات التالية:

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

إزالة مكتبة

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

تعديل مكتبة

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

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

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

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

1. أنشئ عملية نشر مستندة إلى إصدار من النص البرمجي.
2. شارِك إذن الوصول على مستوى العرض على الأقل مع جميع المستخدمين المحتملين للمكتبة.
3. امنح هؤلاء المستخدمين معرّف النص البرمجي، والذي يمكن العثور عليه في صفحة 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) {
    return ScriptProperties.getProperty(key);
  }

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

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

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

اختبار مكتبة

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

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

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