このページでは、グラフのデータテーブルにおけるロールのコンセプトと使用方法について説明します。
ロールとは
Google DataTable オブジェクトと DataView オブジェクトで、明示的に割り当てられた列のロールを使用できるようになりました。列のロールは、その列のデータの目的を記述します。たとえば、列には、ツールチップ テキスト、データポイントのアノテーション、不確実性インジケーターを説明するデータを保持できます。ほとんどの列ロールは、その前の「列」、つまり連続するロール列の最初のグループの前に適用されます。たとえば、「データ」列の後に「ツールチップ」用と「アノテーション」用として 2 つの列を作成できます。ただし、「domain」列を使用する場合、通常は「annotation」と「annotationText」列のロールも使用できます。
注: ユーザーがグラフにカーソルを合わせたときに表示されるツールチップの内容を制御する場合は、ツールチップをご覧ください。
もともと、列に対して使用できるロールは、長軸の値を指定する「domain」と、バーの高さや円グラフのスライスの幅などを指定する「data」の 2 つのみでした。これらのロールは、テーブル内の列の順序と種類に基づいて暗黙的に割り当てられます。ただし、列ロールを明示的に割り当てる機能を使用することで、任意のアノテーション ラベル、マウスオーバー テキスト、不確実性バーなどの興味深い機能をグラフに追加するオプション列を追加できるようになりました。
列の役割を明示的に割り当てない場合、そのロールは、グラフのデータ形式仕様に従って、テーブル内の列の順序によって推測されます。このページでは、明示的に割り当てることができるロールと、それらの割り当て方法について説明します。
ここでは、デフォルトの推定ロールのみを使用した折れ線グラフと、明示的に割り当てられたロールとの機能比較を比較します。
折れ線グラフのデータ表形式:
| 列 0 | 列 1 | … | N 列 | |
|---|---|---|---|---|
| 目的 | 行 1 の値 | … | 行 N の値 | |
| データの種類 | 数値 | … | 数値 | |
| ロール | domain | サポート | … | サポート |
| サポートされている任意の列 |
|
|
… |
|
| 明示的な列ロールを含まないグラフ | 明示的な列のロールを含むグラフ |
|---|---|
|
|
|
このグラフにはロールが明示的に適用されていないため、上記の基本的なデータとドメイン列のレイアウトのみを使用できます。 DataTable: var data = new google.visualization.DataTable();
data.addColumn('string', 'Month'); // Implicit domain label col.
data.addColumn('number', 'Sales'); // Implicit series 1 data col.
data.addRows([
['April',1000],
['May', 1170],
['June', 660],
['July', 1030]
]); |
このグラフではロールが明示的に割り当てられています。これにより、オプションの列を追加できます。このグラフには、アノテーション、アノテーション テキスト、間隔、確実性のロールのオプション列があります。
DataTable: var data = new google.visualization.DataTable();
data.addColumn('string', 'Month'); // Implicit domain label col.
data.addColumn('number', 'Sales'); // Implicit series 1 data col.
data.addColumn({type:'number', role:'interval'}); // interval role col.
data.addColumn({type:'number', role:'interval'}); // interval role col.
data.addColumn({type:'string', role:'annotation'}); // annotation role col.
data.addColumn({type:'string', role:'annotationText'}); // annotationText col.
data.addColumn({type:'boolean',role:'certainty'}); // certainty col.
data.addRows([
['April',1000, 900, 1100, 'A','Stolen data', true],
['May', 1170, 1000, 1200, 'B','Coffee spill', true],
['June', 660, 550, 800, 'C','Wumpus attack', true],
['July', 1030, null, null, null, null, false]
]); |
使用可能なロール
次の表に、Google Charts がサポートするすべてのロールを示します。すべてのロールがすべてのグラフタイプでサポートされているわけではありません。各グラフのドキュメントでは、利用できるロールとその位置について説明しています。グラフの種類によってロールのレンダリング方法が異なります。
| ロール | 説明 | 例 |
|---|---|---|
| アノテーション | 関連付けられているデータポイントの近くのグラフに表示するテキスト。ユーザーの操作なしでテキストが表示されます。アノテーションとアノテーション テキストは、データポイントとカテゴリ（軸ラベル）の両方に割り当てることができます。 アノテーションには、指定されたポイントの近くにアノテーション テキストを描画するポイント（デフォルト）と、グラフ領域を二等分する線にアノテーション テキストを描画する線の 2 種類があります。線のスタイルを指定するには、次のグラフ オプションを設定します。 データ型: string デフォルト: 空の文字列 |
データ: label
このグラフの「A」と「B」はアノテーションです。アノテーションにカーソルを合わせると、アノテーション テキストが表示されます。annotationText の値を表示するには、適用対象のデータポイントではなく、アノテーションにカーソルを合わせてください。 annotation セルと annotationText セルの両方に null 値を使用できます。ただし、annotationText 値がある場合は、関連付けられたアノテーション値が必要です。 |
| annotationText | 関連するアノテーションにカーソルを合わせると表示される拡張テキスト。アノテーションとアノテーション テキストは、データポイントとカテゴリ（軸ラベル）の両方に割り当てることができます。annotationText 列がある場合は、アノテーション列も必要です。一方、ツールチップのテキストは、ユーザーがグラフに関連付けられているデータポイントにカーソルを合わせると表示されます。 データ型: string デフォルト: 空の文字列 |
|
| 確実性 | データポイントが確定しているかどうかを示します。表示形式はグラフの種類によって異なります。たとえば、破線や縞模様で示される場合があります。 折れ線グラフと面グラフでは、2 つのデータポイント間のセグメントは、両方のデータポイントが同一である場合にのみ確実になります。 データ型: boolean。true は確定、false は不確定です。 デフォルト: true |
|
| 強調 | グラフの特定のデータポイントを強調します。太い線や大きい点として表示される。 折れ線グラフと面グラフでは、両方のデータポイントが強調されている場合のみ、2 つのデータポイント間のセグメントが強調されます。 データ型: boolean デフォルト: false |
データ: label: 'Year', 'Sales', null, 'Expenses', null
role: domain, data, emphasis, data, emphasis
'2004', 1000, true, 400, false
'2005', 1170, true, 460, true
'2006', 660, false, 1120, true
'2007', 1030, false, 540, true
このグラフでは、「販売」シリーズに列 3、行 1、行 2 で示されている強調セグメントが 1 つあります。「経費」シリーズには、5 列目、2 行目、3 行目、4 列目という 2 つの強調セグメントがあります。強調を行う際は、両方の境界点を強調する必要があります。 |
| 間隔 | 特定の地点で想定されるデータ範囲を示します。間隔は通常、I バーのスタイル範囲インジケーターとして表示されます。間隔列は数値列で、ペアとして間隔列を追加し、棒の下限と上限をマークします。間隔の値は左から右へ順に値を増やします。 データ型: number デフォルト: 間隔なし |
データ: label: 'Day', 'Stock value', null, null
role: domain, data, interval, interval
'Mon', 38, 20, 45
'Tue', 55, 31, 66
'Wed', 77, 50, 80
'Thurs', 66, 50, 77
このグラフでは、interval 値がポイントを囲む I バーを定義しています。値は左から右に増加します。 地点を囲む最高と最低の間隔は、バーの上下に表示されます。 注: 間隔の詳細については、間隔をご覧ください。 |
| 範囲 | ポイントがスコープに含まれるかどうかを示します。ポイントがスコープ外の場合、視覚的な強調は解除されます。 折れ線グラフと面グラフでは、エンドポイントのいずれかがスコープに含まれる場合、2 つのデータポイント間のセグメントがスコープに含まれます。 データ型: boolean。true は対象範囲です。 デフォルト: true |
データ: label: 'Year', 'Sales', null, 'Expenses', null
role: domain, data, scope, data, scope
'2004', 1000, false, 400, true
'2005', 1170, false, 460, false
'2006', 660, true, 1120, false
'2007', 1030, true, 540, false
最初の適用範囲の列は、左側の「販売」データ列に適用されます。最初の境界線はスコープ外のため、両方の境界点は範囲外です。2 番目のスコープ列は、左側の [Expenses] データ列に適用されます。最初のセグメントはスコープ内の 1 つのスコープに含まれるため、対象範囲外としてマークされます。それ以外のポイントは範囲外としてマークされています。 |
| スタイル |
データのさまざまな側面の特定のプロパティのスタイルを設定します。これらの値は次のとおりです。
データ型: 文字列。 デフォルト: null |
データ:
label: 'Character', 'Popularity', 'Style',
role: domain, data, style,
'Hulk', 50, 'color: green',
'Captain America', 75, 'color: #0000cf;' +
'stroke-color: #cf001d',
'Wolverine', 90, 'opacity: 0.5;' +
'stroke-width: 5;' +
'stroke-color: #01a0ff;' +
'fill-color: #fff600',
'Iron Man', 60, 'color: #db9500;' +
'stroke-width: 10;' +
'stroke-color: #a30300',
'Spider Man', 100, 'bar {' +
'fill-color: #c8001d;' +
'stroke-width: 3;' +
'stroke-color: #1800c8}'
このグラフでは、各棒のスタイルは 注: 詳しくは、ポイント、ライン、バーのスタイルをカスタマイズする方法に関する詳細をご覧ください。グラフの種類ごとに、領域、テキスト、ボックスなど、他の種類のエンティティにスタイルを指定することもできます。 |
| ツールチップ |
この行に関連付けられたデータポイントにユーザーがカーソルを合わせたときに表示するテキスト。 注: これは、バブルチャートの可視化ではサポートされていません。バブルチャートの HTML ツールチップのコンテンツはカスタマイズできません。 データ型: string デフォルト: データポイントの値 |
データ: label: 'Year', 'Sales', null, 'Expenses', null
role: domain, data, tooltip, data, tooltip
'2004', 1000, '1M$ sales, 400, '$0.4M expenses
in 2004' in 2004'
'2005', 1170, '1.17M$ sales, 460, '$0.46M expenses
in 2005' in 2005'
'2006', 660, '.66$ sales, 1120, '$1.12M expenses
in 2006' in 2006'
'2007', 1030, '1.03M$ sales, 540, '$0.54M expenses
in 2007' in 2007'
データポイントにカーソルを合わせると、ツールチップ テキストが表示されます。ツールチップ データは、列 3 と列 5 の両行のすべてのポイントに割り当てられます。 注: ツールチップのカスタマイズについて詳しくは、ツールチップをご覧ください。 |
| ドメイン | マルチドメイン グラフ（図を参照）を設計しない限り、このロールを明示的に割り当てる必要はありません。データテーブルの基本形式では、グラフエンジンがどの列をドメイン列なのかを推測できます。ただし、他のどの列がドメイン列なのかを把握できるように、どの列がドメイン列なのかを把握しておく必要があります。 ドメイン列では、グラフの長軸に沿ってラベルを指定します。同じグラフ内で複数のドメイン列を使用して、複数のスケールをサポートすることがあります。 データ型: 通常は文字列、ただし時折数値または日付 |
データ:
label: '2009, '2009, '2009, '2008, '2008 '2008
Quarter', Sales', Expenses', Quarter', Sales', Expenses'
role: domain, data, data, domain, data, data
'Q1/09', 1000, 400, 'Q1/08', 800, 300
'Q2/09', 1170, 460, 'Q2/08', 750, 400
'Q3/09', 660, 1120, 'Q3/08', 700, 540
'Q4/09', 1030, 540, 'Q4/08', 820, 620
この例では、マルチドメインのグラフを示しています。最初の 2 つのデータ列は、最初のドメイン（「2009 四半期」）を変更し、最後の 2 つのデータ列は、2 番目のドメイン（「2008 四半期」）を変更します。両方のドメインが同じ軸スケールでオーバーレイされます。 |
| データ | このロールを明示的に割り当てる必要はありません。データテーブルの基本形式では、グラフエンジンがどの列をドメイン列なのかを推測できます。ただし、他のどの列がデータ列なのかを把握できるように、どの列がデータ列なのかを把握しておく必要があります。 データロールの列では、グラフに表示する時系列データを指定します。ほとんどのグラフでは 1 列 = 1 系列ですが、これはグラフの種類によって異なります（たとえば、散布図では最初のシリーズに 2 つのデータ列、追加の系列ごとに 1 つのデータ列が必要です）。ローソク足チャートにはシリーズごとに 4 つのデータ列が必要です。 データ型: number |
ロールの階層と関連付け
次の図は、どのロール列を他のロール列に適用できるかを示しています。ドメイン列を除くすべての列は、適用先の最も近い近隣地域に適用されます。
たとえば、scope 列が左端の data 列に適用され、annotationText 列が左側に最も近い annotation 列に適用されます。annotation は左側に最も近い data 列または domain 列に適用されます。
ロールの割り当て
ロールは、DataTable オブジェクトの列のプロパティとして割り当てられます。ロール列を作成する方法はいくつかありますが、最も一般的なものを以下に示します。
最初の 2 つの手法は、以下のグラフを表しています。
DataTable.addColumn メソッド
次の例では、3 つの棒に間隔マーカーを含む棒グラフを作成しています。間隔マーカーは、DataTable.addColumn() メソッドを使用して 3 列目と 4 列目で指定します。
var data = new google.visualization.DataTable();
data.addColumn('string', 'Month'); // Implicit domain column.
data.addColumn('number', 'Sales'); // Implicit data column.
data.addColumn({type:'number', role:'interval'});
data.addColumn({type:'number', role:'interval'});
data.addColumn('number', 'Expenses');
data.addRows([
['April',1000, 900, 1100, 400],
['May', 1170, 1000, 1200, 460],
['June', 660, 550, 800, 1120],
['July', 1030, , , 540]
]);
var chart = new google.visualization.BarChart(
document.getElementById('visualization'));
chart.draw(data,
{width: 800, height: 600, title: 'Company Performance'});
JavaScript のリテラル表記
JSON リテラルでは、値 "role":"role-type" を使用して列の p プロパティを指定する必要があります。次の例は、JavaScript のリテラル表記を使用してロールを指定する方法を示しています。これは、テーブルの作成時にのみ行うことができます。
{"cols":[
{"id":"","label":"Month","pattern":"","type":"string"},
{"id":"","label":"Sales","pattern":"","type":"number"},
{"id":"","label":"","pattern":"","type":"number","p":{"role":"interval"}},
{"id":"","label":"","pattern":"","type":"number","p":{"role":"interval"}},
{"id":"","label":"Expenses","pattern":"","type":"number"}],
"rows":[
{"c":[
{"v":"April","f":null},
{"v":1000,"f":null},
{"v":900,"f":null},
{"v":1100,"f":null},
{"v":400,"f":null}]},
{"c":[
{"v":"May","f":null},
{"v":1170,"f":null},
{"v":1000,"f":null},
{"v":1200,"f":null},
{"v":460,"f":null}]},
{"c":[{"v":"June","f":null},
{"v":660,"f":null},
{"v":550,"f":null},
{"v":800,"f":null},
{"v":1120,"f":null}]},
{"c":[
{"v":"July","f":null},
{"v":1030,"f":null},
{"v":null,"f":null},
{"v":null,"f":null},
{"v":540,"f":null}]}],
"p":null
}
DataView.setColumns メソッド
ビューを作成するときに、列のロールを明示的に設定できます。これは、新しい計算列を作成する際に役立ちます。詳しくは、DataView.setColumns() をご覧ください。