ספריות

ספרייה היא פרויקט סקריפט שאפשר לעשות בו שימוש חוזר בפונקציות בסקריפטים אחרים.

אזהרה: סקריפט שמשתמש בספרייה לא פועל באותה מהירות שהיא הייתה רצה אם כל הקוד היה כלול בפרויקט סקריפט אחד. למרות שספריות יכולות להקל על הפיתוח והתחזוקה, כדאי להשתמש בהן באופן צר בפרויקטים שבהם המהירות קריטית. בגלל הבעיה הזו, השימוש בספרייה בתוספים צריך להיות מוגבל.

קבלת גישה לספרייה

כדי לכלול ספרייה בפרויקט, צריכה להיות לכם גישה אליה ברמת התצוגה לפחות. אם אינך המחבר של הספרייה שברצונך לכלול, עליך לפנות למחבר ולבקש גישה.

צריך לדעת את מזהה הסקריפט של הספרייה שרוצים לכלול. כשיש לכם גישה לספרייה, תוכלו למצוא את מזהה הסקריפט בדף של Project Settings.

הוספת ספרייה לפרויקט הסקריפטים

1. בצד ימין של העורך של Apps Script, לוחצים על הסמל להוספת ספרייה ליד 'ספריות'.
2. בשדה 'מזהה סקריפט', מדביקים את מזהה הסקריפט של הספרייה.
3. לוחצים על חיפוש.
   אם מקבלים שגיאה, צריך לוודא שיש לכם גישה לפחות ברמת התצוגה לפרויקט שאתם מנסים לכלול.
4. לוחצים על התפריט הנפתח Version ובוחרים את גרסת הספרייה שבה רוצים להשתמש.
5. כדאי לבדוק אם שם ברירת המחדל של 'Identifier' הוא השם שרוצים להשתמש בו בספרייה הזו. זה השם שבו הסקריפט משתמש כדי להתייחס לספרייה. לדוגמה, אם מגדירים אותה ל-Test, אפשר לקרוא ל-method של הספרייה הזו באופן הבא: Test.libraryMethod().
   אם אתם משתמשים בשם מזהה שתואם לשם של שירות קיים, כמו MailApp או ספרייה שהוספתם בעבר, הספרייה שהוספתם לאחרונה תבטל את השירות או הספרייה הקיימים.
6. לוחצים על Add (הוספה).

שימוש בספרייה

משתמשים בספרייה הכלולה כמו שמשתמשים בשירות ברירת מחדל. לדוגמה, אם Test הוא המזהה של הספרייה, מקלידים Test ומיד אחריה נקודה כדי לראות את רשימת השיטות בספרייה.

אפשר לפתוח את מאמרי העזרה של ספרייה כלולה באמצעות הפעולות הבאות:

מימין לכלי לעריכת סקריפטים, לצד שם הספרייה, לוחצים על סמל האפשרויות הנוספות > פתיחה בכרטיסייה חדשה.

הסרת ספרייה

מימין לכלי לעריכת סקריפטים, לצד שם הספרייה, לוחצים על סמל האפשרויות הנוספות > הסרה > הסרת הספרייה.

אם המחבר מחק את הספרייה, עדיין צריך להסיר אותה מרשימת הספריות הכלולות.

עדכון ספרייה

אפשר לשנות את גרסת הספרייה או לעדכן את המזהה שלה.

1. מימין לכלי העריכה, בקטע 'ספריות' לוחצים על שם הספרייה.
2. מבצעים את השינויים הרצויים ולוחצים על שמירה.

יצירה ושיתוף של ספרייה

כדי להשתמש בפרויקט הסקריפט ולשתף אותו כספרייה, צריך לפעול לפי השלבים הבאים.

1. יוצרים פריסה עם גרסאות של הסקריפט.
2. כדאי לשתף גישה ברמת תצוגה לפחות עם כל המשתמשים הפוטנציאליים בספרייה.
3. נותנים למשתמשים האלה את מזהה הסקריפט, שמופיע בדף של הגדרות הפרויקט.

שיטות מומלצות

הנה כמה הנחיות לכתיבת ספרייה:

1. חשוב לבחור שם בעל משמעות לפרויקט, כי הוא משמש כמזהה ברירת המחדל כשאחרים כוללים את הספרייה שלכם.
2. אם אתם רוצים שאחת או יותר מהשיטות של הסקריפט לא יהיו גלויות (או לא ניתנות לשימוש) למשתמשים בספרייה, תוכלו לסיים את שם ה-method עם קו תחתון. לדוגמה, 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 Sites, Sheets ומאגרים אחרים			קריאה ל-getActive() מחזירה את הקונטיינר של הסקריפט שכולל את הסקריפט.
MailApp ו-GmailApp
* המשמעות היא שלספרייה אין מופע משלה של התכונה או המשאב, ובמקום זאת היא משתמשת במופע שנוצר על ידי הסקריפט שהפעיל אותו. ** כלומר, לספרייה יש מופע משלה של המשאב או התכונה, ולכל הסקריפטים שמשתמשים בספרייה יש גישה לאותה מכונה ויש להם גישה אליה.

בדיקת ספרייה

כדי לבדוק את הספרייה, צריך להשתמש בפריסת כותרת. כל מי שיש לו גישה ברמת העורך לסקריפט יכול להשתמש בפריסת head.

עדיין צריכה להיות לפחות גרסה אחת של הספרייה השמורה.

ניפוי באגים בספרייה

כשמשתמשים בכלי לניפוי באגים בפרויקט שכולל ספרייה, אפשר להיכנס לפונקציה של הספרייה הכלולה. הקוד מופיע בכלי לניפוי באגים במצב תצוגה בלבד ובגרסה הנכונה.