דף זה תורגם על ידי 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>

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

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

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

פרטי הטעינה

קודם צריך לטעון את ה-loader עצמו, באמצעות תג 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:

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

  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). יש שלוש דרכים לעשות זאת. אפשר לציין הגדרה של callback בקריאה ל-google.charts.load, או לקרוא ל-setOnLoadCallback ולהעביר פונקציה כארגומנט, או להשתמש ב-Promise שמוחזר על ידי הקריאה ל-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

דרך נוספת לרשום את פונקציית ה-callback היא להשתמש ב-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>
קוד חדש של מערך הטעינה של הספרייה
<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>

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

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