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

  1. نظرة عامة
  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 درجات".

خيارات الضبط

الاسم
سماح HTML

وفي حال ضبطها على "صحيح"، سيتم عرض أي نص تعليق توضيحي يتضمن علامات HTML بتنسيق HTML.

النوع: منطقي
تلقائي: خطأ
كل القيم

لاحقة تُضاف إلى جميع القيم في رموز التسمية التوضيحية والمؤشرات في المحاور العمودية.

النوع: سلسلة
افتراضي: بدون
عرض التعليقات التوضيحية

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

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

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

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

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

النوع: سلسلة
تلقائي: اكتب "MMMM dd, yyyy" أو "HH:mm MMMM dd, yyyy"، حسب نوع العمود الأول (التاريخ أو التاريخ، على التوالي).
التعليقات التوضيحية على الشبكة الإعلانية

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

النوع: منطقي
افتراضي: صحيح
عرض التعليقات التوضيحية

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

النوع: منطقي
تلقائي: خطأ
DisplayDateBarفاصل

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

النوع: منطقي
افتراضي: صحيح
قيم الشبكة الإعلانية بالضبط

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

النوع: منطقي
تلقائي: خطأ
شاشة عرض التسمية التوضيحية

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

النوع: منطقي
افتراضي: صحيح
قيم أسطورية العرض

ما إذا كان سيتم عرض القيم المميزة في وسيلة الإيضاح، حيث يعني true أنه نعم.

النوع: منطقي
افتراضي: صحيح
تحديد نطاق العرض

يمكنك اختيار إظهار منطقة اختيار نطاق التكبير أو التصغير (المنطقة أسفل الرسم البياني)، حيث تشير القيمة "خطأ" إلى "لا".

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

النوع: منطقي
افتراضي: صحيح
أزرار تكبير/تصغير العرض

ما إذا كان سيتم إظهار أزرار التكبير أو التصغير ("1d 5d 1m وما إلى ذلك")، حيث يعني false "لا".

النوع: منطقي
افتراضي: صحيح
fill

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

النوع: الرقم
القيمة التلقائية: 0
موضع التسمية التوضيحية

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

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

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

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

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

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

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

النوع: الرقم
افتراضي: تلقائي
تنسيق الأرقام

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

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

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

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

    لست بحاجة إلى تضمين تنسيق لكل سلسلة على الرسم البياني، لأنّ أي سلسلة غير محدّدة ستستخدم التنسيق التلقائي.

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

النوع: سلسلة أو خريطة رقم:أزواج من السلاسل
افتراضي: تلقائي
مقياس الأعمدة

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

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

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

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

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

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

النوع: سلسلة
تلقائي: '#'
نوع المقياس

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

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

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

النوع: سلسلة
تلقائي: "تم الإصلاح"
جدول

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

var options: {
  table: {
    sortAscending: true,
    sortColumn: 1
  }
};
النوع: الكائن
تلقائي: null
table.sortAscending

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

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

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

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

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

النوع: الرقم
القيمة التلقائية: 0
وقت الانتهاء/التكبير

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

النوع: التاريخ
افتراضي: بدون
وقت بدء التكبير/التصغير

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

النوع: التاريخ
افتراضي: بدون

الطرق

الطريقة
clearChart()

محو الرسم البياني وإصدار جميع الموارد المخصّصة له

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

لرسم المخطط.

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

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

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

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

نوع العرض: مصفوفة من عناصر التحديد
getVisibleChartRange()

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

نوع العرض: كائن بخاصيتين start وend
hideDataColumns(columnIndexes)

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

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

لتعيين النطاق المرئي (تكبير/تصغير) إلى النطاق المحدد. تقبل معلّمتَين من النوع Date تمثّلان المرّتين الأولى والأخيرة للنطاق المرئي المختار المختار. اضبط start على null ليتضمن كل شيء من تاريخ البدء إلى 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().

الخصائص: بلا

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

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