ספריות

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

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

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

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

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

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

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

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

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

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

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

הסרת ספרייה

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

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

עדכון ספרייה

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

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

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

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

1. יוצרים פריסה עם גרסאות של הסקריפט.
2. שיתוף גישה ברמת התצוגה המפורטת לפחות עם כל המשתמשים הפוטנציאליים בספרייה.
3. נותנים למשתמשים האלה את מזהה הסקריפט, שאפשר למצוא בדף Project 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);
  }

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

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

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

בדיקת ספרייה

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

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

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

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