Carga las bibliotecas

En esta página, se muestra cómo cargar las bibliotecas de los gráficos de Google.

Carga básica de biblioteca

Con algunas excepciones, todas las páginas web con gráficos de Google deben incluir las siguientes líneas en el <head> de la página web:

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

La primera línea de este ejemplo carga el cargador. Solo puedes cargar el cargador una vez, sin importar la cantidad de gráficos que desees dibujar. Después de cargar el cargador, puedes llamar a la función google.charts.load una o más veces para cargar paquetes de tipos de gráficos específicos.

El primer argumento de google.charts.load es el nombre o el número de la versión, como una string. Si especificas 'current', se cargará la última versión oficial de los gráficos de Google. Si quieres probar la versión candidata para la próxima versión, usa 'upcoming'. En general, habrá poca diferencia entre los dos, y serán completamente idénticos, excepto cuando se esté lanzando un nuevo lanzamiento. Un motivo común para usar upcoming es que quieres probar un nuevo tipo de gráfico o función que Google lanzará en los próximos meses. (Anunciamos las próximas versiones en nuestro foro y te recomendamos que las pruebes cuando se anuncien a fin de asegurarte de que cualquier cambio en tus gráficos sea aceptable).

En el ejemplo anterior, se supone que deseas mostrar un corechart (barra, columna, línea, área, área escalonada, burbuja, circular, anillo, combo, candelabro, histograma, dispersión). Si deseas un tipo de gráfico diferente o adicional, sustituye o agrega el nombre de paquete adecuado para corechart anterior (p.ej., {packages: ['corechart', 'table', 'sankey']}. Puedes encontrar el nombre del paquete en la sección "Cargando" de la página de documentación para cada gráfico.

En este ejemplo, también se supone que tienes una función de JavaScript llamada drawChart definida en algún lugar de tu página web. Puedes nombrar a esa función como quieras, pero asegúrate de que sea única a nivel global y de que esté definida antes de hacer referencia a ella en tu llamada a google.charts.setOnLoadCallback.

Nota: Las versiones anteriores de los gráficos de Google usaban un código que difiere de los anteriores para cargar las bibliotecas. Si quieres actualizar tus gráficos existentes para usar el código nuevo, consulta Cómo actualizar el código del cargador de la biblioteca.

Aquí tienes un ejemplo completo de cómo dibujar un gráfico circular con la técnica de carga básica:

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

Carga de detalles

Primero, debes cargar el cargador, que se hace en una etiqueta script separada con src="https://www.gstatic.com/charts/loader.js". Esta etiqueta puede estar en el head o en el body del documento, o se puede insertar de forma dinámica mientras se carga o después de que se completa la carga.

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

Después de cargar el cargador, puedes llamar a google.charts.load. Donde lo llames puede estar en una etiqueta script en el head o body del documento, y puedes llamarlo mientras el documento aún se está cargando o en cualquier momento después de que haya terminado de cargarse.

A partir de la versión 45, puedes llamar a google.charts.load más de una vez para cargar paquetes adicionales, aunque es más seguro si puedes evitar hacerlo. Debes proporcionar el mismo número de versión y configuración de idioma cada vez.

Ahora puedes usar el parámetro de URL autoload anterior de JSAPI, pero el valor de este parámetro debe usar un formato JSON estricto y codificación de URL. En JavaScript, puedes codificar jsonObject con este código: encodeURIComponent(JSON.stringify(jsonObject)).

Limitaciones

Si usas versiones anteriores a la versión 45, existen algunas limitaciones menores, pero importantes, con respecto a la forma en que cargas los gráficos de Google:

  1. Solo puedes llamar a google.charts.load una vez. Sin embargo, puedes enumerar todos los paquetes que necesitarás en una llamada, por lo que no es necesario realizar llamadas separadas.
  2. Si usas un ChartWrapper, debes cargar de forma explícita todos los paquetes que necesitarás, en lugar de depender de ChartWrapper para cargarlos automáticamente.
  3. Para Geochart y Gráfico de mapas, debes cargar el cargador de biblioteca anterior y el cargador de biblioteca nuevo. Nuevamente, esto es solo para las versiones anteriores a v45 y no debes hacerlo para las versiones posteriores.
    <script src="https://www.gstatic.com/charts/loader.js"></script>
    <script src="https://www.google.com/jsapi"></script>

Cómo cargar el nombre o el número de la versión

El primer argumento de tu llamada a google.charts.load es el nombre o el número de la versión. En este momento, solo hay dos nombres de versión especiales y varias versiones sin actualizar.

actual
Esta es para la versión oficial más reciente, que cambia cada vez que lanzamos una nueva versión. Esta versión está bien probada y es libre de errores, pero es posible que desees especificar una versión inmovilizada en particular una vez que estés seguro de que funciona.
futura
Se trata de la próxima versión, mientras se está probando y antes de que se convierta en la versión oficial actual. Prueba esta versión de forma regular para saber lo antes posible si hay problemas que se deben solucionar antes de que se convierta en la versión oficial.

Cuando lanzamos versiones nuevas de Google Charts, algunos de los cambios son importantes, como los tipos de gráficos completamente nuevos. Otros cambios son pequeños, como mejoras en la apariencia o el comportamiento de los gráficos existentes.

Muchos creadores de los rankings de Google afinan la apariencia de sus gráficos hasta que son exactamente lo que desean. Es posible que algunos creadores se sientan más cómodos sabiendo que sus gráficos nunca cambiarán, independientemente de las mejoras que realicemos en el futuro. Para esos usuarios, admitimos gráficos de Google congelados.

Las versiones inmovilizadas de los gráficos se identifican por número y se describen en nuestras Versiones oficiales. Para cargar una versión inmovilizada, reemplaza current o upcoming en tu llamada de google.charts.load con el número de versión inmovilizado:

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

Se espera que las versiones congeladas permanezcan disponibles de forma indefinida, aunque es posible que las retiremos debido a problemas de seguridad. Por lo general, no proporcionaremos asistencia para las versiones inmovilizadas, excepto para sugerir de forma poco útil que actualices a una versión más reciente.

Cómo cargar la configuración

El segundo parámetro de tu llamada a google.charts.load es un objeto para especificar la configuración. Las siguientes propiedades son compatibles con la configuración.

paquetes
Un arreglo de cero o más paquetes. Cada paquete que se carga tendrá el código necesario para admitir un conjunto de funcionalidades, por lo general, un tipo de gráfico. Los paquetes que debes cargar se enumeran en la documentación para cada tipo de gráfico. Puedes evitar la especificación de paquetes si usas un ChartWrapper para cargar de forma automática lo que se requerirá.
language
Es el código para el idioma o la configuración regional que debería personalizar el texto que podría ser parte del gráfico. Consulta Configuraciones regionales para obtener más información.
callback
Es una función que se llamará una vez que se hayan cargado los paquetes. Como alternativa, puedes especificar esta función llamando a google.charts.setOnLoadCallback como se muestra en el ejemplo anterior. Consulta Devolución de llamada para obtener más información.
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
Api de mapas
(v45) Esta configuración te permite especificar una clave que puedes usar con Geochart y Gráfico de mapas. Es posible que quieras hacerlo en lugar de usar el comportamiento predeterminado, que puede causar una regulación ocasional del servicio para tus usuarios. Aprende a configurar tu propia clave para usar el servicio de la "Google Maps JavaScript API" aquí: Obtener una clave/autenticación. El código se verá de la siguiente manera:
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
modo seguro
(v47) Cuando se establece como verdadero, todos los gráficos y la información sobre la herramienta que generan HTML a partir de datos proporcionados por el usuario se limpiarán mediante la eliminación de elementos y atributos no seguros. Como alternativa (v49 o superior), la biblioteca se puede cargar en modo seguro con un acceso directo que acepta la misma configuración de carga, pero siempre carga la versión "actual":
  google.charts.safeLoad({ packages: ['corechart'] });

Configuración regional

Las configuraciones regionales se usan para personalizar el texto de un país o idioma, lo que afecta el formato de los valores, como monedas, fechas y números.

De forma predeterminada, los gráficos de Google se cargan con la configuración regional "en". Puedes anular este valor predeterminado si especificas una configuración regional de forma explícita en la configuración de carga.

Si deseas cargar un gráfico con formato para una configuración regional específica, usa la configuración language de la siguiente manera:

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

Sigue este vínculo para ver un ejemplo en vivo.

Callback

Antes de que puedas usar cualquiera de los paquetes que carga google.charts.load, debes esperar a que finalice la carga. No basta con esperar a que termine de cargarse el documento. Debes registrar una función de devolución de llamada, ya que puede tomar un tiempo antes de que finalice esta carga. Existen tres maneras de hacerlo. Especifica una configuración de callback en tu llamada a google.charts.load, llama a setOnLoadCallback y pasa una función como argumento, o usa la promesa que muestra la llamada de google.charts.load.

Ten en cuenta que para todas estas formas debes proporcionar una definición de función, en lugar de llamar a la función. La definición de función que proporcionas puede ser una función con nombre (por lo que solo debes asignar un nombre) o una función anónima. Cuando los paquetes terminen de cargarse, se llamará a esta función de devolución de llamada sin argumentos. El cargador también esperará a que el documento termine de cargarse antes de llamar a la devolución de llamada.

Si deseas dibujar más de un gráfico, puedes registrar más de una función de devolución de llamada con setOnLoadCallback o combinarlas en una función. Obtén más información para dibujar varios gráficos en una página.

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

Devolución de llamada a través de promesas

Otra forma de registrar la devolución de llamada es usar la promesa que se muestra en la llamada a google.charts.load. Para ello, agrega una llamada al método then() con un código similar al siguiente.

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

Uno de los beneficios de usar la promesa es que puedes encadenar más llamadas .then(anotherFunction) con facilidad. El uso de la promesa también vincula la devolución de llamada con los paquetes específicos requeridos para esa devolución de llamada, lo cual es importante si deseas cargar más paquetes con otra llamada de google.charts.load().

Cómo actualizar el código del cargador de la biblioteca

Las versiones anteriores de los Gráficos de Google usaban un código diferente para cargar las bibliotecas. En la siguiente tabla, se muestra el código del cargador de bibliotecas anterior en comparación con el nuevo.

Código de cargador de biblioteca anterior
<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>
      
Nuevo código de cargador de biblioteca
<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
</script>
      

Para actualizar tus gráficos existentes, puedes reemplazar el código antiguo del cargador de la biblioteca por el nuevo. Sin embargo, ten en cuenta las limitaciones para la carga de bibliotecas descritas anteriormente.