المكتبات

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

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

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

يجب إدخال رقم تعريف النص البرمجي للمكتبة التي تريد تضمينها. عندما يكون لديك إذن الوصول إلى المكتبة، يمكنك العثور على رقم تعريف النص البرمجي في صفحة 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 والخصائص التي تم ضبطها صراحةً في الكائن العمومي. على سبيل المثال، عند ضبط enumerable على false، يُنشئ Object.defineProperty() رمزًا يمكنك استخدامه في مكتبتك، ولكن لا يمكن للمستخدمين الوصول إليه.

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

اختبار مكتبة

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

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

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