Загрузите библиотеки

На этой странице показано, как загрузить библиотеки Google Chart.

Загрузка базовой библиотеки

За некоторыми исключениями, все веб-страницы с Google Charts должны включать следующие строки в <head> веб-страницы:

<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
  ...
</script>

Первая строка этого примера загружает сам загрузчик. Вы можете загрузить загрузчик только один раз, независимо от того, сколько графиков вы планируете нарисовать. После загрузки загрузчика вы можете вызвать функцию google.charts.load один или несколько раз, чтобы загрузить пакеты для определенных типов диаграмм.

Первым аргументом google.charts.load является название или номер версии в виде строки. Если вы укажете 'current' , будет загружена последняя официальная версия Google Charts. Если вы хотите попробовать кандидата для следующего выпуска, вместо этого используйте 'upcoming' . В целом между ними будет очень мало различий, и они будут полностью идентичны, за исключением случаев, когда готовится новый выпуск. Распространенной причиной использования upcoming является то, что вы хотите протестировать новый тип диаграммы или функцию, которую Google собирается выпустить в ближайшие месяц или два. (Мы объявляем о предстоящих выпусках на нашем форуме и рекомендуем вам попробовать их после объявления, чтобы убедиться, что любые изменения в ваших графиках приемлемы.)

В приведенном выше примере предполагается, что вы хотите отобразить corechart (гистограмма, столбец, линия, область, ступенчатая область, пузырь, круговая диаграмма, пончик, комбинация, свеча, гистограмма, разброс). Если вам нужен другой или дополнительный тип диаграммы, замените или добавьте соответствующее имя пакета для corechart выше (например, {packages: ['corechart', 'table', 'sankey']} . Вы можете найти имя пакета в ' Загрузка» на странице документации для каждой диаграммы.

В этом примере также предполагается, что у вас есть функция JavaScript с именем drawChart определенная где-то на вашей веб-странице. Вы можете назвать эту функцию как угодно, но убедитесь, что она глобально уникальна и определена, прежде чем ссылаться на нее в своем вызове google.charts.setOnLoadCallback .

Примечание. В предыдущих версиях Google Charts для загрузки библиотек использовался код, отличный от приведенного выше. Чтобы обновить существующие диаграммы для использования нового кода, см. раздел Обновление кода загрузчика библиотеки .

Вот полный пример рисования круговой диаграммы с использованием базовой техники загрузки:

<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>

Загрузка сведений

Сначала вы должны загрузить сам загрузчик, что делается в отдельном теге script с src="https://www.gstatic.com/charts/loader.js" . Этот тег может быть либо в head , либо в body документа, либо он может быть динамически вставлен в документ во время его загрузки или после завершения загрузки.

<script src="https://www.gstatic.com/charts/loader.js"></script>

После загрузки загрузчика вы можете вызвать google.charts.load . Вы можете вызвать его в теге script в head или body документа, и вы можете вызвать его либо во время загрузки документа, либо в любое время после его загрузки.

Начиная с версии 45, вы можете вызывать google.charts.load более одного раза, чтобы загрузить дополнительные пакеты, хотя это безопаснее, если вы можете избежать этого. Каждый раз необходимо указывать один и тот же номер версии и языковые настройки.

Теперь вы можете использовать старый параметр URL autoload JSAPI, но значение этого параметра должно использовать строгое форматирование JSON и кодировку URL. В JavaScript вы можете выполнить кодирование jsonObject с помощью этого кода: encodeURIComponent(JSON.stringify(jsonObject)) .

Ограничения

Если вы используете версии до v45 , есть несколько незначительных, но важных ограничений на то, как вы загружаете Google Charts:

  1. Вы можете вызвать google.charts.load только один раз . Но вы можете перечислить все пакеты, которые вам понадобятся, за один звонок, поэтому нет необходимости делать отдельные звонки.
  2. Если вы используете ChartWrapper, вы должны явным образом загрузить все необходимые пакеты, а не полагаться на то, что ChartWrapper автоматически загрузит их для вас.
  3. Для 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 является название или номер версии. В настоящее время существует только два названия специальных версий и несколько замороженных версий.

Текущий
Это для последней официальной версии, которая меняется каждый раз, когда мы выпускаем новую версию. Эта версия в идеале хорошо протестирована и не содержит ошибок, но вы можете вместо этого указать конкретную замороженную версию, как только вы убедитесь, что она работает.
предстоящий
Это для следующего выпуска, пока он все еще тестируется и до того, как он станет официальным текущим выпуском. Пожалуйста, регулярно тестируйте эту версию, чтобы как можно скорее узнать, есть ли какие-либо проблемы, которые необходимо решить, прежде чем эта версия станет официальным выпуском.

Когда мы выпускаем новые версии Google Charts, некоторые из них вносят большие изменения, например совершенно новые типы диаграмм. Другие изменения небольшие, например улучшения внешнего вида или поведения существующих диаграмм.

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

Версии замороженных диаграмм обозначаются номерами и описаны в наших официальных выпусках . Чтобы загрузить замороженную версию, замените current или upcoming в вызове google.charts.load на номер замороженной версии:

<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 — это объект для указания настроек. Для настроек поддерживаются следующие свойства.

пакеты
Массив из нуля или более пакетов. Каждый загруженный пакет будет иметь код, необходимый для поддержки набора функций, обычно типа диаграммы. Пакет или пакеты, которые необходимо загрузить, перечислены в документации для каждого типа диаграммы. Вы можете не указывать какие-либо пакеты, если используете ChartWrapper для автоматической загрузки того, что потребуется.
язык
Код языка или локали, который должен использоваться для настройки текста, который может быть частью диаграммы. См. Locales для более подробной информации.
перезвонить
Функция, которая будет вызываться после загрузки пакетов. Кроме того, вы можете указать эту функцию, вызвав google.charts.setOnLoadCallback , как показано в примере выше. См. Обратный звонок для более подробной информации.
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
картыApiKey
(v45) Этот параметр позволяет указать ключ, который можно использовать с Geochart и Map Chart . Вы можете сделать это, а не использовать поведение по умолчанию, которое может привести к периодическому регулированию обслуживания для ваших пользователей. Узнайте, как настроить собственный ключ для использования сервиса Google Maps JavaScript API, здесь: Получение ключа/аутентификация . Ваш код будет выглядеть примерно так:
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
безопасный режим
(v47) Если установлено значение true, все диаграммы и всплывающие подсказки, которые генерируют HTML из предоставленных пользователем данных, будут очищать его, удаляя небезопасные элементы и атрибуты. В качестве альтернативы (v49+) библиотеку можно загрузить в безопасном режиме с помощью ярлыка, который принимает те же параметры загрузки, но всегда загружает «текущую» версию:
  google.charts.safeLoad({ packages: ['corechart'] });

Места

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

По умолчанию Google Charts загружается с языковым стандартом «en». Вы можете переопределить это значение по умолчанию, явно указав локаль в настройках загрузки.

Чтобы загрузить диаграмму, отформатированную для определенной локали, используйте настройку language следующим образом:

  // Load Google Charts for the Japanese locale.
  google.charts.load('current', {'packages':['corechart'], 'language': 'ja'});

Перейдите по этой ссылке для живого примера.

Перезвонить

Прежде чем вы сможете использовать любой из пакетов, загруженных с помощью google.charts.load , вам нужно дождаться завершения загрузки. Недостаточно просто дождаться завершения загрузки документа. Поскольку эта загрузка может занять некоторое время, вам необходимо зарегистрировать функцию обратного вызова. Это можно сделать тремя способами. Либо укажите параметр callback в вызове google.charts.load , либо вызовите setOnLoadCallback , передав функцию в качестве аргумента, либо используйте обещание, возвращаемое вызовом google.charts.load .

Обратите внимание, что для всех этих способов вам нужно предоставить определение функции, а не вызывать функцию. Предоставляемое вами определение функции может быть либо именованной функцией (поэтому вы просто указываете ее имя), либо анонимной функцией. Когда пакеты закончат загрузку, эта функция обратного вызова будет вызвана без аргументов. Загрузчик также будет ждать завершения загрузки документа перед вызовом обратного вызова.

Если вы хотите нарисовать более одной диаграммы, вы можете либо зарегистрировать более одной функции обратного вызова с помощью setOnLoadCallback , либо объединить их в одну функцию. Узнайте больше о том, как рисовать несколько диаграмм на одной странице .

  google.charts.setOnLoadCallback(drawChart1);
  google.charts.setOnLoadCallback(drawChart2);
  // OR
  google.charts.setOnLoadCallback(
    function() { // Anonymous function that calls drawChart1 and drawChart2
         drawChart1();
         drawChart2();
      });

Обратный вызов через обещание

Другой способ регистрации вашего обратного вызова — использовать промис, возвращаемый вызовом google.charts.load . Вы делаете это, добавляя вызов метода then() с кодом, который выглядит следующим образом.

  google.charts.load('upcoming', {packages: ['corechart']}).then(drawChart);

Одним из преимуществ использования Promise является то, что вы можете легко рисовать больше диаграмм, просто связывая больше вызовов .then(anotherFunction) . Использование Promise также связывает обратный вызов с конкретными пакетами, необходимыми для этого обратного вызова, что важно, если вы хотите загрузить больше пакетов с помощью другого вызова google.charts.load() .

Обновить код загрузчика библиотеки

Предыдущие версии Google Charts использовали другой код для загрузки библиотек. В таблице ниже показан старый код загрузчика библиотеки и новый.

Код загрузчика старой библиотеки
<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>
Новый код загрузчика библиотеки
<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
</script>

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