本頁面由 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 圖表使用的程式碼與上述版本不同，載入程式庫。如要將現有圖表更新為使用新程式碼，請參閱「更新程式庫載入器程式碼」。

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

<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 標記完成。這個標記可以位於文件的 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 自動為您載入。
如果是 Geochart 和 Map 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 呼叫中的 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

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

舊版程式庫載入器程式碼

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

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

下一步：準備資料