ספריות

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

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

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

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

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

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

1. בצד ימין של כלי העריכה של Apps Script, לצד 'ספריות', לוחצים על סמל הוספת ספרייה .
2. בשדה Script ID (מזהה סקריפט), מדביקים את מזהה הסקריפט של הספרייה.
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
* המשמעות היא שלספרייה אין מופע משלה של התכונה או המשאב, והיא משתמשת במשאב שנוצר על ידי הסקריפט שהפעיל אותה. ** כלומר, לספרייה יש מופע משלה של המשאב או התכונה וכל הסקריפטים שמשתמשים בספרייה חולקים את אותו המופע ויש להם גישה אליו.

בדיקת ספרייה

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

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

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

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