مكتبات

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

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

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

تحتاج إلى معرّف النص البرمجي للمكتبة التي تريد تضمينها. عندما تتوفّر لك إمكانية الوصول إلى المكتبة، يمكنك العثور على رقم تعريف النص البرمجي في صفحة إعدادات المشروع 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);
  }

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

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

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

اختبار مكتبة

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

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

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