Роли столбцов

На этой странице описывается концепция и использование ролей в таблицах данных диаграммы.

1. Что такое роли?
2. Какие роли доступны?
3. Иерархия ролей и ассоциативность
4. Назначение роли

Что такое роли?

Объекты Google DataTable и DataView теперь поддерживают явно назначенные роли столбцов . Роль столбца описывает назначение данных в этом столбце: например, столбец может содержать данные, описывающие текст всплывающей подсказки, аннотации точек данных или индикаторы неопределенности. Большинство ролей столбцов применяются к столбцу «данные», предшествующему ему, независимо от того, находится ли он непосредственно перед ним или перед первым из последовательной группы столбцов ролей. Например, у вас может быть два столбца после столбца «данные», один для «подсказки» и один для «аннотации». Но после столбца «домен» мы также обычно разрешаем роли столбцов «аннотация» и «аннотацияТекст».

Примечание. Если вы хотите управлять содержимым всплывающих подсказок, которые появляются, когда пользователь наводит курсор на диаграмму, см. раздел Подсказки .

Первоначально для столбца было доступно только две роли: «домен», определяющий значения главной оси; и «данные», которые определяют высоту столбца, ширину сегмента круговой диаграммы и т. д. Эти роли были назначены неявно, в зависимости от порядка и типа столбцов в таблице. Однако благодаря возможности явным образом назначать роли столбцов теперь можно добавлять необязательные столбцы, предоставляющие новые интересные функции для диаграммы, такие как произвольные метки аннотаций, всплывающий текст и столбцы неопределенности.

Если вы явно не назначаете роль столбца, его роль определяется порядком столбцов в таблице в соответствии со спецификацией формата данных диаграммы. На этой странице показано, какие роли доступны для явного назначения и как их назначать.

Вот сравнение того, что вы можете сделать с линейной диаграммой, используя только предполагаемые роли по умолчанию, по сравнению с дополнительными, явно назначенными ролями.

Формат таблицы данных линейной диаграммы :

	Столбец 0	Колонка 1	...	Колонка N
Цель	Групповые метки оси X ( дискретные ) Значения по оси X ( непрерывно )	Значения строки 1	...	Значения строки N
Тип данных	строка ( дискретная ) номер, дата, дата/время или время дня ( непрерывно )	количество	...	количество
Роль	домен	данные	...	данные
Дополнительно поддерживается роли столбца	аннотация аннотацияТекст	аннотация аннотацияТекст уверенность акцент интервал сфера стиль подсказка	...	аннотация аннотацияТекст уверенность акцент интервал сфера стиль подсказка

Диаграмма без явных ролей столбцов	Диаграмма с явными ролями столбцов
Эта диаграмма не применяет роли явно, поэтому может использовать только базовые данные и расположение столбцов домена, показанное выше. Таблица данных: 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] ]);	На этой диаграмме роли назначаются явно, поэтому можно добавлять необязательные столбцы. Эта диаграмма имеет необязательные столбцы для ролей аннотации, аннотацииТекст, интервала и достоверности. столбцы аннотаций задают статические метки на диаграмме; здесь «A», «B», «C» — аннотации. Столбцы annotationText определяют текст при наведении указателя мыши на аннотацию ( а не на точку данных). Столбцы интервалов определяют верхнюю и нижнюю точки I-баров на диаграмме. На графике есть три I-бара. столбцы достоверности указывают, являются ли данные в этой точке достоверными. Последняя точка данных является неопределенной, поэтому линия, ведущая к ней, обозначена пунктиром. Таблица данных: 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. Не все роли поддерживаются всеми типами диаграмм; документация каждой диаграммы будет описывать, какие роли доступны и куда они идут. Роли отображаются по-разному для разных типов диаграмм.

Роль	Описание	Пример
аннотация	Текст, отображаемый на диаграмме рядом с соответствующей точкой данных. Текст отображается без какого-либо взаимодействия с пользователем. Аннотации и текст аннотаций можно назначать как точкам данных, так и категориям (меткам осей). Существует два стиля аннотаций: точечный ( по умолчанию ), когда текст аннотации рисуется рядом с указанной точкой, и линия, когда текст аннотации рисуется на линии, которая делит область диаграммы пополам. Вы можете указать стиль линии, установив этот параметр диаграммы: annotations: {' column_id ': {style: 'line'}} Тип данных: строка По умолчанию: пустая строка	Данные: метка : «Год», «Продажи», null, null, «Расходы», null, null роль : домен, данные, аннотация, annotationText, данные, аннотация, annotationText '2004', 1000, null, null, 400, null, null '2005', 1170, null, null, 460, 'A', 'Разработка новой модели' '2006', 660, 'B', 'Запущена новая модель', 1120, null, null '2007', 1030, null , ноль, 540, ноль, ноль Буквы «А» и «В» на этой диаграмме являются аннотациями. Наведите курсор на аннотацию, чтобы увидеть текст аннотации. Обратите внимание, что вы должны навести указатель мыши на аннотацию, а не на точку данных, к которой она применяется, чтобы отобразить значение annotationText. Нулевые значения принимаются как для ячеек аннотаций, так и для ячеек annotationText; однако, если у вас есть значение annotationText, у вас должно быть соответствующее значение аннотации.
аннотацияТекст	Расширенный текст, отображаемый при наведении курсора на связанную аннотацию. Аннотации и текст аннотаций можно назначать как точкам данных, так и категориям (меткам осей). Если у вас есть столбец annotationText, у вас также должен быть столбец аннотаций. Текст всплывающей подсказки, напротив, отображается, когда пользователь наводит курсор на соответствующую точку данных на диаграмме. Тип данных: строка По умолчанию: пустая строка
уверенность	Указывает, является ли точка данных достоверной или нет. То, как это отображается, зависит от типа диаграммы — например, это может быть обозначено пунктирными линиями или полосатой заливкой. Для линейных и площадных диаграмм сегмент между двумя точками данных является определенным тогда и только тогда, когда обе точки данных являются определенными. Тип данных: boolean , где true — точно, 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 На этой диаграмме ряд «Продажи» имеет один выделенный сегмент, обозначенный третьим столбцом, первой и второй строками. Серия «Расходы» состоит из двух выделенных сегментов, обозначенных пятой колонкой, второй, третьей и четвертой строками. Обратите внимание, что выделение требует выделения обеих ограничивающих точек.
интервал	Указывает возможный диапазон данных для конкретной точки. Интервалы обычно отображаются в виде индикаторов диапазона в стиле I-bar. Интервальные столбцы — это числовые столбцы; добавьте интервальные столбцы попарно, отмечая минимальное и максимальное значение бара. Значения интервала следует добавлять в порядке возрастания слева направо. Тип данных: число По умолчанию: Без интервала	Данные: 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 На этой диаграмме значения интервалов определяют I-образную полосу, окружающую точки. Значения увеличиваются слева направо. Самый высокий и самый низкий интервалы вокруг точки отмечают верх и низ столбца. Примечание: все подробности об интервалах см. в разделе Интервалы .
сфера	Указывает, находится ли точка в области видимости или вне ее. Если точка выходит за рамки, она визуально не подчеркивается. Для линейных и площадных диаграмм сегмент между двумя точками данных находится в области действия, если в область действия входит любая конечная точка. Тип данных: boolean , где 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 Первый столбец области действия относится к столбцу данных «Продажи» слева от него. Первый сегмент визуализируется вне области видимости, поскольку обе граничные точки находятся вне области видимости. Второй столбец области действия относится к столбцу данных «Расходы» слева от него. Первый сегмент помечен как находящийся в области действия, поскольку одна из его граничных точек находится в области действия; остальная часть линии выходит за рамки, потому что все остальные точки помечены как не входящие в область действия.
стиль	Стилизует определенные свойства различных аспектов ваших данных. Эти значения: color opacity stroke-width stroke-color stroke-opacity fill-color fill-opacity Тип данных: строка , где можно применить несколько стилей, используя 'firstProperty: value; secondProperty: value' или задайте определенные стили для bar, line, и point , указав тип и заключив свойства стиля в фигурные скобки (например bar { //properties go here } ). По умолчанию: ноль	Данные: 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}' На этой диаграмме каждый столбец имеет стиль, независимый от других, с использованием роли столбца style . Стили могут быть установлены для точек, линий или столбцов конкретно (см. строку Человека-паука) или вообще, что применит стили ко всем точкам, линиям и столбцам, в зависимости от типа диаграммы. Примечание: дополнительные сведения о том, как настроить стиль точек , линий и столбцов , описаны в другом месте. Также см. параметры для каждого типа диаграммы, где можно указать стили для других типов объектов, таких как области, текст и поля.
подсказка	Текст, отображаемый при наведении курсора на точку данных, связанную с этой строкой. Примечание. Это не поддерживается визуализацией пузырьковой диаграммы . Содержимое всплывающих подсказок пузырьковой диаграммы в формате HTML не настраивается. Тип данных: строка По умолчанию: значение точки данных	Данные: 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 Этот пример демонстрирует многодоменную диаграмму. Первые два столбца данных изменяют первый домен ("Квартал 2009"), а последние два столбца данных изменяют второй домен ("Квартал 2008"). Оба домена накладываются на одну и ту же шкалу осей.
данные	Вам не нужно назначать эту роль явно; базовый формат таблицы данных позволяет механизму построения диаграмм определить, какие столбцы являются столбцами домена. Однако вы должны знать, какие столбцы являются столбцами данных, чтобы знать, какие другие столбцы могут их изменять. Столбцы роли данных определяют данные серии для отображения на диаграмме. Для большинства диаграмм один столбец = одна серия, но это может варьироваться в зависимости от типа диаграммы (например, точечная диаграмма требует два столбца данных для первой серии и дополнительный для каждой дополнительной серии; свечные диаграммы требуют четыре столбца данных для каждой серии ). Тип данных: число

Иерархия ролей и ассоциативность

На следующей диаграмме показано, какие столбцы ролей могут применяться к другим столбцам ролей. Все столбцы, кроме столбцов домена, применяются к ближайшему левому соседу , к которому он может быть применен.

Так, например, столбец области действия применяется к ближайшему столбцу данных слева от него; столбец annotationText будет применяться к ближайшему столбцу аннотаций слева от него; аннотация будет применяться к ближайшему столбцу данных или домена слева от него.

Назначение роли

Роли назначаются как свойство столбца в объекте DataTable. Существует несколько способов создания столбца ролей, но вот наиболее распространенные:

• DataTable.addColumn()
• Буквенное обозначение JavaScript
• DataView.setColumns()

Первые два метода рисуют следующую диаграмму:

Метод DataTable.addColumn

В следующем примере создается линейчатая диаграмма с маркером интервала на трех полосах. Маркеры интервалов задаются третьим и четвертым столбцами с помощью метода DataTable.addColumn() .

       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 необходимо указать свойство p столбца со значением "role":"role-type" . В следующем примере показано, как указать роли с помощью литеральной записи 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() для получения дополнительной информации.