ライブラリを読み込む

このページでは、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>

この例の最初の行で、ローダ自体が読み込まれます。 ローダは、何枚でもグラフを描画しても 1 回だけ読み込むことができます。ローダを読み込んだ後、google.charts.load 関数を 1 回以上呼び出して、特定のグラフタイプのパッケージを読み込むことができます。

google.charts.load の最初の引数は、バージョン名または番号を文字列として表したものです。'current' を指定すると、Google Chart の最新の公式リリースが読み込まれます。次のリリースの候補を試す場合は、代わりに 'upcoming' を使用してください。一般的にこの 2 つに大きな違いはなく、新しいリリースが進行中の場合を除き、完全に同じになります。upcoming を使用する一般的な理由は、Google が今後数か月または 2 月にリリースする新しいグラフの種類や機能をテストする場合です。(今後のリリースをフォーラムで発表します。発表時に試し、グラフが変更されても問題がないことを確認することをおすすめします)。

上の例では、corechart(棒グラフ、列、折れ線、面積、階段状の領域、バブル、円グラフ、ドーナツ、コンボ、ろうそくスティック、ヒストグラム、散布図)を表示することを前提としています。別のグラフ タイプや追加のグラフの種類が必要な場合は、上記の corechart の適切なパッケージ名を代用または追加します(例:{packages: ['corechart', 'table', 'sankey']}。パッケージ名は、各グラフのドキュメント ページの「読み込み」セクションにあります。

この例では、drawChart という JavaScript 関数がウェブページのどこかで定義されていることを前提としています。関数には任意の名前を付けることができますが、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>

読み込みの詳細

まず、ローダ自体を読み込む必要があります。読み込みは、src="https://www.gstatic.com/charts/loader.js" を使用して別個の script タグで行います。このタグは、ドキュメントの headbody のいずれかです。あるいは、読み込み中または読み込みが完了した後に、ドキュメントに動的に挿入することもできます。

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

ローダが読み込まれると、google.charts.load を呼び出すことができます。呼び出す場所は、ドキュメントの head または bodyscript タグです。ドキュメントの読み込み中でも、読み込みが完了した後でも呼び出すことができます。

バージョン 45 以降では、追加のパッケージを読み込むために google.charts.load を複数回呼び出すことができますが、できれば保護することをおすすめします。これを行う場合は、毎回同じバージョン番号と言語設定を指定する必要があります。

従来の JSAPI の autoload URL パラメータを使用できるようになりましたが、このパラメータの値は厳格な JSON 形式と URL エンコードを使用する必要があります。JavaScript では、encodeURIComponent(JSON.stringify(jsonObject)) のコードを使用して jsonObject のエンコードを行うことができます。

制限事項

v45 より前のバージョンを使用している場合、Google Chart の読み込み方法には、いくつかの小さな制限があります。

  1. google.charts.load は 1 回だけ呼び出すことができます。ただし、必要なパッケージはすべて 1 回の呼び出しで一覧表示できるため、別の呼び出しを行う必要はありません。
  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 呼び出しの最初の引数は、バージョン名または番号です。現時点で特別なバージョン名は 2 つのみで、固定バージョンが複数あります。

最新
これは、新しいリリースが公開されるたびに変更される、最新の公式リリース向けです。このバージョンは十分にテストされており、バグがないことが理想的ですが、動作が確認できたら特定の固定バージョンを指定することもできます。
今後
これは、次のリリースがテスト段階であり、正式に現在のリリースになる前です。このバージョンを定期的にテストして、このバージョンが公式リリースされる前に対処すべき問題がないか、できるだけ早く確認してください。

Google Chart の新しいバージョンをリリースするとき、まったく新しいタイプのグラフなど、大きな変更もあります。その他の変更には、既存のグラフの外観や動作の改善などがあります。

Google Chart のクリエイターの多くは、グラフが意図したとおりに表示されるまで、デザインを微調整します。クリエイターによっては、今後どのような改善があってもグラフが変わらないことを安心できるでしょう。そのようなユーザーのために、Google は凍結された Google Chart をサポートしています。

フリーズしたチャート バージョンは番号で特定され、公式リリースに記載されています。固定されたバージョンを読み込むには、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 の 2 番目のパラメータは、設定を指定するオブジェクトです。設定では次のプロパティがサポートされています。

荷物
0 個以上のパッケージの配列。読み込まれる各パッケージには、一連の機能(通常はグラフのタイプ)のサポートに必要なコードが含まれています。読み込む必要があるパッケージは、各タイプのグラフのドキュメントに記載されています。ChartWrapper を使って必要なものを自動的に読み込む場合、パッケージの指定を回避できます。
language
グラフの一部に使われるテキストをカスタマイズするために使用する言語または地域のコード。詳しくは、言語 / 地域をご覧ください。
callback
パッケージの読み込み後に呼び出される関数。また、上の例のように 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 Charts に「en」ロケールが読み込まれます。このデフォルト設定をオーバーライドするには、読み込み設定でロケールを明示的に指定します。

特定のロケールにフォーマットされたグラフを読み込むには、次のように language 設定を使用します。

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

実際の例については、こちらのリンクをご覧ください。

コールバック

google.charts.load が読み込んだパッケージを使用するには、読み込みが完了するまで待つ必要があります。ドキュメントの読み込みが完了するまで待つだけでは不十分です。この読み込みが完了するまでに時間がかかることがあるため、コールバック関数を登録する必要があります。これには、次の 3 つの方法があります。google.charts.load 呼び出しで callback の設定を指定するか、関数を引数として渡して setOnLoadCallback を呼び出すか、google.charts.load の呼び出しによって返される Promise を使用します。

これらすべてのメソッドでは、関数を呼び出すのではなく、関数の定義を指定する必要があります。指定する関数の定義には、名前付き関数(名前のみを指定する)と匿名関数のいずれかを指定できます。 パッケージの読み込みが完了すると、このコールバック関数は引数なしで呼び出されます。ローダは、ドキュメントの呼び出しが完了するまで待機してから、コールバックを呼び出します。

複数のグラフを描画する場合は、setOnLoadCallback を使用して複数のコールバック関数を登録するか、1 つの関数にまとめることができます。詳しくは、1 つのページに複数のグラフを描画する方法をご覧ください。

  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 を使用するメリットの 1 つは、より多くの .then(anotherFunction) 呼び出しを連結するだけで、簡単にグラフを描画できるようになることです。また、Promise を使用すると、コールバックは特定のコールバックに必要なパッケージに関連付けられます。これは、google.charts.load() の別の呼び出しで追加のパッケージを読み込む場合に重要です。

ライブラリのローダコードを更新する

以前のバージョンの 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>
      

既存のグラフを更新するには、ライブラリの古いローダコードを新しいコードに置き換えます。 ただし、前述のライブラリの読み込みに関する制限に注意してください。