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

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

Базовая загрузка библиотеки

За некоторыми исключениями, все веб-страницы с диаграммами Google должны содержать следующие строки в <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 Chart настраивают внешний вид своих диаграмм до тех пор, пока они не станут именно такими, как им нужно. Некоторым авторам может быть спокойнее знать, что их диаграммы никогда не изменятся, независимо от того, какие улучшения мы внесем в будущем. Для этих пользователей мы поддерживаем замороженные диаграммы 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 для автоматической загрузки того, что потребуется.
язык
Код языка или локали, который должен использоваться для настройки текста, который может быть частью диаграммы. Дополнительные сведения см. в разделе «Локали» .
перезвонить
Функция, которая будет вызываться после загрузки пакетов. Альтернативно вы можете указать эту функцию, вызвав google.charts.setOnLoadCallback как показано в примере выше. Подробнее см. в разделе Обратный вызов . 
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
картыApiKey
(v45) Этот параметр позволяет указать ключ, который можно использовать с географической диаграммой и картографической диаграммой . Возможно, вы захотите сделать это, а не использовать поведение по умолчанию, которое может привести к периодическому регулированию обслуживания ваших пользователей. Узнайте, как настроить собственный ключ для использования службы «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 загружаются с локалью «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 передав функцию в качестве аргумента, либо используйте Promise, возвращаемый вызовом 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>

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