本頁面由 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 圖表的官方版本。如果您要試用下一個版本的候選項目，請改用 'upcoming'。一般來說，兩者之間幾乎沒有任何差異，除非新發布進行中，否則這兩者完全相同。使用 upcoming 的常見原因是要測試 Google 即將在一兩個月內推出的新圖表類型或功能。(我們會在論壇上公布即將發布的版本，並建議在公告時試用，以確保系統可接受任何變更)。

上述範例假設您想要顯示 corechart (長條、欄、行、區域、階梯區、對話框、圓餅、甜甜圈、組合、蠟燭、直方圖、散佈)。如果想使用其他或額外的圖表類型，請針對上述 corechart 替換或新增適當的套件名稱 (例如：{packages: ['corechart', 'table', 'sankey']}。您可以在每個圖表說明文件頁面的「載入中」部分找到套件名稱。

此範例也假設您在網頁中某個位置定義了名為 drawChart 的 JavaScript 函式。您可以視需要為函式命名，但請務必為全域唯一定義，並在呼叫 google.charts.setOnLoadCallback 前加以定義。

注意：舊版 Google Chart 使用與上述不同的程式碼，以載入程式庫。如要將現有圖表更新為使用新程式碼，請參閱更新程式庫載入器程式碼。

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

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

載入詳細資料

首先，您必須載入具有載入器的載入器本身，該 SDK 會透過獨立的 script 標記和 src="https://www.gstatic.com/charts/loader.js" 完成。這個標記可以位於文件的 head 或 body 中，也可以在載入或載入完成之後動態插入文件中。

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

載入載入器後，即可呼叫 google.charts.load。呼叫位置位於文件 head 或 body 的 script 標記中，即可在文件仍在載入期間或載入完成後隨時呼叫該標記。

自第 45 版起，您「可能會」多次呼叫 google.charts.load 以載入其他套件，但為了避免安全，導致作業更加安全。您必須每次都提供相同的版本號碼和語言設定。

您現在可以使用舊版 JSAPI autoload 網址參數，但這個參數的值必須使用嚴格的 JSON 格式和網址編碼。在 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 Chart 時，有些變更的功能非常龐大，例如全新的圖表類型。其他變化較小，例如現有圖表的外觀或行為強化。

許多 Google Chart 創作者都會調整圖表的外觀和風格，直到完全呈現具體內容為止。部分創作者可能會覺得，無論我們日後的改善項目為何，他們的圖表都不會改變。對於這些使用者，我們支援凍結 Google 圖表。

冷凍圖表版本以編號表示，詳情請參閱官方版本。如要載入凍結版本，請將 google.charts.load 呼叫中的 current 或 upcoming 替換成凍結版本編號：

<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

(v45) 這項設定可讓您指定可搭配地理圖和地圖圖表使用的金鑰。建議您執行這項操作，而不要使用預設行為，否則可能會偶爾對使用者的服務受到限制。如要瞭解如何設定自己的「Google Maps JavaScript API」服務金鑰，請參閱這篇文章。程式碼應如下所示：

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

安全模式

(v47) 設為 true 時，所有透過使用者提供資料產生 HTML 的圖表和工具提示都會去除這些元素和屬性，藉此簡化處理作業。或者 (v49+)，您可以使用接受相同載入設定的捷徑，在安全模式下載入程式庫，但一律會載入「目前」版本：

  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 Chart 使用不同程式碼載入程式庫。下表列出了舊版程式庫載入器程式碼與新的程式碼。

舊程式庫載入器程式碼
<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>

如要更新現有圖表，您可以將舊的程式庫載入器程式碼替換成新程式碼。不過，請注意上述載入程式庫的限制。

下一步：準備資料