ספריות

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

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

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

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

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

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

1. מימין בעורך Apps Script, ליד האפשרות 'ספריות', לוחצים על הסמל 'הוספת ספרייה' .
2. בשדה 'מזהה סקריפט', מדביקים את מזהה הסקריפט של הספרייה.
3. לוחצים על חיפוש.
   אם נתקלתם בשגיאה, ודאו שיש לכם לפחות גישה ברמת התצוגה המפורטת לפרויקט שאתם מנסים לכלול.
4. לוחצים על התפריט הנפתח Version [גרסה] ובוחרים את הגרסה של הספרייה שבה רוצים להשתמש.
5. צריך לבדוק אם שם ברירת המחדל של ה'מזהה' הוא השם שרוצים להשתמש בו בספרייה הזו. זה השם שבו הסקריפט שלכם ישתמש כדי להפנות לספרייה. לדוגמה, אם מגדירים אותה ל-Test, אפשר לקרוא לשיטה של אותה הספרייה באופן הבא: 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
מאפייני משתמש
תמליל של יומן הביצוע והרישום
Google Sites, Sheets ומאגרים אחרים			הקריאה ל-getActive() מחזירה את הקונטיינר של הסקריפט כולל.
MailApp ו-GmailApp
* המשמעות היא שלספרייה אין מופע משלה של התכונה או המשאב, ובמקום זאת היא משתמשת במופע שנוצר על ידי הסקריפט שהפעיל אותו. ** המשמעות היא שלספרייה יש מופע משלה של המשאב או התכונה, ושכל הסקריפטים שמשתמשים בספרייה חולקים את אותה מכונה ויש להם גישה לאותה מכונה.

בדיקת ספרייה

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

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

.

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

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