טעינת הספריות

בדף הזה מוסבר איך לטעון את ספריות התרשים של Google.

טעינת הספרייה הבסיסית

למעט כמה יוצאים מן הכלל, כל דפי האינטרנט שכוללים תרשימים של Google צריכים לכלול את השורות הבאות ב<head> של דף האינטרנט:

<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
  ...
</script>

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

הארגומנט הראשון של google.charts.load הוא שם הגרסה או מספר הגרסה, כמחרוזת. אם מציינים את הערך 'current', מתבצעת טעינה של הגרסה הרשמית האחרונה של Google Charts. אם אתם רוצים לנסות את המועמדים לגרסה הבאה, השתמשו במקום זאת ב-'upcoming'. באופן כללי, יהיה הבדל קטן מאוד בין השניים, והם יהיו זהים לחלוטין, חוץ מאשר כשיוצאים גרסה חדשה. סיבה נפוצה להשתמש ב-upcoming היא שרוצים לבדוק סוג תרשים חדש או תכונה חדשה ש-Google תשיק בחודש או חודשיים הבאים. (אנחנו מכריזים על סרטים חדשים בפורום שלנו, וממליצים לנסות אותם כשההודעה תפורסם, כדי לוודא שהשינויים בתרשימים יהיו מקובלים עליכם).

בדוגמה שלמעלה יצאנו מנקודת הנחה שאתם רוצים להציג corechart (עמודות, עמודות, קו, שטח, שטח מדורג, בועה, עוגה, דונאטס, שילוב, פמוט, היסטוגרמה, פיזור). אם רוצים סוג תרשים אחר או נוסף, מחליפים או מוסיפים את שם החבילה המתאים ל-corechart שלמעלה (למשל, {packages: ['corechart', 'table', 'sankey']}. שם החבילה מופיע בקטע 'טעינה' בדף התיעוד של כל תרשים.

הדוגמה הזו גם מבוססת על ההנחה שיש לכם פונקציית JavaScript בשם drawChart שמוגדרת במקום כלשהו בדף האינטרנט שלכם. אפשר לתת לפונקציה הזו כל שם שרוצים, אבל חשוב לוודא שהיא ייחודית בכל העולם ושהיא מוגדרת לפני שאתם מפנים אליה בקריאה אל google.charts.setOnLoadCallback.

הערה: כדי לטעון את הספריות, בגרסאות הקודמות של Google Charts נעשה שימוש בקוד שונה מזה שמופיע למעלה. כדי לעדכן את התרשימים הקיימים כך שישתמשו בקוד החדש, ראו Update Library Loader Code

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

<head>
  <script src="https://www.gstatic.com/charts/loader.js"></script>
  <script>
    google.charts.load('current', {packages: ['corechart']});
    google.charts.setOnLoadCallback(drawChart);

    function drawChart() {
      // Define the chart to be drawn.
      var data = new google.visualization.DataTable();
      data.addColumn('string', 'Element');
      data.addColumn('number', 'Percentage');
      data.addRows([
        ['Nitrogen', 0.78],
        ['Oxygen', 0.21],
        ['Other', 0.01]
      ]);

      // Instantiate and draw the chart.
      var chart = new google.visualization.PieChart(document.getElementById('myPieChart'));
      chart.draw(data, null);
    }
  </script>
</head>
<body>
  <!-- Identify where the chart should be drawn. -->
  <div id="myPieChart"/>
</body>

פרטי טעינה

קודם צריך לטעון את הטוען עצמו, שנוצר בתג script נפרד עם src="https://www.gstatic.com/charts/loader.js". אפשר להוסיף את התג הזה ב-head או ב-body של המסמך, או להוסיף אותו באופן דינמי למסמך בזמן הטעינה או אחרי שהטעינה מסתיימת. 

<script src="https://www.gstatic.com/charts/loader.js"></script>

לאחר טעינת ה-load, אפשר להתקשר למוקד של google.charts.load. אפשר לקרוא לו בתג script ב-head או ב-body של המסמך, ואפשר לקרוא לו גם בזמן שהמסמך עדיין בטעינה או בכל שלב אחרי שהוא מסתיים.

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

עכשיו אפשר להשתמש בפרמטר הישן של כתובת URL מסוג autoload JSAPI, אבל הערך של הפרמטר הזה צריך להשתמש בפורמט JSON מחמיר ובקידוד כתובות URL. ב-JavaScript, תוכלו לבצע את הקידוד של jsonObject באמצעות הקוד הבא: encodeURIComponent(JSON.stringify(jsonObject)).

מגבלות

אם אתם משתמשים בגרסאות שקדמו לגרסה 45, יש שתי מגבלות קטנות אבל חשובות באופן הטעינה של Google Charts:

  1. אפשר להתקשר אל google.charts.load פעם אחת בלבד. אבל אפשר לרשום את כל החבילות שצריך בשיחה אחת, כך שאין צורך לבצע שיחות נפרדות.
  2. אם משתמשים ב-ChartWrapper, צריך לטעון באופן מפורש את כל החבילות הנדרשות, במקום להסתמך על ChartWrapper כדי לטעון אותן באופן אוטומטי.
  3. עבור Geochart ו-Map Chart, צריך לטעון גם את טוען הספרייה הישן וגם את טוען הספריות החדש. שוב, האפשרות הזו חלה רק על גרסאות שלפני גרסה 45, ולא כדאי לעשות את זה בגרסאות מאוחרות יותר. 
    <script src="https://www.gstatic.com/charts/loader.js"></script>
<script src="https://www.google.com/jsapi"></script>

שם או מספר של גרסת הטעינה

הארגומנט הראשון של הקריאה אל google.charts.load הוא שם הגרסה או מספר הגרסה. יש כרגע רק שתי שמות של גרסאות מיוחדות, וכמה גרסאות שהוקפאו.

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

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

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

גרסאות קפואות של תרשים מזוהות לפי מספר ומתוארות בגרסאות הרשמיות. כדי לטעון גרסה שהוקפאה, מחליפים את current או את upcoming בשיחה של google.charts.load במספר הגרסה שהוקפאה:

<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
    google.charts.load('43', {packages: ['corechart']});
    google.charts.setOnLoadCallback(drawChart);
    ...
</script>

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

טעינת ההגדרות

הפרמטר השני בקריאה ל-google.charts.load הוא אובייקט לציון הגדרות. המאפיינים הבאים נתמכים בהגדרות.

חבילות
מערך של אפס חבילות או יותר. כל חבילה שנטענה תכלול את הקוד שנדרש כדי לתמוך בפונקציונליות, בדרך כלל סוג של תרשים. החבילות או החבילות שצריך לטעון מפורטות במסמכי התיעוד של כל סוג תרשים. אפשר להימנע מציון חבילות אם משתמשים ב-ChartWrapper כדי לטעון באופן אוטומטי את מה שיידרש.
language
הקוד של השפה או הלוקאל שאמורים להתאים אישית את הטקסט שעשוי להיות חלק מהתרשים. אפשר לקרוא פרטים נוספים בקטע לוקאלים.
קריאה חוזרת (callback)
פונקציה שתיפתח לאחר שהחבילות ייטענו. לחלופין, אפשר להגדיר את הפונקציה הזו על ידי קריאה ל-google.charts.setOnLoadCallback כפי שמוצג בדוגמה שלמעלה. אפשר לקרוא פרטים נוספים בקטע התקשרות חזרה. 
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
mapsApiKey
(v45) ההגדרה הזו מאפשרת לציין מַפְתח שאפשר להשתמש בו ב-Geochart וב-Map Chart. מומלץ לעשות זאת במקום להשתמש בהתנהגות ברירת המחדל שעלולה לגרום מדי פעם לויסות נתונים (throttle) של השירות עבור המשתמשים שלך. כאן מוסבר איך להגדיר מפתח משלכם לשימוש בשירות 'API JavaScript של מפות Google': קבלת מפתח/אימות. הקוד אמור להיראות כך: 
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
safeMode
(v47) אם המדיניות מוגדרת כ-True, כל התרשימים וההסברים הקצרים שיוצרים HTML מנתונים שסופקו על ידי משתמשים יטשטשו אותו ויסירו רכיבים ומאפיינים לא בטוחים. לחלופין (מגרסה 49 ואילך), אפשר לטעון את הספרייה במצב בטוח באמצעות קיצור דרך שמקבל את אותן הגדרות טעינה, אבל תמיד טוען את הגרסה ה'נוכחית': 
  google.charts.safeLoad({ packages: ['corechart'] });

לוקאלים

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

כברירת מחדל, נתוני Google Charts נטענים עם הלוקאל 'en'. אפשר לשנות את ברירת המחדל על ידי ציון לוקאל באופן מפורש בהגדרות הטעינה.

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

  // Load Google Charts for the Japanese locale.
  google.charts.load('current', {'packages':['corechart'], 'language': 'ja'});

אפשר ללחוץ על הקישור הזה כדי לראות דוגמה פעילה.

התקשרות חזרה

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

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

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

  google.charts.setOnLoadCallback(drawChart1);
  google.charts.setOnLoadCallback(drawChart2);
  // OR
  google.charts.setOnLoadCallback(
    function() { // Anonymous function that calls drawChart1 and drawChart2
         drawChart1();
         drawChart2();
      });

התקשרות חזרה באמצעות Promise

דרך נוספת לרשום את הקריאה החוזרת היא להשתמש בהבטחה שמוחזרת מהקריאה google.charts.load. כדי לעשות זאת, מוסיפים קריאה ל-method then() עם קוד שנראה כמו בדוגמה הבאה. 

  google.charts.load('upcoming', {packages: ['corechart']}).then(drawChart);

אחד היתרונות של השימוש ב-Promise הוא שאפשר לשרטט בקלות יותר תרשימים פשוט על ידי יצירת שרשור של יותר קריאות .then(anotherFunction). השימוש ב-Promise גם מקשר את הקריאה החוזרת לחבילות הספציפיות שנדרשות להתקשרות חזרה הזו, והיא חשובה אם רוצים לטעון יותר חבילות עם קריאה אחרת של google.charts.load().

עדכון הקוד של Library Loader

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

קוד של תוכנת הספרייה הישנה 
<script type="text/javascript" src="https://www.google.com/jsapi"></script>
<script type="text/javascript">
  google.load("visualization", "1", {packages:["corechart"]});
  google.setOnLoadCallback(drawChart);
</script>
קוד חדש של Directory Loader 
<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
</script>

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