مكتبات

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

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

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

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

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

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

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

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

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

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

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

إزالة مكتبة

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

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

تعديل مكتبة

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

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

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

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

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

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

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

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

اختبار مكتبة

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

لا تزال بحاجة إلى إصدار واحد على الأقل من المكتبة المحفوظة

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

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