المكتبات

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

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

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

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

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

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

1. على يمين محرّر برمجة تطبيقات، انقر على "إضافة مكتبة" 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) {
    const scriptProperties = PropertiesService.getScriptProperties();
    return scriptProperties.getProperty(key);
  }

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

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

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

اختبار مكتبة

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

سيظلّ عليك حفظ نسخة واحدة على الأقل من المكتبة.

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

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

لا يتيح استخدام HEAD (وضع التطوير) لإصدار المكتبة إمكانية الانتقال إلى المكتبة أو الوصول إلى نقاط التوقّف داخلها.

لتصحيح أخطاء رمز المكتبة، استخدِم إحدى الطرق التالية:

• تصحيح الأخطاء من مشروع المكتبة: افتح مشروع نص المكتبة البرمجي في أداة تعديل النصوص البرمجية. لاختبار دوال المكتبة باستخدام وسيطات معيّنة، أنشئ دالة "اختبار" مؤقتة ضمن مشروع المكتبة تستدعي دوال المكتبة، ثم شغِّل دالة الاختبار هذه في وضع تصحيح الأخطاء.
• التسجيل: استخدِم console.log() ضمن دوال المكتبة لعرض المعلومات في سجلّات التنفيذ. عندما يستدعي نص برمجي آخر المكتبة، تظهر هذه السجلات في سجلات التنفيذ للنص البرمجي الذي يستدعي المكتبة.