Carga las bibliotecas

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

Carga básica de la 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, independientemente de la cantidad de gráficos que planees dibujar. Después de cargar el cargador, puedes llamar a la función google.charts.load una o más veces a fin de cargar paquetes para tipos de gráficos específicos.

El primer argumento de google.charts.load es el nombre o número de la versión, como una cadena. Si especificas 'current', se cargará la versión oficial más reciente de Google Charts. Si quieres probar la versión candidata para la próxima versión, usa 'upcoming'. En general, habrá muy poca diferencia entre los dos y serán completamente idénticos, excepto cuando se esté realizando una nueva versión. 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 los próximos lanzamientos en nuestro foro y te recomendamos que los pruebes cuando se anuncien, para asegurarte de que cualquier cambio en tus gráficos sea aceptable).

En el ejemplo anterior, se supone que deseas mostrar una corechart (barra, columna, línea, área, área escalonada, burbuja, circular, dona, combo, vela, histograma, dispersión). Si deseas un tipo de gráfico diferente o adicional, sustituye o agrega el nombre de paquete adecuado de 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 de 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 esa función como desees, 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 Gráficos de Google usaban código distinto del anterior para cargar las bibliotecas. A fin de actualizar los gráficos existentes para usar el código nuevo, consulta Actualiza el código del cargador de la biblioteca.

A continuación, se muestra 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>

Cómo cargar detalles

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

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

Una vez que se cargue el cargador, podrás llamar a google.charts.load. Cuando 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 con el objetivo de cargar paquetes adicionales, aunque es más seguro evitar hacerlo. Debes proporcionar el mismo número de versión y la misma configuración de idioma cada vez.

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

Limitaciones

Si usas versiones anteriores a la 45, existen algunas limitaciones menores, pero importantes, en la forma en que cargas 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 hacer llamadas separadas.
  2. Si usas un ChartWrapper, debes cargar explícitamente todos los paquetes que necesitarás, en lugar de confiar en que ChartWrapper los cargará automáticamente por ti.
  3. Para Geochart y Gráfico de mapa, debes cargar el cargador de bibliotecas anterior y el cargador de bibliotecas nuevo. Recuerda que esto es solo para las versiones anteriores a la 45 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>

Carga el nombre o número de la versión

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

actual
Este es el lanzamiento oficial más reciente, que cambia cada vez que lanzamos una versión nueva. Lo ideal es que esta versión esté bien probada y no contenga errores, pero es posible que desees especificar una versión sin actualizar 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 con regularidad para saber lo antes posible si hay algún problema que debas solucionar antes de que esta versión se convierta en el lanzamiento oficial.

Cuando lanzamos versiones nuevas de los gráficos de Google, algunos de los cambios son importantes, al igual que los tipos de gráficos completamente nuevos. Otros cambios son pequeños, como las mejoras en el aspecto o el comportamiento de los gráficos existentes.

Muchos creadores de los rankings de Google ajustan el aspecto de sus rankings hasta que sea exactamente lo que quieren. Es posible que algunos creadores se sientan más cómodos sabiendo que sus rankings nunca cambiarán, independientemente de las mejoras que realicemos en el futuro. En el caso de esos usuarios, admitimos Google Charts congelado.

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

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

Esperamos que las versiones congeladas permanezcan disponibles de forma indefinida, aunque es posible que retiremos las versiones congeladas que tengan problemas de seguridad. Por lo general, no brindaremos asistencia para las versiones sin actualizar, excepto para sugerirte, de forma poco útil, que actualices a una versión más reciente.

Cargar la configuración

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

paquetes
Es un array 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 necesitas cargar se enumeran en la documentación para cada tipo de gráfico. Puedes evitar especificar cualquier paquete si usas un ChartWrapper para cargar automáticamente lo que se requerirá.
language
Es el código del idioma o la configuración regional que se debe usar para personalizar el texto que podría formar parte del gráfico. Consulta Configuraciones regionales para obtener más información.
callback
Una función a la que se llamará una vez que se carguen 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 detalles. 
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
mapsApiKey
(v45) Esta configuración te permite especificar una clave que puedes usar con Geográfico y Gráfico de mapa. Te recomendamos hacerlo en lugar de usar el comportamiento predeterminado, que podría provocar que se limite ocasionalmente el servicio para tus usuarios. Obtén información sobre cómo configurar tu propia clave para usar el servicio "Google Maps JavaScript API" aquí: Obtén una clave o autenticación. El código se verá de la siguiente manera: 
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
safeMode
(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 lo limpiarán mediante la eliminación de los elementos y atributos no seguros. Como alternativa (v49 y versiones posteriores), la biblioteca se puede cargar en modo seguro con un acceso directo que acepte la misma configuración de carga, pero siempre cargue 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 un 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 esta configuración predeterminada si especificas de forma explícita una configuración regional en la configuración de carga.

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

Devolución de llamada

Antes de poder usar cualquiera de los paquetes cargados por google.charts.load, debes esperar a que finalice la carga. No basta con esperar a que termine de cargarse el documento. Como la carga puede tardar un poco en finalizar, debes registrar una función de devolución de llamada. Existen tres formas de hacerlo. Especifica una configuración de callback en tu llamada a google.charts.load, o bien llama a setOnLoadCallback pasando una función como argumento, o usa la promesa que muestra la llamada de google.charts.load.

Ten en cuenta que, para todos estos métodos, debes proporcionar una definición de función, en lugar de llamar a la función. La definición de función que proporciones puede ser una función con nombre (por lo que solo debes asignarle su 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 puedes 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 una promesa

Otra forma de registrar la devolución de llamada es usar la promesa que se muestra a partir de 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 dibujar más gráficos fácilmente con solo encadenar más llamadas a .then(anotherFunction). El uso de la promesa también vincula la devolución de llamada a los paquetes específicos necesarios para esa devolución de llamada, lo cual es importante si deseas cargar más paquetes con otra llamada a google.charts.load().

Actualiza el código del cargador de la biblioteca

Las versiones anteriores de Gráficos de Google utilizaban código diferente para cargar las bibliotecas. En la siguiente tabla, se muestra el código antiguo del cargador de bibliotecas y el nuevo.

Código antiguo del cargador de biblioteca 
<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 del 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 bibliotecas con el código nuevo. Sin embargo, ten en cuenta las limitaciones para cargar las bibliotecas que se describieron anteriormente.