Descrizioni comandi

Descrizione comando: introduzione

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

Con questa documentazione imparerai a creare e personalizzare le descrizioni comando in Google Tables.

Specificare il tipo di descrizione comando

Google grafici crea automaticamente le descrizioni comando per tutti i grafici principali. Il rendering sarà eseguito come SVG per impostazione predefinita, ad eccezione di IE 8, dove verrà visualizzato come VML. Puoi creare descrizioni comando HTML sui grafici principali specificando tooltip.isHtml: true nelle opzioni di grafico trasmesse alla chiamata draw(), che ti consentirà anche di creare azioni descrizione comando.

Descrizioni comandi standard

In assenza di contenuti personalizzati, la descrizione comando viene generata automaticamente in base ai dati sottostanti. Puoi visualizzare la descrizione comando passando il mouse sopra una delle barre nel grafico.

Passa il mouse sopra le barre per visualizzare le descrizioni comando standard.

Personalizzare i contenuti della descrizione comando

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

Nota: questa funzionalità 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);
      }

Utilizzo delle descrizioni comando HTML

L'esempio si basa su quello precedente attivando le descrizioni comando HTML. Osserva 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);
      }

Non sembra molto diverso, ma ora possiamo personalizzare il codice HTML.

Personalizzare i contenuti HTML

Gli esempi precedenti hanno tutte le descrizioni comando utilizzate con contenuti di testo normale, ma il vero potere delle descrizioni comando HTML si verifica quando puoi personalizzarle utilizzando il markup HTML. Per attivare questa funzionalità, devi procedere in due modi:

  1. Specifica tooltip.isHtml: true nelle opzioni del grafico. Questo indica al grafico di tracciare le descrizioni comando in HTML (anziché SVG).
  2. Contrassegna un'intera colonna o una cella specifica nella tabella dati con la proprietà personalizzata html. Una colonna di dati con il ruolo 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 l'HTML nelle descrizioni comando provenga da una fonte attendibile. Se i contenuti HTML personalizzati includono contenuti generati dagli utenti, l'escape è fondamentale. In caso contrario, le splendide visualizzazioni potrebbero aprirsi agli attacchi XSS.

I contenuti HTML personalizzati possono essere semplici come aggiungere un tag <img> o formattare il testo in grassetto:

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

Questo esempio mostra come è possibile associare una descrizione comando HTML personalizzata a una colonna di dominio. Negli esempi precedenti, era collegato 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>';
}

Descrizione dei comandi in rotazione

Le descrizioni comando in Google Tables possono essere ruotate con il CSS. Nel grafico riportato di seguito, le descrizioni comando vengono ruotate di 30° in senso orario utilizzando questo CSS in linea immediatamente prima dell'elemento div del grafico:

<style>div.google-visualization-tooltip { transform: rotate(30deg); }</style>

legend: { location: 'none' }, bar: { groupWidth: '90%' }, colori: ['#A61D4C'] }; var chart = new google.visualization.ColumnChart(document.getElementById('tooltip_rotated'ē chart.draw(data, options); }

Tieni presente che funzionerà solo per le descrizioni comando HTML, ovvero 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 grafici nelle descrizioni comando

Le descrizioni comandi HTML possono includere la maggior parte dei contenuti HTML che ti piacciono, anche un grafico Google. Con i grafici nelle descrizioni comando, i tuoi utenti possono ottenere informazioni aggiuntive quando passano il mouse sopra un elemento di dati: un buon modo per fornire dettagli di alto livello a colpo d'occhio, consentendo agli utenti di approfondire ciò che vogliono.

Il grafico a colonne di seguito mostra un grafico delle visualizzazioni più recenti di diversi eventi sportivi importanti, con le descrizioni comando per ogni grafico con linee delle visualizzazioni medie degli ultimi dieci anni.

Un paio di aspetti da considerare qui. Innanzitutto, per visualizzare un set di dati con una descrizione comando, è necessario tracciare un grafico stampabile. In secondo luogo, ogni grafico con descrizione comando richiede un gestore di eventi "pronto", che chiamiamo tramite addListener per creare un grafico stampabile.

IMPORTANTE:tutti i grafici di descrizione comando devono essere tracciati prima del grafico principale. Questo è necessario per acquisire le immagini da aggiungere alla tabella Data del grafico principale.

Componenti importanti
      // 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);

      }
Pagina web completa
<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. Di seguito viene riportata una descrizione comando con un'azione che viene visualizzata una finestra di dialogo quando l'utente fa clic su "Visualizza libro di esempio":

L'opzione tooltip si attiva quando l'utente seleziona una porzione di torta, in modo da eseguire il 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. (Le opzioni disattivate sono disattivate, ma sono in grigio.)

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

Le descrizioni comando possono essere attivate sia su focus sia su selection. Tuttavia, con azioni descrizione comando, è preferibile selection. In questo modo, la descrizione comando persiste, consentendo all'utente di selezionare l'azione più facilmente.

Le azioni non devono essere avvisi, ovviamente: tutto quello che puoi fare da JavaScript, puoi farlo da un'azione. Aggiungeremo due azioni: una per ingrandire un grafico a torta e l'altra per ridurlo.

        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 a un grafico Google utilizzando annotationText invece di tooltip come ruolo della colonna. Puoi visualizzare la descrizione comando passando il mouse sopra l'annotazione con il mouse.

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

Le descrizioni comando HTML sono attualmente supportate per i seguenti tipi di grafici:

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