このページは Cloud Translation API によって翻訳されました。

グラフの種類を作成する

このページでは、独自のグラフの種類を開発して、ユーザーが利用できるようにする方法について説明します。

視聴者

このページは、グラフの使用ページを理解していることを前提としています。また、JavaScript とオブジェクト指向プログラミングに精通していることを前提としています。ウェブ上に多数ある JavaScript チュートリアルも参考にしてください。

グラフの作成

グラフは、作成した JavaScript ライブラリを通じてユーザーに公開されます。グラフライブラリを作成する手順は次のとおりです。

コードの名前空間を選択します。他のページはコードをホストします。名前が競合しないように注意してください。
Chart オブジェクトを実装する以下を公開する JavaScript オブジェクトを実装します。
- コンストラクタ、
- コンストラクタに渡される DOM 要素内にオブジェクトを描画する draw() メソッド
- クライアントが使用するその他の任意の標準メソッド（getSelection() など）
- クライアントに公開したいカスタムメソッド
[省略可] クライアントが検出するために配信するイベントを実装します。
グラフのドキュメントを作成します。文書化しないと、人々はその動画を埋め込めなくなる可能性があります。
グラフギャラリーにグラフを投稿する。

ヒント

goog.visualization API クラスとメソッド定義をダウンロードして、IDE（コードエディタ）でオートコンプリートを有効にしましょう。http://www.google.com/uds/modules/gviz/gviz-api.js からファイルをダウンロードしてプロジェクトに保存します。ほとんどの IDE では、自動的にインデックスが作成され、オートコンプリートが有効になります。ただし、IDE が異なる場合があります。このファイルは常に最新であるとは限りません。リファレンスページで、最新の API リファレンスをご確認ください。

名前空間を選択する

他のグラフや、その他の無関係な JavaScript をホストするページにグラフを埋め込むことができます。他のコードや CSS クラス名と競合しないように、グラフコードには一意の名前空間を選択する必要があります。名前空間を適切に選択するには、スクリプトのホストに使用する URL（WWW と任意の拡張機能を除く）を使用します。たとえば、グラフが www.example.com に投稿される場合は、example を一意の名前空間として使用します。別のサフィックスを . で区切って追加できます。マークはグラフをさらにグループ化するために使用します（Google のすべてのグラフに google.visualization 名前空間があります）。名前空間オブジェクトを使用して、グラフオブジェクトや、必要なグローバル変数を格納します。

以下に、MyTable という名前のグラフクラスと必要なグローバル変数を保持する Namespace オブジェクトを作成します。

// Namespace, implemented as a global variable.
var example = {};

// MyTable class constructor.
example.MyTable = function(container) {
  // ...
}

// MyTable.draw() method.
example.MyTable.prototype.draw = function(data, options) {
  // ...
}

CSS の競合の回避

CSS を使用する場合は、ページ上の他のグラフに影響する可能性のある CSS ルールを作成しないようにしてください。たとえば、td {color: blue;} のようなルールは、グラフだけでなくページの他の <td> 要素に影響するため、使用しないことを強くおすすめします。これを回避するには、グラフ全体をクラス名で <div> で囲み、すべての CSS ルールをそのクラス名の要素の子孫である要素にのみ適用します。たとえば、次の CSS ルールは、「祖先」としてクラス名「example」の要素を持つ <td> 要素にのみ影響します。

td.example {color: blue;}

次に、以下を使用してグラフを <div> でラップできます。

<div class="example">
  ...
</div>

グラフを実装する

リファレンスセクションに記載されている標準のメソッドを公開する JavaScript オブジェクトとしてチャートを実装する必要があります。必要な 2 つのメソッドは、コンストラクタメソッドと draw() メソッドです。グラフに適したその他のメソッドをユーザーに公開することもできます。使いやすいほどパフォーマンスが上がることを忘れないでください。

コンストラクタ

グラフには、単一のパラメータ（グラフの描画先となる DOM 要素）を受け取るコンストラクタを 1 つ公開する必要があります。通常、グラフは後で使用するために、この要素のローカルコピーをコンストラクタに格納します。

function example.MyTable(container) {
  this.container = container
}

`draw()` メソッド

グラフクラスには、グラフクラスのプロトタイプで定義されるメソッド draw() が必要です。draw() メソッドは次の 2 つのパラメータを受け入れます。

表示するデータを保持する DataTable。
グラフの名前/値オプションのマップ（省略可）。オプションの名前と値の型は、特定のグラフ用にユーザーが定義します。たとえば、以下の Hello Chart サンプルでは、Chart の値が Boolean 型の「showLineNumber」オプションをサポートしています。ユーザーが特定のオプションの値を渡さない場合に備えて、オプションごとにデフォルト値をサポートする必要があります。このパラメータは省略可能です。ユーザーがこのパラメータを渡さない場合は、すべてのデフォルト値を使用するように準備する必要があります（詳細）。

example.MyTable.prototype.draw = function(data, options) {
  // Process data and options and render output into the container element.
  ...
}

グラフへようこそ。

DataTable データを HTML テーブルとして表示する単純なグラフを次に示します。

以下に実装コードを示します。

// Declare a unique namespace.
var example = {};

// Class constructor. Parameter container is a DOM elementon the client that
// that will contain the chart.
example.MyTable = function(container) {
  this.containerElement = container;
}

// Main drawing logic.
// Parameters:
//   data is data to display, type google.visualization.DataTable.
//   options is a name/value map of options. Our example takes one option.
example.MyTable.prototype.draw = function(data, options) {

  // Create an HTML table
  var showLineNumber = options.showLineNumber; // Boolean configuration option.

  var html = [];
  html.push('<table border="1">');

  // Header row
  html.push('<tr>');
  if (showLineNumber) {
    html.push('<th>Seq</th>');
  }
  for (var col = 0; col < data.getNumberOfColumns(); col++) {
    html.push('<th>' + this.escapeHtml(data.getColumnLabel(col)) + '</th>');
  }
  html.push('</tr>');

  for (var row = 0; row < data.getNumberOfRows(); row++) {
    html.push('<tr>');
    if (showLineNumber) {
      html.push('<td align="right">', (row + 1), '</td>');
    }

    for (var col = 0; col < data.getNumberOfColumns(); col++) {
      html.push(data.getColumnType(col) == 'number' ? '<td align="right">' : '<td>');
      html.push(this.escapeHtml(data.getFormattedValue(row, col)));
      html.push('</td>');
    }
    html.push('</tr>');
  }
  html.push('</table>');

  this.containerElement.innerHTML = html.join('');
}

// Utility function to escape HTML special characters
example.MyTable.prototype.escapeHtml = function(text) {
  if (text == null)
    return '';
  return text.replace(/&/g, '&').replace(/</g, '<')
      .replace(/>/g, '>').replace(/"/g, '"');
}

グラフをウェブページに追加する

以前のグラフを使用するには、ブラウザからアクセスできる .js ファイルにグラフを保存します。次に、JavaScript ファイルを指すように <script> ソースパラメータを変更して、次のコードを保存します。

<html>
  <head>
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type="text/javascript" src="mytablevis.js"></script>
    <script type="text/javascript">
      google.charts.load("current");

      // Set callback to run when API is loaded
      google.charts.setOnLoadCallback(drawVisualization);

      // Called when the Chart API is loaded.
      function drawVisualization() {

        // Create and populate a data table.
        var data = new google.visualization.DataTable();
        data.addColumn('string', 'Task');
        data.addColumn('number', 'Daily Hours');
        data.addRows(5);
        data.setCell(0, 0, 'Work');
        data.setCell(0, 1, 11);
        // Add more data rows and cells here

        // Instantiate our table object.
        var vis = new example.MyTable(document.getElementById('mydiv'));

        // Draw our table with the data we created locally.
        vis.draw(data, {showLineNumber: true});
       }
   </script>
  <title>MyTable example page</title></head>
  <body>
    <div id="mydiv"></div>
    <p>This page demonstrates hosting a table visualization.</p>
  </body>
</html>

イベントを実装する

グラフで有用なイベント（タイマーイベントやクリックなどのユーザー開始イベントなど）を発生させたい場合は、イベントの詳細（名前、送信するプロパティなど）を指定して google.visualization.events.trigger 関数を呼び出す必要があります。詳細については、[イベント] ページをご覧ください。イベントオブジェクトにプロパティを追加してイベントの詳細をクライアントに示すか、グラフ上のなんらかのタイプの get...() メソッドを公開します。クライアントはそのメソッドを呼び出してイベントの詳細を取得できます。いずれの場合も、メソッドまたはイベントプロパティを適切に文書化します。

グラフの記録

グラフを適切にドキュメントしないと、多くのユーザーがアクセスできない可能性があります。必ず以下を記録してください。

サポートしているすべてのメソッドについて説明してください。draw() メソッドはすべてのグラフに共通ですが、各グラフでは独自の追加メソッドをサポートできます。（標準的でない動作がない限り、コンストラクタをドキュメント化する必要はありません）。想定されるメソッドのリストについては、リファレンスページをご覧ください。
draw() メソッドがサポートするオプションをすべて説明します。これには、各オプションの名前、期待される値の型、デフォルト値が含まれます。
トリガーするすべてのイベントを記述します。これは、各イベントの名前とプロパティ、および各イベントがトリガーされるタイミングを表します。
クライアントの <script> インクルードステートメントで使用するチャートライブラリの URL をリストし、ドキュメントの URL を明記してください。
グラフの完全修飾名を指定します。
サポートするオプション、イベント、カスタムメソッドを使用したグラフの使用方法を示すサンプルページを作成します。
グラフのデータポリシーを明示します。ほとんどのグラフはブラウザ内のデータを処理しますが、グラフや地図の画像を作成するなど、一部のグラフがサーバーに送信される場合もあります。サーバーにデータを送信する場合:
- 送信するデータを明確に定義
- データがサーバーに保存される期間をメモします。
- データにアクセスできるエンティティを文書化します。（例: XYZ 社など）。
- データを記録するかどうか、およびその期間を指定します。

ドキュメントは、グラフのコードと同じ場所でホストされます（下記のギャラリーにグラフを送信するをご覧ください）。

グラフをギャラリーに送信する

作成したグラフは送信して、ギャラリーの [その他のグラフ] セクションに投稿します。グラフを送信するということは、悪意のあるソフトウェアを作成したり、ユーザーデータを不正使用したりしないことについて、Google と契約を結ぶ必要があることを意味します。ギャラリーは、作成したグラフや審査したグラフのポインタのリストです。実際の JavaScript ライブラリやドキュメントを自分のサイトでホストすることも、Google でホストしてライブラリやドキュメントをホストすることもできます。グラフをギャラリーに投稿するときに、Google にチャートのホストを許可するかどうかを指定します。

トラブルシューティング

コードが機能していないと思われる場合は、次の方法をお試しください。

入力ミスを探します。JavaScript では大文字と小文字が区別されることに注意してください。
JavaScript デバッガを使用します。Firefox では、JavaScript コンソール、Venkman Debugger、または Firebug アドオンを使用できます。IE では、Microsoft Script Debugger を使用できます。
Google Chart API のディスカッショングループを検索します。質問に対する投稿が見つからない場合は、その問題を紹介するウェブページへのリンクを投稿してください。

ローカライズ

さまざまな国のユーザーが使用するグラフが必要な場合は、さまざまな言語や文化に合わせてグラフをローカライズすることをおすすめします。最も基本的なローカライズは、ユーザーのブラウザ設定に従って UI の標準テキスト文字列を翻訳することです。ローカライズの高度な方法としては、ローカライズに応じて UI の設計を変更することや、場合によっては数値形式を変更することが挙げられます。グラフをローカライズする場合は、グラフでサポートされている言語をドキュメントに記載し、よく使用される言語のデフォルト設定を指定します。また、言語を間違えた場合に備えて、グラフの UI に [言語を変更] ボタンを追加すると便利です。ブラウザの言語を検出する一般的な方法は、Accept-Language HTML ヘッダーを確認することです。