نکات ابزار

نکات ابزار: مقدمه

راهنمای ابزار جعبه‌های کوچکی هستند که وقتی ماوس را روی چیزی می‌چرخانید ظاهر می‌شوند. (کارت‌های هاورکارت‌ها کلی‌تر هستند و می‌توانند در هر جایی روی صفحه ظاهر شوند؛ نکات ابزار همیشه به چیزی متصل می‌شوند، مانند یک نقطه در نمودار پراکنده یا یک میله در نمودار میله‌ای.)

در این مستندات، نحوه ایجاد و سفارشی کردن نکات ابزار در نمودارهای گوگل را خواهید آموخت.

تعیین نوع راهنمای ابزار

Google Charts به طور خودکار برای همه نمودارهای اصلی نکات ابزار ایجاد می کند. آنها به طور پیش فرض به صورت SVG ارائه می شوند، به جز در IE 8 که در آن به صورت VML رندر می شوند. می‌توانید با مشخص کردن tooltip.isHtml: true در نمودارهایی که به فراخوانی draw() منتقل می‌شوند، نکات ابزار HTML را در نمودارهای اصلی ایجاد کنید، که به شما امکان ایجاد Tooltip Actions را نیز می‌دهد.

نکات ابزار استاندارد

در غیاب هر گونه محتوای سفارشی، محتوای راهنمای ابزار به طور خودکار بر اساس داده های اساسی تولید می شود. می توانید با نگه داشتن ماوس خود روی هر یک از میله های نمودار، راهنمای ابزار را ببینید.

برای دیدن نکات استاندارد ابزار، نشانگر را روی نوارها نگه دارید.

سفارشی کردن محتوای راهنمای ابزار

در این مثال، با افزودن یک ستون جدید به DataTable و علامت گذاری آن با نقش راهنمای ابزار ، محتوای سفارشی را به راهنمای ابزار اضافه می کنیم.

توجه: این توسط تجسم نمودار حباب پشتیبانی نمی شود.

        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);
      }

استفاده از راهنمای ابزار HTML

این مثال با فعال کردن راهنمای ابزار HTML بر روی نمونه قبلی استوار است. به افزودن tooltip.isHtml: true به گزینه های نمودار توجه کنید.

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);
      }

به نظر تفاوت چندانی ندارد، اما اکنون می‌توانیم HTML را سفارشی کنیم.

سفارشی کردن محتوای HTML

نمونه‌های قبلی همگی از راهنمایی‌های ابزار با محتوای متن ساده استفاده کرده‌اند، اما قدرت واقعی راهنمای ابزار HTML زمانی به دست می‌آید که بتوانید آنها را با استفاده از نشانه‌گذاری HTML سفارشی کنید. برای فعال کردن این کار باید دو کار انجام دهید:

  1. tooltip.isHtml: true در گزینه های نمودار مشخص کنید. این به نمودار می گوید که نکات ابزار را در HTML ترسیم کند (برخلاف SVG).
  2. یک ستون کامل یا یک سلول خاص را در جدول داده با ویژگی سفارشی html علامت گذاری کنید. یک ستون جدول داده با نقش راهنمای ابزار و ویژگی HTML خواهد بود:
    dataTable.addColumn({'type': 'string', 'role': 'tooltip', 'p': {'html': true}})

    توجه: این با تجسم نمودار حباب کار نمی کند. محتوای نکات ابزار Bubble Chart HTML قابل تنظیم نیست.

مهم: مطمئن شوید که HTML در راهنمای ابزار شما از یک منبع قابل اعتماد است. اگر محتوای HTML سفارشی حاوی محتوای تولید شده توسط کاربر باشد، فرار از آن محتوا حیاتی است. در غیر این صورت، تجسم های زیبای شما ممکن است برای حملات XSS باز باشد.

محتوای سفارشی HTML می تواند به سادگی اضافه کردن یک تگ <img> یا پررنگ کردن متنی باشد:

محتوای سفارشی HTML همچنین می تواند شامل محتوای تولید شده به صورت پویا باشد. در اینجا، یک راهنمای ابزار حاوی یک جدول تولید شده به صورت پویا برای هر مقدار دسته اضافه می کنیم. از آنجایی که راهنمای ابزار به مقدار ردیف متصل است، با نگه داشتن ماوس روی هر یک از نوارها، راهنمای ابزار HTML نمایش داده می شود.

این مثال نشان می دهد که چگونه یک راهنمای ابزار سفارشی HTML را می توان به ستون دامنه متصل کرد. (در مثال های قبلی، به یک ستون داده متصل شده بود.) برای روشن کردن راهنمای ابزار برای محور دامنه، گزینه 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>';
}

نکات چرخشی ابزار

نکات ابزار در نمودارهای گوگل را می توان با CSS چرخاند. در نمودار زیر، نکات ابزار با استفاده از این CSS درون خطی، بلافاصله قبل از تقسیم نمودار، 30 درجه در جهت عقربه‌های ساعت چرخانده شده‌اند:

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

توجه داشته باشید که این فقط برای راهنمای ابزار HTML کار می کند، یعنی کسانی که گزینه 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>

قرار دادن نمودارها در راهنمای ابزار

نکات ابزار HTML می تواند شامل اکثر محتوای HTML مورد علاقه شما باشد - حتی یک نمودار Google. با استفاده از نمودارهای داخل راهنمای ابزار، کاربران شما می‌توانند وقتی ماوس را روی یک عنصر داده نگه می‌دارند، اطلاعات بیشتری دریافت کنند: راهی خوب برای ارائه جزئیات سطح بالا در نگاه اول و در عین حال به افراد اجازه می‌دهد در صورت تمایل عمیق‌تر شیرجه بزنند.

نمودار ستونی زیر نموداری از بالاترین میزان بیننده اخیر از چندین رویداد مهم ورزشی را نشان می دهد، با نکات ابزار برای هر یک نمودار خطی از میانگین بینندگان در ده سال گذشته را نشان می دهد.

چند نکته در اینجا قابل ذکر است. ابتدا، یک نمودار قابل چاپ باید برای هر مجموعه داده ترسیم شود تا در یک راهنمای ابزار نشان داده شود. دوم، هر نمودار راهنمای ابزار نیاز به یک کنترل کننده رویداد "آماده" دارد که ما از طریق addListener آن را برای ایجاد یک نمودار قابل چاپ فراخوانی می کنیم.

مهم: همه نمودارهای راهنمای ابزار باید قبل از نمودار اولیه ترسیم شوند. این برای گرفتن تصاویر برای افزودن به DataTable نمودار اولیه ضروری است.

قطعات مهم
      // 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>

اقدامات راهنمای ابزار

راهنمای ابزار همچنین می تواند شامل اقدامات تعریف شده با جاوا اسکریپت باشد. به عنوان یک مثال ساده، در اینجا یک راهنمای ابزار با یک عمل است که وقتی کاربر روی "مشاهده کتاب نمونه" کلیک می کند، یک کادر محاوره ای ظاهر می شود:

گزینه tooltip زمانی فعال می شود که کاربر یک گوه از پای را انتخاب می کند و باعث می شود کد تعریف شده در 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);
      }

اقدامات می توانند visible ، enabled ، هر دو یا هیچکدام باشند. هنگامی که یک نمودار Google رندر می شود، یک عمل راهنمای ابزار فقط در صورتی نشان داده می شود که قابل مشاهده باشد، و فقط در صورت فعال بودن قابل کلیک است. (عملکردهای غیرفعال اما قابل مشاهده خاکستری هستند.)

visible و enabled باید توابعی باشند که مقادیر true یا false را برگردانند. این توابع می توانند به شناسه عنصر و انتخاب کاربر بستگی داشته باشند و به شما این امکان را می دهند که قابلیت مشاهده و کلیک کردن عملکرد را به دقت تنظیم کنید.

نکات ابزار می توانند در focus و همچنین selection فعال شوند. با این حال، با اقدامات راهنمای ابزار، selection ترجیح داده می شود. این باعث می‌شود که راهنمای ابزار باقی بماند و به کاربر امکان می‌دهد عمل را راحت‌تر انتخاب کند.

البته، اقدامات لازم نیست هشدار باشند: هر کاری که می توانید از جاوا اسکریپت انجام دهید، می توانید از یک عمل انجام دهید. در اینجا، ما دو عمل اضافه می کنیم: یکی برای بزرگ کردن یک گوه از نمودار دایره ای خود، و دیگری برای کوچک کردن آن.

        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);
      }

حاشیه نویسی داده ها

می‌توانید با استفاده از annotationText به‌جای tooltip به‌عنوان نقش ستون، متن را مستقیماً روی نمودار Google قرار دهید. (می توانید با نگه داشتن ماوس روی حاشیه نویسی، راهنمای ابزار را ببینید.)

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);
}

نمودارهای پشتیبانی شده

راهنمای ابزار HTML در حال حاضر برای انواع نمودار زیر پشتیبانی می شود:

اگر از نقش‌های annotationText یا tooltip استفاده می‌کنید، لطفاً مستندات مربوط به نقش‌ها را مشاهده کنید تا در مورد تغییرات آینده و نحوه جلوگیری از درد آینده مطالعه کنید.