本頁面由 Cloud Translation API 翻譯而成。

載入程式庫

本頁說明如何載入 Google 圖表程式庫。

基本程式庫載入

除了少數例外狀況，所有含有 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 (長條圖、柱狀圖、折線圖、面積圖、階梯狀面積圖、氣泡圖、圓餅圖、圓環圖、組合圖、K 線圖、直方圖、散布圖)。如果您想要使用其他或額外的圖表類型，請在上述 corechart 中替換或新增適當的套件名稱 (例如{packages: ['corechart', 'table', 'sankey']}。您可以在每個圖表的說明文件頁面「Loading」部分找到套件名稱。

這個範例也假設您在網頁中定義了名為 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。您可以呼叫 script 標記，在文件的 head 或 body 中呼叫，也可以在文件載入時或載入完成後的任何時間呼叫。

自 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 呼叫中的第二個參數是用於指定設定的物件。設定支援下列屬性。

packages

零或多個套件的陣列。每個載入的套件都會包含支援一組功能所需的程式碼，通常是某種圖表。需要載入的套件或套件會列在各圖表類型的說明文件中。如果您使用 ChartWrapper 自動載入所需的資料，可以避免指定任何套件。

language

語言或語言代碼，用於自訂可能會出現在圖表中的文字。詳情請參閱「語言代碼」。

回呼

載入套件後會呼叫的函式。或者，您也可以按照上述範例呼叫 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 的圖表和工具提示，都會去除不安全的元素和屬性，藉此清理資料。或者，您也可以使用接受相同載入設定的捷徑，在安全模式下載程式庫，但一律載入「目前」版本：

  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 圖表使用不同的程式碼載入程式庫。下表比較舊版與新版的程式庫載入器程式碼。

舊版 LibraryLoader 程式碼
<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>

舊版 LibraryLoader 程式碼

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

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

下一節：準備資料