דף זה תורגם על ידי Cloud Translation API.

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

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

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

למעט כמה יוצאים מן הכלל, כל דפי האינטרנט עם תרשימים של 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 Listings. אם אתם רוצים לנסות את הגרסה הבאה, השתמשו במקום זאת ב-'upcoming'. באופן כללי, יהיה הבדל קטן מאוד בין השניים, והם יהיו זהים לחלוטין, למעט כשאנחנו מתכננים להשיק גרסה חדשה. סיבה נפוצה לשימוש ב-upcoming היא שאתם רוצים לבדוק סוג חדש של תכונה או תכונה ש-Google עומדת להשיק בחודש הבא. (אנחנו מכריזים על גרסאות עתידיות של הפורום

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

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

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

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

<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>

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

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

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

מגבלות

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

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

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

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

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

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

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

גרסאות הקפאה של התרשים מזוהות לפי מספר, והן מתוארות בגרסאות הרשמיות שלנו. כדי לטעון גרסה קפואה, צריך להחליף את 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) ההגדרה הזו מאפשרת לך לציין את המפתח שבו אתה יכול להשתמש עם תרשים תרשים ו תרשים מפה. ייתכן שעדיף לעשות זאת במקום להשתמש בהתנהגות ברירת המחדל שעלולה לגרום לויסות נתונים מדי פעם עבור המשתמשים. כאן אפשר ללמוד איך להגדיר מפתח משלך לשימוש בשירות 'API של מפות Google ל-JavaScript': קבלת מפתח/אימות. הקוד ייראה כך:

  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });

מצב בטוח

(v47) אם המדיניות מוגדרת כ-true, כל התרשימים וכל ההסברים שיוצרים HTML מנתונים שסופקו על ידי משתמשים יעברו ניקוי על ידי הסרת רכיבים ומאפיינים לא בטוחים. (גרסה 49 ואילך), אפשר לטעון את הספרייה במצב בטוח באמצעות קיצור דרך שמקבל את אותן הגדרות טעינה, אבל תמיד טוען את הגרסה "הנוכחית":

  google.charts.safeLoad({ packages: ['corechart'] });

לוקאלים

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

כברירת מחדל, התרשימים של Google נטענים עם הלוקאל "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. כדי לעשות זאת, עליך להוסיף קריאה לשיטה then() עם קוד שנראה כך.

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

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

עדכון קוד של הכלי לטעינת ספרייה

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

קוד נטען של ספרייה ישנה
<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>
קוד חדש של ספריית טעינה
<script src="https://www.gstatic.com/charts/loader.js"></script> <script> google.charts.load('current', {packages: ['corechart']}); google.charts.setOnLoadCallback(drawChart); </script>

קוד נטען של ספרייה ישנה

<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>

קוד חדש של ספריית טעינה

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

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

השלב הבא: הכנת הנתונים