Создание типов диаграмм

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

Аудитория

На этой странице предполагается, что вы прочитали страницу «Использование диаграмм» . Также предполагается, что вы знакомы с JavaScript и объектно-ориентированным программированием. В Интернете доступно множество руководств по JavaScript .

Создание диаграммы

Диаграммы предоставляются пользователю через созданную вами библиотеку JavaScript. Вот шаги для создания библиотеки диаграмм:

  1. Выберите пространство имен для вашего кода. На других страницах будет размещаться ваш код; вам следует стараться избегать конфликтов имен.
  2. Реализуйте свой объект диаграммы. Реализуйте объект JavaScript, который предоставляет следующее:
    • Конструктор,
    • Метод draw() для рисования объекта внутри элемента DOM, передаваемого конструктору.
    • Любые другие дополнительные стандартные методы, которые может использовать клиент, например getSelection() и
    • Любые пользовательские методы, которые вы хотите предоставить своим клиентам.
  3. [ Необязательно ] Реализуйте любые события , которые вы хотите инициировать, чтобы клиент мог их перехватить.
  4. Напишите документацию для вашей диаграммы. Если вы не задокументируете это, люди, вероятно, не смогут встроить это.
  5. Опубликуйте свою диаграмму в галерее диаграмм.

Кончик

  • Вы можете загрузить класс API goog.visualization и определения методов, чтобы включить автозаполнение в вашей 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, 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 будет влиять только на элементы <td> , предком которых является элемент с именем класса «example».

td.example {color: blue;}

Затем вы можете обернуть диаграмму в <div> с помощью:

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

Реализуйте свою диаграмму

Вам потребуется реализовать диаграмму как объект JavaScript, который предоставляет стандартные методы, описанные в разделе «Справочник» . Два обязательных метода — это конструктор и метод draw(). Вы также можете предоставить пользователю любые дополнительные методы, подходящие для вашей диаграммы. Просто помните, что чем проще в использовании, тем лучше.

Конструктор

Ваша диаграмма должна предоставлять один конструктор, принимающий один параметр — элемент DOM, в котором вы будете рисовать диаграмму. Обычно диаграммы хранят локальную копию этого элемента в конструкторе для дальнейшего использования:

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

Метод draw()

В вашем классе диаграммы должен быть метод draw() определенный в прототипе вашего класса диаграммы. Метод draw() принимает два параметра:

  1. DataTable , содержащий данные для отображения.
  2. Дополнительная карта параметров имени/значения для вашей диаграммы. Имена и типы значений параметров определяются вами для вашей конкретной диаграммы. Например, в приведенном ниже примере диаграммы Hello диаграмма поддерживает параметр с именем «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, доступном из вашего браузера. Затем сохраните следующий код, изменив исходный параметр <script> , чтобы он указывал на ваш файл JavaScript:

<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() . Сюда входит имя каждого параметра, тип ожидаемого значения и его значение по умолчанию.
  • Опишите все события, которые вы вызываете. Это означает имя и свойства каждого события, а также время срабатывания каждого события.
  • Укажите URL-адрес вашей библиотеки диаграмм, которая должна использоваться в операторе включения <script> клиента, и укажите URL-адрес вашей документации.
  • Дайте полное имя вашей диаграммы.
  • Создайте примеры страниц, демонстрирующие, как использовать диаграмму с поддерживаемыми параметрами, ее событиями и настраиваемыми методами.
  • Четко опишите политику данных вашей диаграммы. Большинство диаграмм обрабатывают данные в браузере, но некоторые могут отправлять данные на сервер, например, для создания изображения диаграммы или карты. Если вы отправляете данные на сервер:
    • Четко определите, какие данные отправляются.
    • Обратите внимание, как долго данные будут храниться на сервере.
    • Задокументируйте, какие организации будут иметь доступ к данным. Например, компания XYZ и т. д.
    • Укажите, будут ли данные регистрироваться и как долго.

Ваша документация будет храниться там же, где и код вашей диаграммы (см. раздел «Отправка диаграммы в галерею» ниже).

После того как вы напишете диаграмму, отправьте ее для публикации в разделе «Дополнительные диаграммы» нашей галереи . Отправка диаграммы означает, что вам придется подписать с нами соглашение, обязующее не создавать вредоносное программное обеспечение и не использовать пользовательские данные не по назначению. Галерея — это просто список указателей на диаграммы, которые мы создали или просмотрели; вы можете разместить фактическую библиотеку JavaScript и документацию на своем собственном сайте или поручить Google разместить библиотеку и документацию за вас. Укажите, хотите ли вы, чтобы мы размещали вашу диаграмму при публикации ее в галерее.

Поиск неисправностей

Если ваш код не работает, вот несколько подходов, которые могут помочь вам решить ваши проблемы:

  • Ищите опечатки. Помните, что JavaScript — язык, чувствительный к регистру.
  • Используйте отладчик JavaScript. В Firefox вы можете использовать консоль JavaScript, отладчик Venkman или надстройку Firebug . В IE вы можете использовать Microsoft Script Debugger .
  • Выполните поиск в группе обсуждения Google Chart API. Если вы не можете найти сообщение, отвечающее на ваш вопрос, опубликуйте свой вопрос в группе вместе со ссылкой на веб-страницу, демонстрирующую проблему.

Локализация

Если вы ожидаете, что вашей диаграммой будут пользоваться люди в разных странах, возможно, вам захочется разработать ее так, чтобы она была локализована для разных языков и культур. Самая простая локализация — это перевод стандартных текстовых строк пользовательского интерфейса в соответствии с настройками браузера пользователя. Более продвинутой формой локализации было бы изменение числовых форматов в зависимости от локализации или, возможно, даже от дизайна пользовательского интерфейса. Если вы решите локализовать диаграмму, укажите в документации языки, которые она поддерживает, и укажите настройки по умолчанию для наиболее часто используемого языка. Также полезно включить кнопку «изменить язык» в пользовательский интерфейс диаграммы на случай, если вы ошибетесь в выборе языка. Обычный способ определить язык браузера — просмотреть HTML-заголовок Accept-Language .