مكتبات

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

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

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

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

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

1. إلى يمين محرر النص البرمجي لـ Apps، انقر على "إضافة مكتبة 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);
  }

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

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

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

اختبار مكتبة

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

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

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