ספריות

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

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

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

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

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

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

1. בצד ימין של הכלי לעריכת סקריפטים של Apps Script, לצד 'ספריות', לוחצים על סמל הוספת ספרייה .
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) {
    const scriptProperties = PropertiesService.getScriptProperties();
    return scriptProperties.getProperty(key);
  }

התרשים הבא ממחיש משאב שלא משותף באמצעות הדוגמה של מאפייני סקריפט:

בטבלה הזו מפורטים המשאבים ששותפו והמשאבים שלא שותפו:

משאב	משותף*	לא משותף**	הערות
נעילה			אותו מופע גלוי לכולם, כולל סקריפטים, כשהוא נוצר בספרייה.
מאפייני הסקריפט			אותו מופע גלוי לכולם, כולל סקריפטים, כשהוא נוצר בספרייה.
מטמון			אותו מופע גלוי לכולם, כולל סקריפטים, כשהוא נוצר בספרייה.
טריגרים			טריגרים פשוטים שנוצרו בספרייה לא מופעלים על ידי הסקריפט שכולל אותם.
ScriptApp
UiApp
מאפייני משתמש
Logger ותעתיק הפעלה
אתרים, גיליונות אלקטרוניים ומאגרים אחרים			קריאה ל-getActive מחזירה את הקונטיינר של ה- כולל הסקריפט.
‫MailApp ו-GmailApp
* המשמעות היא שלספרייה אין מופע משלה של התכונה או המשאב, והיא משתמשת במקום זאת במופע שנוצר על ידי הסקריפט שהפעיל אותה. ** המשמעות היא שלספרייה יש מופע משלה של המשאב או התכונה וכל הסקריפטים שמשתמשים בספרייה חולקים את אותו המופע ויש להם גישה אליו.

בדיקת ספרייה

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

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

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

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

שימוש ב-HEAD (מצב פיתוח) לגרסת הספרייה לא מאפשר מעבר שלב אחר שלב בספרייה או הגעה לנקודות עצירה בתוכה.

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

• ניפוי באגים מפרויקט הספרייה: פותחים את פרויקט הסקריפט של הספרייה בכלי לעריכת סקריפטים של Apps Script. כדי לבדוק פונקציות של ספרייה עם ארגומנטים ספציפיים, יוצרים פונקציית בדיקה זמנית בפרויקט הספרייה שקוראת לפונקציות של הספרייה, ואז מריצים את פונקציית הבדיקה הזו במצב ניפוי באגים.
• רישום ביומן: אפשר להשתמש ב-console.log() בפונקציות של הספרייה כדי להוציא מידע ליומני הביצוע. כשספרייה נקראת על ידי סקריפט אחר, היומנים האלה מופיעים ביומני ההפעלה של הסקריפט הקורא.