إنشاء أنواع المخططات

تصف هذه الصفحة كيفية إعداد نوع المخطط الخاص بك وجعله متاحًا للمستخدمين.

الجمهور

تفترض هذه الصفحة أنّك قرأت صفحة استخدام الرسومات البيانية. ويُفترض أيضًا أنّك على دراية JavaScript والبرمجة المتعلّقة بالكائنات. هناك العديد من البرامج التعليمية لـ JavaScript على الويب.

إنشاء رسم بياني

تظهر الرسوم البيانية للمستخدم من خلال مكتبة JavaScript التي تنشئها. فيما يلي خطوات إنشاء مكتبة مخططات:

1. اختَر مساحة اسم للرمز الخاص بك. وستستضيف صفحات أخرى الرمز الخاص بك، لذا ننصحك بتجنُّب تعارض الأسماء.
2. تنفيذ كائن الرسم البياني. تنفيذ كائن JavaScript يعرض ما يلي:
   • أداة الإنشاء
   • هي طريقة draw() لرسم كائن داخل عنصر DOM تم تمريره إلى الدالة الإنشائية.
   • أي طرق معيارية اختيارية أخرى يمكن للعميل استخدامها، مثل getSelection()
   • أي طرق مخصّصة تريد عرضها لعملائك.
3. [اختياري] نفِّذ أي أحداث تريد تنشيطها ليكتشفها العميل.
4. اكتب مستندات الرسم البياني. إذا لم توثِّقه، لن يتمكّن المستخدمون على الأرجح من تضمينه.
5. انشر الرسم البياني في معرض الرسومات البيانية.

اختيار مساحة الاسم

يمكن تضمين الرسم البياني في صفحة تستضيف رسومات بيانية أخرى أو محتوى JavaScript آخر غير ذي صلة. لتجنّب تعارض الأسماء مع الرموز الأخرى أو أسماء فئات CSS الأخرى، يجب اختيار مساحة اسم فريدة لرمز الرسم البياني. يُعدّ عنوان URL الذي ستستخدمه لاستضافة النص البرمجي الخيار الجيد ضمن مساحة الاسم (باستثناء WWW وأي إضافات). على سبيل المثال، إذا تم نشر الرسم البياني على www.example.com، ستستخدم example كمساحة الاسم الفريدة. يمكنك إضافة لاحقات أخرى، مفصولة بفواصل . العلامات، لتجميع رسم بياني معيّن بشكل أكبر (تتضمّن جميع الرسومات البيانية في Google مساحة الاسم google.visualization). يمكنك استخدام عنصر مساحة الاسم لتخزين عنصر الرسم البياني، بالإضافة إلى أي متغيّرات عمومية قد تكون مطلوبة.

في ما يلي مثال على إنشاء كائن مساحة اسم للاحتفاظ بفئة رسم بياني تُسمى MyTable، بالإضافة إلى أي متغيّرات عمومية مطلوبة:

// Namespace, implemented as a global variable.
var example = {};

// MyTable class constructor.
example.MyTable = function(container) {
  // ...
}

// MyTable.draw() method.
example.MyTable.prototype.draw = function(data, options) {
  // ...
}

تجنُّب تعارضات CSS

إذا كنت تستخدم CSS، احرص على عدم كتابة قواعد CSS يمكن أن تؤثر في الرسومات البيانية الأخرى على الصفحة. على سبيل المثال، لا يُنصح باستخدام قاعدة مثل td {color: blue;}، لأنّ ذلك سيؤثر في أي عنصر <td> آخر على الصفحة، وليس فقط في الرسم البياني. لحلّ هذه المشكلة، يمكنك تضمين الرسم البياني بالكامل في <div> مع اسم فئة، و تطبيق جميع قواعد CSS على العناصر التابعة لعنصر يحمل اسم الفئة هذا. على سبيل المثال، ستؤثّر قاعدة CSS التالية فقط في عناصر <td> التي تتضمّن عنصرًا يحمل اسم الفئة "example" كعنصر أصل.

td.example {color: blue;}

بعد ذلك، يمكنك التفاف الرسم البياني في <div> باستخدام :

<div class="example">
  ...
</div>

تنفيذ الرسم البياني

وعليك تنفيذ الرسم البياني على شكل كائن JavaScript يعرض الطرق العادية الموضّحة في القسم المرجعي. الطريقتان المطلوبتان هما الطريقة الإنشائية وطريقة الرسم()). يمكنك أيضًا أن تعرض للمستخدم أي طرق إضافية مناسبة للرسم البياني. ولكن تذكر أن سهولة الاستخدام هي الأفضل.

المنشئ

يجب أن يعرض الرسم البياني دالة إنشاء واحدة تستخدم مَعلمة واحدة، وهي عنصر DOM الذي سترسم فيه الرسم البياني. وتخزِّن الرسوم البيانية عادةً نسخة محلية من هذا العنصر في الدالة الإنشائية لاستخدامها لاحقًا.

function example.MyTable(container) {
  this.container = container
}

طريقة draw()

يجب أن تحتوي فئة الرسم البياني على طريقة draw() محددة في النموذج الأولي لفئة المخطط. تقبل الطريقة draw() مَعلمتَين، هما:

1. تمثّل هذه السمة DataTable تحتفظ بالبيانات لعرضها.
2. خريطة اختيارية لخيارات الاسم/القيمة للرسم البياني وتحدِّد أنت أسماء الخيارات وأنواعها في الرسم البياني الخاص بك. على سبيل المثال، في مثال Hello Chart أدناه، يتيح الرسم البياني خيارًا يُسمى showLineNumber بقيمة من النوع المنطقي. ويجب إتاحة قيمة تلقائية لكل خيار، في حال لم يمرّر المستخدم قيمة لخيار معيّن. هذه المَعلمة اختيارية، لذا عليك أيضًا الاستعداد لاستخدام جميع القيم التلقائية إذا لم يمرّر المستخدم هذه المَعلمة (مزيد من المعلومات).

example.MyTable.prototype.draw = function(data, options) {
  // Process data and options and render output into the container element.
  ...
}

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

إليك رسم بياني بسيط يعرض بيانات DataTable كجدول HTML:

وإليك رمز التنفيذ:

// Declare a unique namespace.
var example = {};

// Class constructor. Parameter container is a DOM elementon the client that
// that will contain the chart.
example.MyTable = function(container) {
  this.containerElement = container;
}

// Main drawing logic.
// Parameters:
//   data is data to display, type google.visualization.DataTable.
//   options is a name/value map of options. Our example takes one option.
example.MyTable.prototype.draw = function(data, options) {

  // Create an HTML table
  var showLineNumber = options.showLineNumber; // Boolean configuration option.

  var html = [];
  html.push('<table border="1">');

  // Header row
  html.push('<tr>');
  if (showLineNumber) {
    html.push('<th>Seq</th>');
  }
  for (var col = 0; col < data.getNumberOfColumns(); col++) {
    html.push('<th>' + this.escapeHtml(data.getColumnLabel(col)) + '</th>');
  }
  html.push('</tr>');

  for (var row = 0; row < data.getNumberOfRows(); row++) {
    html.push('<tr>');
    if (showLineNumber) {
      html.push('<td align="right">', (row + 1), '</td>');
    }

    for (var col = 0; col < data.getNumberOfColumns(); col++) {
      html.push(data.getColumnType(col) == 'number' ? '<td align="right">' : '<td>');
      html.push(this.escapeHtml(data.getFormattedValue(row, col)));
      html.push('</td>');
    }
    html.push('</tr>');
  }
  html.push('</table>');

  this.containerElement.innerHTML = html.join('');
}

// Utility function to escape HTML special characters
example.MyTable.prototype.escapeHtml = function(text) {
  if (text == null)
    return '';
  return text.replace(/&/g, '&').replace(/</g, '<')
      .replace(/>/g, '>').replace(/"/g, '"');
}

تضمين المخطط في صفحة ويب

لاستخدام المخطط السابق، احفظه في ملف js .يمكن الوصول إليه من المتصفح. بعد ذلك، احفظ الرمز التالي، مع تغيير معلَمة المصدر <script> للتوجيه إلى ملف JavaScript:

<html>
  <head>
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type="text/javascript" src="mytablevis.js"></script>
    <script type="text/javascript">
      google.charts.load("current");

      // Set callback to run when API is loaded
      google.charts.setOnLoadCallback(drawVisualization);

      // Called when the Chart API is loaded.
      function drawVisualization() {

        // Create and populate a data table.
        var data = new google.visualization.DataTable();
        data.addColumn('string', 'Task');
        data.addColumn('number', 'Daily Hours');
        data.addRows(5);
        data.setCell(0, 0, 'Work');
        data.setCell(0, 1, 11);
        // Add more data rows and cells here

        // Instantiate our table object.
        var vis = new example.MyTable(document.getElementById('mydiv'));

        // Draw our table with the data we created locally.
        vis.draw(data, {showLineNumber: true});
       }
   </script>
  <title>MyTable example page</title></head>
  <body>
    <div id="mydiv"></div>
    <p>This page demonstrates hosting a table visualization.</p>
  </body>
</html>

 

تنفيذ الأحداث

إذا كنت تريد أن ينشط الرسم البياني أحداثًا مفيدة (على سبيل المثال، أحداث الموقّت أو الأحداث التي يبدأها المستخدم مثل النقرات)، ستحتاج إلى استدعاء الدالة google.visualization.events.trigger مع تفاصيل الحدث (الاسم والخصائص المطلوب إرسالها وما إلى ذلك). يمكنك العثور على التفاصيل في صفحة الأحداث. يمكنك عرض تفاصيل الحدث للعميل من خلال إضافة سمات إلى كائن الحدث، أو يمكنك عرض طريقة get...() من نوع ما على الرسم البياني، ويمكن للعميل استدعاء هذه الطريقة للحصول على تفاصيل الحدث. في كلتا الحالتين، عليك توثيق الطُرق أو خصائص الفعاليات جيدًا.

توثيق الرسم البياني

إذا لم توثق المخطط بشكل صحيح، فمن المحتمل ألا تحصل على العديد من المستخدمين. تأكد من توثيق ما يلي:

• قدِّم وصفًا لجميع الطرق التي تدعمها. ويمكن استخدام طريقة draw() في جميع الرسومات البيانية، ولكن يمكن أن يتيح كل رسم بياني أساليبه الإضافية الخاصة. (لن تحتاج على الأرجح إلى توثيق الدالة الإنشائية، ما لم تكن تستخدم سلوكًا غير عادي). يمكنك العثور على قائمة بالطرق المتوقّعة في الصفحة المرجعية.
• يُرجى وصف جميع الخيارات المتوافقة مع طريقة draw(). ويتضمّن ذلك اسم كل خيار ونوع القيمة المتوقّع وقيمته التلقائية.
• قدِّم وصفًا لجميع الأحداث التي تبدأها. ويشير ذلك إلى اسم كل حدث وخصائصه ووقت تشغيله.
• أدرِج عنوان URL الخاص بمكتبة الرسوم البيانية التي يجب استخدامها في عبارة تضمين <script> الخاصة بالعميل، مع توفير عنوان URL لمستنداتك.
• أدخِل الاسم المؤهّل بالكامل للرسم البياني.
• أنشِئ نماذج صفحات توضّح كيفية استخدام الرسم البياني بالخيارات المتاحة فيه والأحداث والطرق المخصّصة.
• صِف بوضوح سياسة البيانات للمخطط. تعالج معظم الرسومات البيانية البيانات داخل المتصفّح، ولكن قد ترسل بعض الرسومات البيانية بيانات إلى خادم، لإنشاء صورة لرسم بياني أو خريطة مثلاً. في حال إرسال البيانات إلى خادم:
  • حدد البيانات التي يتم إرسالها بوضوح.
  • لاحظ المدة التي سيتم خلالها حفظ البيانات على الخادم.
  • قم بتوثيق الكيانات التي سيكون لها حق الوصول إلى البيانات. على سبيل المثال، الشركة XYZ، إلخ.
  • حدِّد ما إذا كان سيتم تسجيل البيانات ومدة تسجيلها.

ستتم استضافة مستنداتك في المكان نفسه الذي يوجد فيه رمز الرسم البياني (راجع إرسال الرسم البياني إلى المعرض أدناه).

إرسال الرسم البياني إلى المعرض

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

تحديد المشاكل وحلّها

إذا كانت التعليمات البرمجية لا تعمل، فإليك بعض الأساليب التي قد تساعدك في حل مشكلاتك:

• ابحث عن الأخطاء الإملائية. تذكر أن JavaScript لغة حساسة لحالة الأحرف.
• استخدام برنامج تصحيح أخطاء JavaScript في Firefox، يمكنك استخدام وحدة تحكّم JavaScript أو Venkman Debugger أو إضافة Firebug. في IE، يمكنك استخدام أداة تصحيح الأخطاء في Microsoft Script Debugger.
• ابحث في مجموعة مناقشة Google Chart API. إذا لم تتمكّن من العثور على مشاركة تجيب عن سؤالك، انشر سؤالك على المجموعة مع رابط يؤدي إلى صفحة ويب تشرح المشكلة.

الأقلمة

إذا كنت تتوقع أن يستخدِم المستخدمون الرسم البياني الخاص بك في بلدان مختلفة، ننصحك بتصميمه ليتناسب مع لغات وثقافات مختلفة. فالأقلمة الأساسية هي ترجمة السلاسل النصية العادية في واجهة المستخدم وفقًا لإعدادات المتصفّح لدى المستخدم. من الطرق الأكثر تقدّمًا للترجمة تغيير تنسيقات الأرقام استنادًا إلى الأقلمة، أو حتى تصميم واجهة المستخدم. إذا قررت ترجمة الرسم البياني، عليك إدراج اللغات التي يتيحها الرسم البياني في مستنداتك، وتحديد الإعدادات التلقائية للّغة الشائعة الاستخدام. من المفيد أيضًا تضمين زر "تغيير اللغة" في واجهة المستخدم الخاصة بالرسم البياني في حال حدوث خطأ في اللغة. والطريقة الشائعة لاكتشاف لغة المتصفّح هي الاطّلاع على عنوان HTML accept-Language.