載入程式庫

本頁說明如何載入 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 圖表。如果想試用下一個版本,請改用 'upcoming'。一般來說,這兩者之間只會有微幅差異,除非新版本正在推出,否則一切都會完全相同。使用 upcoming 的常見原因是您想要測試 Google 即將在下個月或二月發布的新圖表類型或功能。(我們會在論壇上公布即將發布的版本,同時建議您在公告發布時進行試用,確保我們接受您對圖表所做的任何變更。)

上述範例假設您想顯示 corechart (長條、欄、行、區域、階梯區域、泡泡、圓餅圖、甜甜圈、連續關鍵圖、燭台、直方圖、散佈圖)。如果您需要其他或其他圖表類型,請在上述的 corechart 中替換或新增適當的套件名稱 (例如天氣為{packages: ['corechart', 'table', 'sankey']}。您可以在每張圖表的說明文件頁面的「載入中」部分找到套件名稱。

此範例也假設您在網頁的某處定義了名為 drawChart 的 JavaScript 函式。您可以視需要為函式命名,但該函式必須全域不重複,且在呼叫 google.charts.setOnLoadCallback 之前已定義該函式。

注意:舊版 Google 圖表使用的程式碼與上述版本不同,載入程式庫。如要將現有圖表更新為使用新程式碼,請參閱「更新程式庫載入器程式碼」。

以下是使用基本載入技術繪製圓餅圖的完整範例:

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

載入詳細資料

您必須先載入載入器本身,這項作業會使用 src="https://www.gstatic.com/charts/loader.js" 的個別 script 標記完成。這個標記可以位於文件的 headbody 中,也可以在載入或載入完成之後,以動態方式插入文件中。

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

載入載入程式後,您可以自由呼叫 google.charts.load。您可以在文件 headbodyscript 標記中呼叫該函式,也可以在文件載入期間或文件載入完成後隨時呼叫。

從 45 版開始,您「可以」多次呼叫 google.charts.load 來載入其他套件,但如果您可以避免這麼做,比較安全。每次都必須提供相同的版本號碼和語言設定。

您現在可以使用舊的 JSAPI autoload 網址參數,但這個參數的值必須使用嚴格的 JSON 格式和網址編碼。在 JavaScript 中,您可以使用下列程式碼進行 jsonObject 編碼:encodeURIComponent(JSON.stringify(jsonObject))

限制

如果您使用 45 版之前的版本,載入 Google 圖表的方式有幾項小但重要的限制:

  1. 您只能一次呼叫 google.charts.load。不過,您可以在一個呼叫中列出所需的所有套件,因此不必另外呼叫。
  2. 如果您使用 ChartWrapper,則必須明確載入所有需要的套件,而非仰賴 ChartWrapper 自動為您載入。
  3. 如果是 GeochartMap Chart,您必須同時載入舊版程式庫載入器和新版程式庫載入器。再次提醒,這「僅」適用於 v45 之前的版本,請「不要」對較新版本執行此操作。
    <script src="https://www.gstatic.com/charts/loader.js"></script>
    <script src="https://www.google.com/jsapi"></script>

載入版本號碼或編號

google.charts.load 呼叫的第一個引數是版本名稱或編號。目前只有兩個特殊版本名稱,以及數個凍結版本。

執行中
這是最新的官方版本,每次推出新版本時都會變更。理想情況下,這個版本經過充分測試且沒有錯誤,但建議您在滿意後改為指定特定的凍結版本。
即將啟用
這是下一個版本,不過仍處於測試階段,尚未成為目前的正式版本。請定期測試這個版本,以便在發布正式版之前盡快解決任何問題。

當我們發布新版 Google 圖表時,部分變更 (例如全新的圖表類型) 十分重要。其他變動則是微小的變動,例如強化現有圖表的外觀或行為。

許多 Google 排行榜創作者都會調整圖表的外觀與風格,直到滿意為止。部分創作者可能會更放心,無論未來我們做了哪些改善,他們的圖表都不會改變。針對這類使用者,我們支援凍結的 Google 圖表。

凍結圖表版本會依編號識別,詳情請參閱官方版本。如要載入凍結版本,請將 google.charts.load 呼叫中的 currentupcoming 替換為凍結版本號碼:

<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
這個語言或語言代碼的程式碼,應該要是自訂可能會列入圖表的一部分文字。詳情請參閱「語言代碼」一文。
回呼
套件載入後,會呼叫的函式。或者,您也可以按照上述範例呼叫 google.charts.setOnLoadCallback 來指定這個函式。詳情請參閱「回呼」。
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
mapsApiKey
(45 版) 這項設定可指定搭配地理區域圖地圖圖表使用的鍵。建議您不要採用預設行為,這樣可能會導致使用者偶爾無法使用服務。 如要瞭解如何自行設定金鑰以便使用「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 圖表載入時會採用「en」語言代碼。如要覆寫這項預設值,請在載入設定中明確指定語言代碼。

如要載入特定語言代碼格式的圖表,請使用 language 設定,如下所示:

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

請點選這個連結查看實際範例。

回撥電話

您必須先等待載入作業完成,才能使用 google.charts.load 載入的任何套件。只等待文件載入完成並不足夠。這項載入可能需要一段時間才能完成,因此您需要註冊回呼函式。方法有三種。請在 google.charts.load 呼叫中指定 callback 設定,或呼叫 setOnLoadCallback 將函式做為引數傳遞,或使用 google.charts.load 呼叫傳回的 Promise。

請注意,無論是上述哪一種方式,您都必須提供函式定義,而非呼叫函式。您提供的函式定義可以是已命名函式 (因此只需提供名稱) 或匿名函式。套件載入完畢後,不會有引數呼叫這個回呼函式。載入器也會等待文件載入完成後,再呼叫回呼。

如要繪製多個圖表,您可以使用 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 呼叫傳回的 Promise。方法是新增呼叫 then() 方法的程式碼,如下所示。

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

使用 Promise 有一個優點,就是只要鏈結更多 .then(anotherFunction) 呼叫,就能輕鬆繪製更多圖表。使用 Promise 也會將回呼連結至該回呼所需的特定套件,如果想透過另一個 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>
      

如要更新現有圖表,可以使用新程式碼取代舊的程式庫載入器程式碼。 但請注意,載入上述程式庫時設有的限制