ספריות

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

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

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

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

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

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

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

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

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

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

הסרת ספרייה

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

עדכון ספרייה

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

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

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

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

1. יוצרים פריסה עם גרסאות של הסקריפט.
2. שיתוף גישה ברמת התצוגה המפורטת לפחות עם כל המשתמשים הפוטנציאליים בספרייה.
3. נותנים למשתמשים האלה את מזהה הסקריפט, שאפשר למצוא בדף settings 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) {
    const scriptProperties = PropertiesService.getScriptProperties();
    return scriptProperties.getProperty(key);
  }

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

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

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

בדיקת ספרייה

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

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

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