إنشاء أنواع الرسومات البيانية

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

الجمهور

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

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

ويتم عرض المخططات للمستخدم من خلال مكتبة جافا سكريبت من إنشائك. في ما يلي خطوات إنشاء مكتبة المخططات:

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

نصيحة

• يمكنك تنزيل تعريفات فئات وطريقة goog.visualization لواجهة برمجة التطبيقات لتفعيل الإكمال التلقائي في IDE (محرر الرموز). نزّل الملف من http://www.google.com/uds/modules/gviz/gviz-api.js واحفظه في مشروعك. وستعمل معظم برامج IDE على فهرسته تلقائيًا وتفعيل الإكمال التلقائي، على الرغم من أن IDE قد يكون مختلفًا. يُرجى العِلم بأنّه قد لا يكون الملف محدّثًا دائمًا، لذا اطّلِع على الصفحات المرجعية للحصول على أحدث مرجع لواجهة برمجة التطبيقات.

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

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

في ما يلي مثال على إنشاء كائن مساحة اسم لتضمين فئة رسم بياني باسم "جدولي"، بالإضافة إلى أي متغيرات عامة مطلوبة:

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

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

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

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

الأقلمة

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