مخطط التعليقات التوضيحية

  1. Overview
  2. مثال
  3. جارٍ التحميل
  4. تنسيق البيانات
  5. خيارات الإعداد
  6. الطُرق
  7. الأحداث
  8. سياسة البيانات
  9. Notes

نظرة عامة

مخططات التعليقات التوضيحية هي مخططات خطية تفاعلية لسلسلة زمنية تدعم التعليقات التوضيحية. لاحظ أن المخطط الزمني التوضيحي يستخدم الآن تلقائيًا مخطط التعليقات التوضيحية.

تنبيه الالتباس: يختلف حاليًا الرسم البياني للتعليقات التوضيحية من Google عن التعليقات التوضيحية التي تدعمها الرسوم البيانية الأخرى في Google (حاليًا استنادًا إلى المنطقة المساحية والشريطية والعمودية والمختلطة والخطية والنقاط المبعثرة). في تلك المخططات، يتم تحديد التعليقات التوضيحية في عمود جدول بيانات منفصل، وعرضها كأجزاء قصيرة من النص يمكن للمستخدمين التمرير فوقها لرؤية نص التعليق التوضيحي بالكامل. وفي المقابل، يعرض مخطط التعليقات التوضيحية التعليقات التوضيحية الكاملة على الجانب الأيمن، كما هو موضح أدناه.

مثال

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

      function drawChart() {
        var data = new google.visualization.DataTable();
        data.addColumn('date', 'Date');
        data.addColumn('number', 'Kepler-22b mission');
        data.addColumn('string', 'Kepler title');
        data.addColumn('string', 'Kepler text');
        data.addColumn('number', 'Gliese 163 mission');
        data.addColumn('string', 'Gliese title');
        data.addColumn('string', 'Gliese text');
        data.addRows([
          [new Date(2314, 2, 15), 12400, undefined, undefined,
                                  10645, undefined, undefined],
          [new Date(2314, 2, 16), 24045, 'Lalibertines', 'First encounter',
                                  12374, undefined, undefined],
          [new Date(2314, 2, 17), 35022, 'Lalibertines', 'They are very tall',
                                  15766, 'Gallantors', 'First Encounter'],
          [new Date(2314, 2, 18), 12284, 'Lalibertines', 'Attack on our crew!',
                                  34334, 'Gallantors', 'Statement of shared principles'],
          [new Date(2314, 2, 19), 8476, 'Lalibertines', 'Heavy casualties',
                                  66467, 'Gallantors', 'Mysteries revealed'],
          [new Date(2314, 2, 20), 0, 'Lalibertines', 'All crew lost',
                                  79463, 'Gallantors', 'Omniscience achieved']
        ]);

        var chart = new google.visualization.AnnotationChart(document.getElementById('chart_div'));

        var options = {
          displayAnnotations: true
        };

        chart.draw(data, options);
      }
    </script>
  </head>

  <body>
    <div id='chart_div' style='width: 900px; height: 600px;'></div>
  </body>
</html>

جارٍ التحميل

اسم حزمة "google.charts.load" هو "annotationchart".

  google.charts.load("current", {packages: ['annotationchart']});

اسم فئة العرض المرئي هو google.visualization.AnnotationChart.

  var visualization = new google.visualization.AnnotationChart(container);

تنسيق البيانات

يمكنك عرض خط أو أكثر في المخطط. ويمثّل كل صف الموضع X على الرسم البياني، أي وقت محدّد، ويتم وصف كل خط من خلال مجموعة من عمود واحد إلى ثلاثة أعمدة.

  • العمود الأول من النوع date أو datetime، ويحدّد القيمة X للنقطة على الرسم البياني. إذا كان هذا العمود من النوع date (وليس datetime)، تكون أصغر درجة دقة زمنيًا على المحور "س" هي يوم واحد.
  • بعد ذلك، يتم وصف كل خط بيانات من خلال مجموعة من عمود إلى ثلاثة أعمدة إضافية كما هو موضّح هنا:
    • قيمة Y - [مطلوبة، العدد] يصف العمود الأول في كل مجموعة قيمة السطر في الوقت المقابل من العمود الأول. يتم عرض تصنيف العمود على الرسم البياني كعنوان ذلك الخط.
    • عنوان التعليق التوضيحي - [اختيارية، سلسلة] إذا كان عمود السلسلة يتبع عمود القيمة وكان الخيار displayAnnotations صحيحًا، يتضمّن هذا العمود عنوانًا قصيرًا يصف هذه النقطة. على سبيل المثال، إذا كان هذا الخط يمثّل درجة الحرارة في البرازيل، وكانت هذه النقطة عددًا كبيرًا جدًا، يمكن أن يكون العنوان "أكثر يوم مسجَّل".
    • نص التعليق التوضيحي - [سلسلة اختيارية] في حال توفُّر عمود سلسلة ثانٍ لهذه السلسلة، سيتم استخدام قيمة الخلية كنص وصفي إضافي لهذه النقطة. ويجب ضبط الخيار displayAnnotations على "صحيح" لاستخدام هذا العمود. يمكنك استخدام علامات HTML في حال ضبط السمة allowHtml على true، إذ ليس هناك حدّ أقصى للحجم، ولكن يُرجى العلم أنّ الإدخالات الطويلة جدًا قد تتجاوز قسم العرض. ولا يُشترط إدراج هذا العمود حتى إذا كان لديك عمود لعنوان التعليق التوضيحي لهذه النقطة. لا يستخدم الرسم البياني تصنيف العمود. على سبيل المثال، إذا كان هذا اليوم أشد الأيام حرارة في نقطة التسجيل، يمكنك مثلاً قول "درجة حرارة اليوم الأقرب التالية كانت أكثر برودة بمقدار 10 درجات".

خيارات الضبط

الاسم
allowHtml

إذا تم تعيينها على "true"، فسيتم عرض أي نص تعليق توضيحي يتضمن علامات HTML كـ HTML.

النوع: قيمة منطقية
الإعداد التلقائي: خطأ
allValuesSuffix

لاحقة ستتم إضافتها إلى جميع القيم في وسيلة الإيضاح وتسميات علامات التجزئة في المحاور الرأسية.

النوع: سلسلة
تلقائي: بدون
annotationsWidth

عرض منطقة التعليقات التوضيحية (بالنسبة المئوية) خارج منطقة الرسم البياني بالكامل ويجب أن يكون رقمًا يتراوح بين 5 و80.

النوع: رقم
القيمة التلقائية: 25
الألوان

الألوان المراد استخدامها لخطوط وتسميات الرسم البياني. مصفوفة من السلاسل. ويكون كل عنصر عبارة عن سلسلة بتنسيق لون HTML صالح. على سبيل المثال، "أحمر" أو " #00cc00".

النوع: مصفوفة من السلاسل
تلقائي: الألوان التلقائية
dateFormat

تمثّل هذه السمة التنسيق المستخدَم لعرض معلومات التاريخ في أعلى يسار الصفحة. ويكون تنسيق هذا الحقل كما هو محدّد في فئة java SimpleDateFormat.

النوع: سلسلة
الوضع التلقائي: إما "ي ي ش ش ش ش س س س س" أو "س س:د ش ش ش ي ي، س س س س"، استنادًا إلى نوع العمود الأول (التاريخ أو التاريخ أو الوقت على التوالي).
displayAnnotations

في حال ضبط هذه السياسة على "خطأ"، سيخفي الرسم البياني جدول التعليقات التوضيحية، ولن تظهر التعليقات التوضيحية والتعليقات التوضيحية النصية (لن يتم عرض جدول التعليقات التوضيحية أيضًا في حال عدم توفّر تعليقات توضيحية في بياناتك، بصرف النظر عن هذا الخيار). عند ضبط هذا الخيار على "صحيح"، بعد كل عمود رقمي، يمكن إضافة عمودَين اختياريَين لسلسلة التعليقات التوضيحية، أحدهما لعنوان التعليق التوضيحي والآخر لنص التعليق التوضيحي.

النوع: قيمة منطقية
القيمة التلقائية:صحيح
displayAnnotationsFilter

في حال ضبط هذه السياسة على "صحيح"، سيعرض الرسم البياني عنصر تحكُّم في الفلترة لفلترة التعليقات التوضيحية. استخدِم هذا الخيار عند توفّر عدد كبير من التعليقات التوضيحية.

النوع: قيمة منطقية
الإعداد التلقائي: خطأ
displayDateBarSeparator

لتحديد ما إذا كان سيتم عرض فاصل شريط صغير ( | ) بين قيم السلسلة والتاريخ في وسيلة الإيضاح، حيث تعني القيمة "نعم" نعم.

النوع: قيمة منطقية
القيمة التلقائية:صحيح
displayExactValues

لتحديد ما إذا كان سيتم عرض نسخة مختصرة ومقربة من القيم في أعلى الرسم البياني لتوفير مساحة، تشير القيمة "خطأ" إلى احتمال ذلك. على سبيل المثال، في حال الضبط على "خطأ"، قد يتم عرض القيمة 56123.45 على أنّها 56.12 ألف.

النوع: قيمة منطقية
الإعداد التلقائي: خطأ
displayLegendDots

تحديد ما إذا كان سيتم عرض النقاط بجانب القيم في نص وسيلة الإيضاح، حيث تعني القيمة "نعم" نعم.

النوع: قيمة منطقية
القيمة التلقائية:صحيح
displayLegendValues

لتحديد ما إذا كان سيتم عرض القيم المميزة في وسيلة الإيضاح، حيث تعني القيمة "صحيح" نعم.

النوع: قيمة منطقية
القيمة التلقائية:صحيح
displayRangeSelector

تحديد ما إذا كان سيتم عرض منطقة اختيار نطاق التكبير أو التصغير (المنطقة في أسفل الرسم البياني)، حيث تعني القيمة "لا" "لا".

المخطط في أداة اختيار التكبير/التصغير هو إصدار مقياس سجل للسلسلة الأولى في الرسم البياني، وقد تم تعديله ليلائم ارتفاع أداة اختيار التكبير/التصغير.

النوع: قيمة منطقية
القيمة التلقائية:صحيح
displayZoomButtons

تحديد ما إذا كان سيتم عرض أزرار التكبير/التصغير ("1d 5d 1m" وهكذا)، بينما تعني القيمة "خطأ" لا.

النوع: قيمة منطقية
القيمة التلقائية:صحيح
fill

رقم من 0 إلى 100 (شامل) يحدّد ألفا التعبئة أسفل كل سطر في الرسم البياني الخطي. وتعني القيمة 100 أنّ القيمة معتمة بنسبة 100%، في حين تعني القيمة 0 عدم التعبئة على الإطلاق. ويكون لون التعبئة هو لون السطر نفسه الذي يظهر فوقه.

النوع: رقم
القيمة التلقائية: 0
legendPosition

لتحديد ما إذا كان سيتم وضع وسيلة الإيضاح الملونة في الصف نفسه مع أزرار التكبير/التصغير والتاريخ ('sameRow') أو على صف جديد ('newRow).

النوع: سلسلة
الإعداد التلقائي: "sameRow"
الحد الأقصى

الحد الأقصى للقيمة التي يتم عرضها على المحور "ص" إذا تجاوز الحد الأقصى لنقطة البيانات هذه القيمة، سيتم تجاهل هذا الإعداد، وسيتم ضبط الرسم البياني لعرض علامة الاختيار الرئيسية التالية فوق الحد الأقصى لنقطة البيانات. وستكون له الأولوية على الحد الأقصى للمحور "ص" الذي تحدّده السمة scaleType.

يشبه ذلك maxValue في الرسوم البيانية الأساسية.

النوع: رقم
تلقائي: تلقائي
دقيقة

أدنى قيمة يمكن عرضها على المحور "ص". إذا كان الحد الأدنى لنقطة البيانات أقل من هذه القيمة، سيتم تجاهل هذا الإعداد، وسيتم ضبط الرسم البياني لعرض علامة التجزئة الرئيسية التالية أسفل الحد الأدنى لنقطة البيانات. وسيكون له الأولوية على الحد الأدنى للمحور "ص" الذي تحدّده السمة scaleType.

يشبه ذلك minValue في الرسوم البيانية الأساسية.

النوع: رقم
تلقائي: تلقائي
numberFormats

تحدّد هذه السمة أنماط تنسيق الأرقام التي سيتم استخدامها لتنسيق القيم في أعلى الرسم البياني.

يجب أن تكون الأنماط بالتنسيق كما هو محدّد في فئة java DecimalFormat.

  • إذا لم يتم تحديده، يتم استخدام نمط التنسيق التلقائي.
  • إذا تم تحديد نمط سلسلة واحد، فسيتم استخدامه لجميع القيم.

  • إذا تم تحديد خريطة، تكون المفاتيح هي فهارس (قائمة على صفر) للسلاسل، والقيم هي الأنماط التي سيتم استخدامها لتنسيق السلسلة المحدّدة.

    ليس مطلوبًا منك تضمين تنسيق لكل سلسلة في الرسم البياني، لأنّ أي سلسلة غير محدّدة ستستخدم التنسيق التلقائي.

وفي حال تحديد هذا الخيار، سيتم تجاهل الخيار "displayExactValues".

النوع: سلسلة، أو خريطة لأزواج السلسلة والرقم
تلقائي: تلقائي
scaleColumns

لتحديد القيم التي سيتم عرضها على علامات التجزئة للمحور ص في الرسم البياني. والإعداد التلقائي هو أن يكون هناك مقياس واحد في الجانب الأيمن، وهذا ينطبق على كلتا السلسلتين، ولكن يمكنك تعديل جوانب مختلفة من الرسم البياني لتتناسب مع قيم سلسلة مختلفة.

يأخذ هذا الخيار مصفوفة من صفر إلى ثلاثة أرقام تحدد الفهرس (المستنِد إلى صفر) للسلسلة لاستخدامها كقيمة المقياس. ويعتمد مكان ظهور هذه القيم على عدد القيم التي تدرجها في الصفيف:

  • إذا حددت صفيفًا فارغًا، فلن يعرض الرسم البياني قيم Y بجانب علامات التجزئة.
  • إذا حدَّدت قيمة واحدة، سيتم عرض مقياس السلسلة المُشار إليه على الجانب الأيسر من الرسم البياني فقط.
  • إذا حددت قيمتين، ستتم إضافة مقياس للسلسلة الثانية إلى يسار الرسم البياني.
  • إذا حددت ثلاث قيم، ستتم إضافة مقياس للسلسلة الثالثة إلى منتصف الرسم البياني.
  • وسيتم تجاهل أي قيم بعد القيمة الثالثة في الصفيف.

عند عرض أكثر من مقياس واحد، يُنصح بضبط الخيار scaleType على "allfixed" أو "allmaximized".

النوع: مصفوفة من الأرقام
تلقائي: تلقائي
scaleFormat

تنسيق الأرقام الذي سيتم استخدامه لتصنيفات علامات المحور. ويتم عرض القيمة التلقائية للسمة '#' كعدد صحيح.

النوع: سلسلة
تلقائي: nofollow
scaleType

لتعيين الحد الأقصى والأدنى للقيم المعروضة على المحور "ص". وتتوفّر الخيارات التالية:

  • "maximized" - المحور ص سيمتد من الحد الأدنى إلى الحد الأقصى لقيم السلسلة. إذا كان لديك أكثر من سلسلة واحدة، استخدِم allmaximized.
  • 'fixed' [default] - يختلف المحور ص حسب قيم البيانات:
    • إذا كانت جميع القيم >=0، فسيمتد المحور ص من صفر إلى الحد الأقصى لقيمة البيانات.
    • إذا كانت جميع القيم <=0، فسيمتد المحور ص من صفر إلى أدنى قيمة بيانات.
    • إذا كانت القيمتان موجبة وسالبة، سيتراوح المحور ص بين الحد الأقصى للسلسلة والحد الأدنى في السلسلة.
      بالنسبة إلى السلاسل المتعددة، استخدِم القيمة "allfixed".
  • "allmaximized": مثل "maximized"، ولكن يُستخدم عند عرض مقاييس متعددة. سيتم تكبير كِلا الرسمين البيانيين ضمن المقياس نفسه، ما يعني أنّه سيتم عرض أحدهما بشكل مضلل على المحور "ص"، ولكن التمرير فوق كل سلسلة سيعرض قيمته الحقيقية.
  • "allfixed": مماثلة لـ "fixed"، ولكن يتم استخدامها عند عرض مقاييس متعددة. يعدّل هذا الإعداد كل مقياس وفقًا للسلسلة التي ينطبق عليها (استخدِم هذا الإعداد مع scaleColumns).

إذا حددت الحدّ الأدنى و/أو الحدّ الأقصى للخيارات، ستكون لها الأولوية على الحدّ الأدنى والأقصى للقيم التي يحدّدها نوع المقياس.

النوع: سلسلة
الإعداد التلقائي: "ثابت"
جدول

يحتوي على خيارات ذات صلة بجدول التعليقات التوضيحية. لتحديد خصائص هذا الكائن، يمكنك استخدام الترميز الحرفي للكائن: 

var options: {
  table: {
    sortAscending: true,
    sortColumn: 1
  }
};
Type: كائن
الإعداد التلقائي: قيمة خالية
table.sortAscending

في حال ضبط القيمة على true، سيؤدي ذلك إلى عكس ترتيب جدول التعليقات التوضيحية وعرضها بترتيب تصاعدي.

النوع: قيمة منطقية
الإعداد التلقائي: خطأ
table.sortColumn

فهرس العمود لجدول التعليقات التوضيحية الذي سيتم فرز التعليقات التوضيحية له. يجب أن يكون الفهرس 0 لعمود تصنيف التعليق التوضيحي أو 1 لعمود نص التعليق التوضيحي.

النوع: رقم
القيمة التلقائية: 0
السُمك

رقم من 0 إلى 10 (شامل) يحدّد سُمك الخطوط، بحيث يكون الرقم 0 هو الأقل سمكًا.

النوع: رقم
القيمة التلقائية: 0
zoomEndTime

لضبط تاريخ/وقت الانتهاء لنطاق التكبير/التصغير المحدّد.

النوع: التاريخ
تلقائي: بدون
zoomStartTime

لضبط تاريخ/وقت البدء لنطاق التكبير/التصغير المحدّد.

النوع: التاريخ
تلقائي: بدون

الطُرق

الطريقة
clearChart()

يؤدي هذا الإجراء إلى محو الرسم البياني وتحرير جميع الموارد المخصّصة له.

نوع الإرجاع: لا شيء
draw(data, options, state)

لرسم الرسم البياني.

نوع الإرجاع: لا شيء
getContainer()

لاسترداد اسم معرِّف لعنصر الحاوية الذي يحتوي على الرسم البياني للتعليقات التوضيحية.

نوع الإرجاع: التعامل مع عنصر DOM
getSelection()

تنفيذ getSelection() عادي. العناصر المحددة هي عناصر الخلية. يمكن للمستخدم اختيار خلية واحدة فقط في كل مرة.

نوع الإرجاع: مصفوفة من عناصر الاختيار
getVisibleChartRange()

تعرض كائنًا بالسمتَين start وend، وكلٌّ منهما عبارة عن كائن Date، ويمثّل اختيار الوقت الحالي.

نوع الإرجاع: كائن بالسمتَين start وend
hideDataColumns(columnIndexes)

يؤدي هذا الإجراء إلى إخفاء سلسلة البيانات المحدّدة من الرسم البياني. يتم قبول مَعلمة واحدة يمكن أن تكون رقمًا أو مصفوفة أرقام، حيث يشير 0 إلى سلسلة البيانات الأولى، وهكذا.

نوع الإرجاع: لا شيء
setVisibleChartRange(start, end)

لضبط النطاق المرئي (تكبير/تصغير) على النطاق المحدّد. يتم قبول مَعلمتَين من النوع Date تمثّلان الوقتَين الأول والأخير للنطاق المرئي المحدَّد. اضبط start على قيمة فارغة لتضمين كل شيء من أقرب تاريخ إلى end، اضبط end على قيمة خالية لتضمين كل شيء من start إلى التاريخ الأخير.

نوع الإرجاع: لا شيء
showDataColumns(columnIndexes)

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

نوع الإرجاع: لا شيء

الأحداث

الاسم
rangechange

يتم الإطلاق عندما يغيّر المستخدم شريط تمرير النطاق. ستكون نقاط نهاية النطاق الجديدة متاحة على الشكلَين event['start'] وevent['end']: 

google.visualization.events.addListener(chart, 'rangechange', rangechange_handler);

function rangechange_handler(e) {
  console.log('You changed the range to ', e['start'], ' and ', e['end']);
}
الخصائص: البداية والنهاية
ready

الرسم البياني جاهز لاستدعاءات الطرق الخارجية. إذا كنت تريد التفاعل مع الرسم البياني وطرق الاتصال بعد رسمه، عليك إعداد أداة معالجة لهذا الحدث قبل استدعاء طريقة draw، وعدم الاتصال بها إلا بعد تنشيط الحدث.

الخصائص: غير محدّدة
select

يتم الإطلاق عندما ينقر المستخدم على عنصر مرئي. لمعرفة ما تم اختياره، يمكنك الاتصال بالرقم getSelection().

الخصائص: غير محدّدة

سياسة البيانات

تتم معالجة جميع الرموز والبيانات وعرضها في المتصفّح. ولا يتم إرسال أي بيانات إلى أي خادم.