このページでは、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 グラフの最新の公式リリースが読み込まれます。次のリリースの候補を試す場合は、代わりに 'upcoming'
を使用してください。通常、両者の間にはほとんど違いはなく、新しいリリースが進行中の場合を除き、完全に同じです。upcoming
を使用する一般的な理由は、Google が今後 1 ~ 2 か月以内にリリースする新しいグラフタイプや機能をテストする場合です。(今後のリリースについてはフォーラムでお知らせします。お知らせされたら、グラフの変更が許容されるかどうかをテストすることをおすすめします)。
上記の例では、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
URL パラメータを使用できるようになりましたが、このパラメータの値には厳格な JSON 形式と URL エンコードを使用する必要があります。JavaScript では、encodeURIComponent(JSON.stringify(jsonObject))
というコードで jsonObject
をエンコードできます。
制限事項
v45 より前のバージョンを使用している場合、Google グラフの読み込み方法には、軽微ながら重要な制限がいくつかあります。
google.charts.load
は 1 回しか呼び出せません。ただし、必要なすべてのパッケージを 1 回の呼び出しでリストできるため、個別に呼び出す必要はありません。- 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
呼び出しの最初の引数は、バージョン名または番号です。現時点では、特別なバージョン名は 2 つと、フリーズされたバージョンがいくつかあります。
- 現在
- これは最新の公式リリース用で、新しいリリースがプッシュされるたびに変更されます。このバージョンは、テストが十分に行われ、バグがないことを確認するのが理想的ですが、動作に問題がないことを確認したら、代わりに特定のフリーズ バージョンを指定することをおすすめします。
- 今後
- テスト中であり、現行の公式リリースになる前の次のリリースを対象とします。このバージョンを定期的にテストして、このバージョンが公式リリースになる前に対処すべき問題があるかどうかをできるだけ早く把握できるようにしてください。
Google グラフの新しいバージョンがリリースされると、まったく新しいグラフの種類など、大きな変更が加えられます。その他の変更点は、既存のグラフの外観や動作の強化など、小さなものです。
多くの Google グラフ作成者は、希望どおりのグラフになるまでグラフの外観を微調整します。クリエイターによっては、YouTube が今後どのような改善を行っても、チャートは決して変わらないと認識している方もいらっしゃるかもしれません。そのようなユーザー向けに、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
の呼び出しの 2 つ目のパラメータは、設定を指定するオブジェクトです。設定でサポートされているプロパティは次のとおりです。
- 荷物
- 0 個以上のパッケージの配列。読み込まれる各パッケージには、一連の機能(通常はグラフの種類)をサポートするために必要なコードが含まれています。読み込む必要があるパッケージは、チャートの種類ごとにドキュメントに記載されています。ChartWrapper を使用して必要なものを自動的に読み込むと、パッケージを指定する必要がなくなります。
- language
- グラフの一部となるテキストをカスタマイズする必要がある言語またはロケールのコード。詳細については、言語 / 地域をご覧ください。
- callback
- パッケージが読み込まれると呼び出される関数。または、上記の例に示すように
google.charts.setOnLoadCallback
を呼び出してこの関数を指定することもできます。詳しくは、コールバックをご覧ください。google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
- mapsApiKey
- (v45)この設定では、Geochart とマップグラフで使用するキーを指定できます。この場合、ユーザーに対するサービスのスロットリングがときどき発生する可能性のある、デフォルトの動作を使用せずに、この方法を使用することをおすすめします。「Google Maps JavaScript API」サービスを使用するための独自のキーを設定する方法については、
キー/認証を取得するをご覧ください。コードは次のようになります。
var myMapsApiKey = 'SomeMagicToSetThis'; google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey });
- safeMode
- (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
によって読み込まれたパッケージを使用するには、読み込みが完了するまで待つ必要があります。ドキュメントの読み込みが完了するまで待つだけでは不十分です。この読み込みが完了するまでに時間がかかる可能性があるため、コールバック関数を登録する必要があります。これには次の 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 グラフでは、ライブラリの読み込みに別のコードを使用していました。次の表に、古いライブラリ ローダー コードと新しいライブラリ ローダー コードを示します。
古い Library Loader コード |
---|
<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> |
新しい Library Loader コード |
<script src="https://www.gstatic.com/charts/loader.js"></script> <script> google.charts.load('current', {packages: ['corechart']}); google.charts.setOnLoadCallback(drawChart); </script> |
既存のグラフを更新するには、古いライブラリ ローダのコードを新しいコードに置き換えます。ただし、上記のライブラリの読み込みに関する制限事項に注意してください。