Descrizioni comandi

Descrizione dei comandi: introduzione

Le descrizioni comando sono piccole caselle che vengono visualizzate quando passi il mouse sopra un elemento. I biglietti da visita sono più generici e possono essere visualizzati ovunque sullo schermo; le descrizioni comando sono sempre collegate a elementi, ad esempio un punto su un grafico a dispersione o una barra in un grafico a barre.

In questa documentazione imparerai a creare e personalizzare le descrizioni comando in Google Chart.

Specificare il tipo di descrizione comando

Google Graph crea automaticamente descrizioni comando per tutti i grafici principali. Verranno sottoposti a rendering come SVG per impostazione predefinita, tranne in IE 8, dove verranno visualizzati come VML. Puoi creare descrizioni comando HTML nei grafici principali specificando tooltip.isHtml: true nelle opzioni del grafico passate alla chiamata draw(). In questo modo potrai anche creare azioni descrizione comando.

Descrizioni comando standard

In assenza di contenuti personalizzati, quelli della descrizione comando vengono generati automaticamente in base ai dati sottostanti. Puoi visualizzare la descrizione comando passando il mouse sopra una delle barre del grafico.

Personalizzazione dei contenuti delle descrizioni comando

In questo esempio, aggiungiamo contenuti personalizzati alle descrizioni comando aggiungendo una nuova colonna a DataTable e contrassegnandola con il ruolo della descrizione comando.

Nota: questa operazione non è supportata dalla visualizzazione Grafico a bolle.

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

      function drawChart() {
        var dataTable = new google.visualization.DataTable();
        dataTable.addColumn('string', 'Year');
        dataTable.addColumn('number', 'Sales');
        // A column for custom tooltip content
        dataTable.addColumn({type: 'string', role: 'tooltip'});
        dataTable.addRows([
          ['2010', 600,'$600K in our first year!'],
          ['2011', 1500, 'Sunspot activity made this our best year ever!'],
          ['2012', 800, '$800K in 2012.'],
          ['2013', 1000, '$1M in sales last year.']
        ]);

        var options = { legend: 'none' };
        var chart = new google.visualization.ColumnChart(document.getElementById('tooltip_action'));
        chart.draw(dataTable, options);
      }

Utilizzare le descrizioni comando HTML

Questo esempio si basa su quello precedente abilitando le descrizioni comando HTML. Nota l'aggiunta di tooltip.isHtml: true alle opzioni del grafico.

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

      function drawChart() {
        var dataTable = new google.visualization.DataTable();
        dataTable.addColumn('string', 'Year');
        dataTable.addColumn('number', 'Sales');
        // A column for custom tooltip content
        dataTable.addColumn({type: 'string', role: 'tooltip'});
        dataTable.addRows([
          ['2010', 600,'$600K in our first year!'],
          ['2011', 1500, 'Sunspot activity made this our best year ever!'],
          ['2012', 800, '$800K in 2012.'],
          ['2013', 1000, '$1M in sales last year.']
        ]);

        var options = {
          tooltip: {isHtml: true},
          legend: 'none'
        };
        var chart = new google.visualization.ColumnChart(document.getElementById('col_chart_html_tooltip'));
        chart.draw(dataTable, options);
      }

L'aspetto non è molto diverso, ma ora possiamo personalizzare il codice HTML.

Personalizzazione dei contenuti HTML

Tutti gli esempi precedenti hanno utilizzato le descrizioni comando con contenuti di testo normale, ma la vera potenza delle descrizioni comando HTML emerge quando è possibile personalizzarle con il markup HTML. Per attivare questa funzionalità, devi fare due cose:

1. Specifica tooltip.isHtml: true nelle opzioni del grafico. Questo indica al grafico di disegnare le descrizioni comando in HTML (anziché in SVG).
2. Contrassegna un'intera colonna o una cella specifica nella tabella di dati con la proprietà personalizzata html. Una colonna della tabella dati con il ruolo della descrizione comando e la proprietà HTML sarebbe:
   dataTable.addColumn({'type': 'string', 'role': 'tooltip', 'p': {'html': true}})

   Nota: questa operazione non funziona con la visualizzazione Grafico a bolle. I contenuti delle descrizioni comando HTML dei grafici a bolle non sono personalizzabili.

Importante:assicurati che il codice HTML nelle descrizioni comando provenga da una fonte attendibile. Se i contenuti HTML personalizzati includono contenuti generati dagli utenti, l'utilizzo di caratteri di escape è fondamentale. In caso contrario, le tue splendide visualizzazioni potrebbero essere soggette ad attacchi XSS.

Per creare contenuti HTML personalizzati basta aggiungere un tag <img> o applicare il grassetto a del testo:

I contenuti HTML personalizzati possono includere anche contenuti generati dinamicamente. Qui aggiungiamo una descrizione comando contenente una tabella generata dinamicamente per ciascun valore di categoria. Poiché la descrizione comando è collegata al valore della riga, se passi il mouse sopra una qualsiasi barra verrà visualizzata la descrizione comando HTML.

Questo esempio mostra come è possibile collegare una descrizione comando HTML personalizzata a una colonna di dominio. (Negli esempi precedenti, era collegata a una colonna di dati). Per attivare la descrizione comando per l'asse del dominio, imposta l'opzione focusTarget: 'category'.

function drawChart() {
  var dataTable = new google.visualization.DataTable();
  dataTable.addColumn('string', 'Country');
  // Use custom HTML content for the domain tooltip.
  dataTable.addColumn({'type': 'string', 'role': 'tooltip', 'p': {'html': true}});
  dataTable.addColumn('number', 'Gold');
  dataTable.addColumn('number', 'Silver');
  dataTable.addColumn('number', 'Bronze');

  dataTable.addRows([
    ['USA', createCustomHTMLContent('https://upload.wikimedia.org/wikipedia/en/a/a4/Flag_of_the_United_States.svg', 46, 29, 29), 46, 29, 29],
    ['China', createCustomHTMLContent('https://upload.wikimedia.org/wikipedia/commons/f/fa/Flag_of_the_People%27s_Republic_of_China.svg', 38, 27, 23), 38, 27, 23],
    ['UK', createCustomHTMLContent('https://upload.wikimedia.org/wikipedia/commons/a/ae/Flag_of_the_United_Kingdom.svg', 29, 17, 19), 29, 17, 19]
  ]);

  var options = {
    title: 'London Olympics Medals',
    colors: ['#FFD700', '#C0C0C0', '#8C7853'],
    // This line makes the entire category's tooltip active.
    focusTarget: 'category',
    // Use an HTML tooltip.
    tooltip: { isHtml: true }
  };

  // Create and draw the visualization.
  new google.visualization.ColumnChart(document.getElementById('custom_html_content_div')).draw(dataTable, options);
}

function createCustomHTMLContent(flagURL, totalGold, totalSilver, totalBronze) {
  return '<div style="padding:5px 5px 5px 5px;">' +
      '<img src="' + flagURL + '" style="width:75px;height:50px"><br/>' +
      '<table class="medals_layout">' + '<tr>' +
      '<td><img src="https://upload.wikimedia.org/wikipedia/commons/1/15/Gold_medal.svg" style="width:25px;height:25px"/></td>' +
      '<td><b>' + totalGold + '</b></td>' + '</tr>' + '<tr>' +
      '<td><img src="https://upload.wikimedia.org/wikipedia/commons/0/03/Silver_medal.svg" style="width:25px;height:25px"/></td>' +
      '<td><b>' + totalSilver + '</b></td>' + '</tr>' + '<tr>' +
      '<td><img src="https://upload.wikimedia.org/wikipedia/commons/5/52/Bronze_medal.svg" style="width:25px;height:25px"/></td>' +
      '<td><b>' + totalBronze + '</b></td>' + '</tr>' + '</table>' + '</div>';
}

Rotazione delle descrizioni comando

Le descrizioni comando nei grafici di Google possono essere ruotate con CSS. Nel grafico sottostante, le descrizioni comando vengono ruotate di 30° in senso orario utilizzando questo CSS incorporato immediatamente prima del div del grafico:

Tieni presente che questa operazione funzionerà solo per le descrizioni comando HTML, ad esempio quelle con l'opzione isHtml: true.

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

        var data = google.visualization.arrayToDataTable([
          ['Year', 'Fixations'],
          ['2015',  80],
          ['2016',  90],
          ['2017',  100],
          ['2018',  90],
          ['2019',  80],
        ]);

        var options = {
          tooltip: { isHtml: true },    // CSS styling affects only HTML tooltips.
          legend: { position: 'none' },
          bar: { groupWidth: '90%' },
          colors: ['#A61D4C']
        };

        var chart = new google.visualization.ColumnChart(document.getElementById('tooltip_rotated'));

        chart.draw(data, options);
      }
    </script>
  </head>
  <body>
    <!-- The next line rotates HTML tooltips by 30 degrees clockwise. -->
    <style>div.google-visualization-tooltip { transform: rotate(30deg); }</style>
    <div id="tooltip_rotated" style="width: 400px; height: 400px;"></div>
  </body>
</html>

Inserire i grafici nelle descrizioni comando

Le descrizioni comando HTML possono includere quasi tutti i contenuti HTML che preferisci, anche un grafico Google. Con i grafici all'interno delle descrizioni comando, gli utenti possono ottenere ulteriori informazioni quando passano il mouse sopra un elemento di dati: un buon modo per fornire un dettaglio di alto livello a un primo sguardo, consentendo agli utenti di approfondire quando vogliono.

Il grafico a colonne riportato di seguito mostra un grafico dei più alti visualizzazioni recenti di diversi importanti eventi sportivi, con le descrizioni comando per ciascun evento che mostra un grafico a linee delle visualizzazioni medie negli ultimi dieci anni.

Occorre notare un paio di cose. Innanzitutto, è necessario disegnare un grafico stampabile per ogni set di dati da mostrare in una descrizione comando. In secondo luogo, ogni grafico con descrizione comando richiede un gestore di eventi"ready", che chiamiamo tramite addListener per creare un grafico stampabile.

IMPORTANTE: tutti i grafici descrizione comando devono essere tracciati prima del grafico principale. Questa operazione è necessaria per recuperare le immagini da aggiungere alla tabella di dati del grafico principale.

      // Draws your charts to pull the PNGs for your tooltips.
      function drawTooltipCharts() {

        var data = new google.visualization.arrayToDataTable(tooltipData);
        var view = new google.visualization.DataView(data);

        // For each row of primary data, draw a chart of its tooltip data.
        for (var i = 0; i < primaryData.length; i++) {

          // Set the view for each event's data
          view.setColumns([0, i + 1]);

          var hiddenDiv = document.getElementById('hidden_div');
          var tooltipChart = new google.visualization.LineChart(hiddenDiv);

          google.visualization.events.addListener(tooltipChart, 'ready', function() {

            // Get the PNG of the chart and set is as the src of an img tag.
            var tooltipImg = '<img src="' + tooltipChart.getImageURI() + '">';

            // Add the new tooltip image to your data rows.
            primaryData[i][2] = tooltipImg;

          });
          tooltipChart.draw(view, tooltipOptions);
        }
        drawPrimaryChart();
      }

      function drawPrimaryChart() {

        var data = new google.visualization.DataTable();
        data.addColumn('string', 'Event');
        data.addColumn('number', 'Highest Recent Viewership');

        // Add a new column for your tooltips.
        data.addColumn({
          type: 'string',
          label: 'Tooltip Chart',
          role: 'tooltip',
          'p': {'html': true}
        });

        // Add your data (with the newly added tooltipImg).
        data.addRows(primaryData);

        var visibleDiv = document.getElementById('visible_div');
        var primaryChart = new google.visualization.ColumnChart(visibleDiv);
        primaryChart.draw(data, primaryOptions);

      }

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

      // Set up data for visible chart.
      var primaryData = [
        ['NBA Finals', 22.4],
        ['NFL Super Bowl', 111.3],
        ['MLB World Series', 19.2],
        ['UEFA Champions League Final', 1.9],
        ['NHL Stanley Cup Finals', 6.4],
        ['Wimbledon Men\'s Championship', 2.4]
      ];

      // Set up data for your tooltips.
      var tooltipData = [
        ['Year', 'NBA Finals', 'NFL Super Bowl', 'MLB World Series',
        'UEFA Champions League Final', 'NHL Stanley Cup Finals',
        'Wimbledon Men\'s Championship'],
        ['2005', 12.5, 98.7, 25.3, 0.6, 3.3, 2.8],
        ['2006', 13.0, 90.7, 17.1, 0.8, 2.8, 3.4],
        ['2007', 9.3, 93.0, 15.8, 0.9, 1.8, 3.8],
        ['2008', 14.9, 97.5, 17.1, 1.3, 4.4, 5.1],
        ['2009', 14.3, 98.7, 13.6, 2.1, 4.9, 5.7],
        ['2010', 18.2, 106.5, 19.4, 2.2, 5.2, 2.3],
        ['2011', 17.4, 111.0, 14.3, 4.2, 4.6, 2.7],
        ['2012', 16.8, 111.3, 16.6, 2.0, 2.9, 3.9],
        ['2013', 16.6, 108.7, 12.7, 1.4, 5.8, 2.5],
        ['2014', 15.7, 111.3, 15.0, 1.9, 4.7, 2.4]
      ];

      var primaryOptions = {
        title: 'Highest U.S. Viewership for Most Recent Event (in millions)',
        legend: 'none',
        tooltip: {isHtml: true} // This MUST be set to true for your chart to show.
      };

      var tooltipOptions = {
        title: 'U.S. Viewership Over The Last 10 Years (in millions)',
        legend: 'none'
      };

      // Draws your charts to pull the PNGs for your tooltips.
      function drawTooltipCharts() {

        var data = new google.visualization.arrayToDataTable(tooltipData);
        var view = new google.visualization.DataView(data);

        // For each row of primary data, draw a chart of its tooltip data.
        for (var i = 0; i < primaryData.length; i++) {

          // Set the view for each event's data
          view.setColumns([0, i + 1]);

          var hiddenDiv = document.getElementById('hidden_div');
          var tooltipChart = new google.visualization.LineChart(hiddenDiv);

          google.visualization.events.addListener(tooltipChart, 'ready', function() {

            // Get the PNG of the chart and set is as the src of an img tag.
            var tooltipImg = '<img src="' + tooltipChart.getImageURI() + '">';

            // Add the new tooltip image to your data rows.
            primaryData[i][2] = tooltipImg;

          });
          tooltipChart.draw(view, tooltipOptions);
        }
        drawPrimaryChart();
      }

      function drawPrimaryChart() {

        var data = new google.visualization.DataTable();
        data.addColumn('string', 'Event');
        data.addColumn('number', 'Highest Recent Viewership');

        // Add a new column for your tooltips.
        data.addColumn({
          type: 'string',
          label: 'Tooltip Chart',
          role: 'tooltip',
          'p': {'html': true}
        });

        // Add your data (with the newly added tooltipImg).
        data.addRows(primaryData);

        var visibleDiv = document.getElementById('visible_div');
        var primaryChart = new google.visualization.ColumnChart(visibleDiv);
        primaryChart.draw(data, primaryOptions);

      }
    </script>
  </head>
<body>
<div id="hidden_div" style="display:none"></div>
<div id="visible_div" style="height:300px"></div>
</body>
</html>

Azioni descrizione comando

Le descrizioni comando possono anche includere azioni definite da JavaScript. Ecco un semplice esempio: ecco una descrizione comando con un'azione che mostra una finestra di dialogo quando l'utente fa clic su "Visualizza anteprima":

L'opzione tooltip si attiva quando l'utente seleziona un wedge della torta, causando l'esecuzione del codice definito in setAction:

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

      function drawChart() {
        var data = google.visualization.arrayToDataTable([
          ['Genre', 'Percentage of my books'],
          ['Science Fiction', 217],
          ['General Science', 203],
          ['Computer Science', 175],
          ['History', 155],
          ['Economics/Political Science', 98],
          ['General Fiction', 72],
          ['Fantasy', 51],
          ['Law', 29]
        ]);

        var chart = new google.visualization.PieChart(
          document.getElementById('tooltip_action'));

        var options = { tooltip: { trigger: 'selection' }};

        chart.setAction({
          id: 'sample',
          text: 'See sample book',
          action: function() {
            selection = chart.getSelection();
            switch (selection[0].row) {
              case 0: alert('Ender\'s Game'); break;
              case 1: alert('Feynman Lectures on Physics'); break;
              case 2: alert('Numerical Recipes in JavaScript'); break;
              case 3: alert('Truman'); break;
              case 4: alert('Freakonomics'); break;
              case 5: alert('The Mezzanine'); break;
              case 6: alert('The Color of Magic'); break;
              case 7: alert('The Law of Superheroes'); break;
            }
          }
        });

        chart.draw(data, options);
      }

Le azioni possono essere visible, enabled, entrambe o nessuna. Quando viene visualizzato un grafico Google, l'azione della descrizione comando viene mostrata solo se è visibile e selezionabile solo se è attiva. (Disattivata, ma le azioni visibili sono in grigio.)

visible e enabled dovrebbero essere funzioni che restituiscono valori veri o falsi. Queste funzioni possono dipendere dall'ID elemento e dalla selezione dell'utente, consentendoti di ottimizzare la visibilità e la cliccabilità delle azioni.

Le descrizioni comando possono essere attivate su focus e selection. Tuttavia, con le azioni della descrizione comando, selection è preferibile. La descrizione comando rimane invariata, consentendo all'utente di selezionare più facilmente l'azione.

Ovviamente le azioni non devono essere avvisi: tutto ciò che puoi fare da JavaScript, lo puoi fare da un'azione. In questo caso aggiungeremo due azioni: una per ingrandire la base del grafico a torta e un'altra per ridurla.

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

      function drawChart() {
        var data = google.visualization.arrayToDataTable([
          ['Genre', 'Percentage of my books'],
          ['Science Fiction', 217],
          ['General Science', 203],
          ['Computer Science', 175],
          ['History', 155],
          ['Economics & Political Science', 98],
          ['General Fiction', 72],
          ['Fantasy', 51],
          ['Law', 29]
        ]);

        var chart = new google.visualization.PieChart(
          document.getElementById('tooltip_action_2'));

        var options = { tooltip: { trigger: 'selection' }};

        chart.setAction({
          id: 'increase',
          text: 'Read 20 more books',
          action: function() {
            data.setCell(chart.getSelection()[0].row, 1,
                         data.getValue(chart.getSelection()[0].row, 1) + 20);
            chart.draw(data, options);
          }
        });

        chart.setAction({
          id: 'decrease',
          text: 'Read 20 fewer books',
          action: function() {
            data.setCell(chart.getSelection()[0].row, 1,
                         data.getValue(chart.getSelection()[0].row, 1) - 20);
            chart.draw(data, options);
          }
        });

        chart.draw(data, options);
      }

Annotazione dei dati

Puoi sovrapporre il testo direttamente su un grafico Google utilizzando annotationText anziché tooltip come ruolo della colonna. Puoi visualizzare la descrizione comando passando il mouse sopra l'annotazione.

function drawChart() {
  var dataTable = new google.visualization.DataTable();
  dataTable.addColumn('string', 'Year');
  dataTable.addColumn('number', 'USA');
  dataTable.addColumn({type: 'string', role: 'annotation'});
  dataTable.addColumn({type: 'string', role: 'annotationText', p: {html:true}});
  dataTable.addColumn('number', 'China');
  dataTable.addColumn('number', 'UK');
  dataTable.addRows([
    ['2000',  94, '',  '', 58, 28],
    ['2004', 101, '',  '', 63, 30],
    ['2008', 110, 'An all time high!', '<img width=100px src="https://upload.wikimedia.org/wikipedia/en/a/a4/Flag_of_the_United_States.svg">', 100, 47],
    ['2012', 104, '',  '', 88, 65]
  ]);

  var options = { tooltip: {isHtml: true}};
  var chart = new google.visualization.LineChart(document.getElementById('tt_6_annotation'));
  chart.draw(dataTable, options);
}

Grafici supportati

• AreaChart
• BarChart
• CalendarChart
• CandlestickChart
• ColumnChart
• ComboChart
• LineChart
• PieChart
• Diagrammi di Sankey
• ScatterChart
• Tempistiche

Se utilizzi i ruoli annotationText o tooltip, consulta la documentazione sui ruoli per informazioni sulle modifiche future e su come evitare problemi in futuro.