التلميحات

  1. النصائح حول الأدوات: مقدّمة
  2. تحديد نوع التلميح
  3. تلميحات الأدوات العادية
  4. تخصيص محتوى التلميح
  5. استخدام تلميحات HTML
  6. تخصيص محتوى HTML
  7. عرض تلميحات الأدوات بالتناوب
  8. عرض الرسوم البيانية في تلميحات الأدوات
  9. إجراءات التلميحات
  10. إضافة تعليقات توضيحية على البيانات
  11. الرسوم البيانية المتوافقة

نصائح الأدوات: مقدمة

تلميحات الأدوات هي المربعات الصغيرة التي تنبثق عندما تقوم بالتمرير فوق شيء ما. (البطاقات تكون أكثر عمومية، ويمكن أن تظهر في أي مكان على الشاشة؛ ودائمًا ما يتم إرفاق التلميحات بشيء ما، مثل نقطة على مخطط مبعثر أو شريط على مخطط شريطي).

في هذه الوثائق، ستتعرف على كيفية إنشاء تلميحات وتخصيصها في مخططات Google.

تحديد نوع التلميح

تنشئ "مخططات Google" تلقائيًا تلميحات لجميع الرسوم البيانية الأساسية. سيتم عرض هذه الرموز تلقائيًا بتنسيق SVG (رسومات موجّهة يمكن تغيير حجمها)، باستثناء الإصدار IE 8 الذي سيتم عرضه بتنسيق VML. يمكنك إنشاء تلميحات HTML على الرسوم البيانية الأساسية من خلال تحديد tooltip.isHtml: true في خيارات الرسم البياني التي يتم تمريرها إلى طلب draw()، ما يتيح لك أيضًا إنشاء إجراءات تلميحات الأدوات.

تلميحات الأدوات العادية

في حال عدم توفّر أي محتوى مخصّص، يتم إنشاء محتوى التلميح تلقائيًا استنادًا إلى البيانات الأساسية. يمكنك الاطّلاع على التلميح من خلال تمرير الماوس فوق أي من الأشرطة في الرسم البياني.

مرِّر مؤشر الماوس فوق الأشرطة للاطّلاع على التلميحات العادية.

تخصيص محتوى التلميح

في هذا المثال، نضيف محتوى مخصّصًا إلى التلميحات من خلال إضافة عمود جديد إلى 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}})

    ملاحظة: لا يعمل هذا الرسم مع التمثيل البصري للرسم البياني الفقاعي. إنّ محتوى تلميحات 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>';
}

تدوير التلميحات

يمكن تدوير التلميحات في "مخططات Google" باستخدام CSS. في المخطط أدناه، يتم تدوير التلميحات بزاوية 30 درجة في اتجاه عقارب الساعة باستخدام CSS المضمنة هذه مباشرةً قبل المخطط div:

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

إجراءات النصائح

يمكن أن تتضمّن التلميحات أيضًا إجراءات محدّدة باستخدام JavaScript. على سبيل المثال، إليك تلميحًا يتضمّن إجراءً ينبثق في مربّع حوار عندما ينقر المستخدم على "الاطّلاع على نموذج الكتاب":

يتم تشغيل الخيار 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 دالتين تعرضان قيمًا صحيحة أو خاطئة. وقد تعتمد هذه الوظائف على معرّف العنصر واختيار المستخدم، ما يسمح لك بضبط مستوى رؤية الإجراء وإمكانية النقر عليه.

يمكن أن يتم تشغيل التلميحات على focus وselection أيضًا. مع ذلك، باستخدام إجراءات التلميحات، يُفضّل استخدام selection. يؤدي ذلك إلى استمرار التلميح، مما يسمح للمستخدم بتحديد الإجراء بسهولة أكبر.

بالطبع، لا ينبغي أن تكون الإجراءات تنبيهات، أي أي شيء يمكنك فعله من خلال JavaScript، بل يمكنك تنفيذه من خلال إجراء ما. هنا، سنضيف إجراءين: أحدهما لتكبير إسفين المخطط الدائري، والآخر لتقليصه.

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

التعليق التوضيحي على البيانات

يمكنك تراكب النص مباشرةً في "مخطط Google" باستخدام annotationText بدلاً من tooltip كدور العمود. (يمكنك رؤية التلميح من خلال التمرير فوق التعليق التوضيحي باستخدام الماوس.)

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، يُرجى الاطّلاع على المواد المتعلقة بالأدوار للاطّلاع على التغييرات المستقبلية وكيفية تجنُّب أي مشاكل مستقبلية.