بدء استخدام المخططات

تصف هذه الصفحة أساسيات استخدام Chart API لإنشاء المخططات.

سياسة استخدام الرسوم البيانية من Google

ما من حدّ أقصى لعدد المكالمات اليومية التي يمكنك إجراؤها باستخدام Google Chart API. ومع ذلك، نحتفظ بالحق في حظر أي استخدام نعتبره إساءة استخدام.

نظرة عامة

عرض الرسوم البيانية في هذا الوثائق

يتم إنشاء جميع صور الرسوم البيانية في هذه المستندات مباشرةً باستخدام Chart API. لعرض عنوان URL لأي صورة، اتّبِع الخطوات التالية:

  • إذا كنت تستخدم Firefox، فانقر بزر الماوس الأيمن ثم حدد "View Image" (عرض الصورة) أو Properties (خصائص).
  • إذا كنت تستخدم برنامج Internet Explorer، انقر بزر الماوس الأيمن ثم حدد "خصائص".

لتسهيل قراءة عنوان URL، غالبًا ما يعرضه هذا المستند في عدة أسطر. عند استخدام Google Chart API، يجب تقديم عنوان URL في سطر واحد.

تعرض Google Chart API صورة رسم بياني استجابةً لطلب GET أو POST لعنوان URL. يمكن لواجهة برمجة التطبيقات إنشاء أنواع عديدة من الرسوم البيانية، بدءًا من المخططات الدائرية أو الخطية ووصولاً إلى رموز الاستجابة السريعة والصيغ. تُعدّ جميع المعلومات التي تريدها بشأن الرسم البياني جزءًا من عنوان URL، بما في ذلك بيانات الرسم البياني وحجمه وألوانه وتصنيفاته. (تختلف طريقة إرسال طلبات POST قليلاً، ولكن لا داعي للقلق بهذا الشأن الآن).

لإنشاء أبسط رسم بياني ممكن، يجب أن يحدّد عنوان URL نوع الرسم البياني والبيانات وحجمه. يمكنك كتابة عنوان URL هذا مباشرةً في المتصفّح الذي تستخدمه، أو الإشارة إليه باستخدام علامة <img> في صفحتك على الويب. على سبيل المثال، اتبع هذا الرابط للحصول على مخطط دائري:

https://chart.googleapis.com/chart?chs=250x100&chd=t:60,40&cht=p3&chl=Hello|World

 

الرابط السابق هو مثال على عنوان URL أساسي لواجهة برمجة تطبيقات المخطط. تحتوي جميع عناوين URL في الرسم البياني على التنسيق التالي:

https://chart.googleapis.com/chart?cht=<chart_type>&chd=<chart_data>&chs=<chart_size>&...additional_parameters...

تبدأ جميع عناوين URL بـ https://chart.googleapis.com/chart?، متبوعة بالمعلَمات التي تحدّد بيانات الرسم البياني ومظهره. المَعلمات هي أزواج name=value، مفصولة برمز العطف اللاتيني (&)، ويمكن أن تكون المَعلمات بأي ترتيب، بعد ?. تتطلّب جميع الرسوم البيانية على الأقل المَعلمات التالية: cht (نوع الرسم البياني) وchd (البيانات) وchs (حجم الرسم البياني). ومع ذلك، هناك العديد من المعلَمات الأخرى للخيارات الإضافية، ويمكنك تحديد أكبر عدد ممكن من المعلَمات الإضافية التي يتيحها الرسم البياني.

لنفحص عنوان URL أعلاه بمزيد من التفاصيل:

عنوان URL المكوّنات

رسم بياني دائري أصفر

https://chart.googleapis.com/chart?
  cht=p3&
  chs=250x100&
  chd=t:60,40&
  chl=Hello|World
https://chart.googleapis.com/chart?
هذا هو عنوان URL الأساسي لجميع طلبات الرسم البياني.
cht=p3
نوع الرسم البياني: هنا رسم بياني دائري ثلاثي الأبعاد
chs=250x100
حجم الرسم البياني (العرض x الارتفاع) بالبكسل اطّلِع على الحد الأقصى للقيم هنا.
chd=t:60,40
بيانات الرسم البياني تكون هذه البيانات بتنسيق نصي بسيط، ولكن تتوفّر تنسيقات أخرى.
chl=Hello|World
تصنيفات الشرائح.
&
يتم فصل المَعلمات برمز العطف اللاتيني. ملاحظة: عند تضمين عنوان URL في ترميز HTML، مثل السمة src للعلامة <img>، يجب استبدال & بين المعلمات بالأحرف &amp;. ويشمل ذلك الحالات التي تنشئ فيها ترميز HTML للصفحة باستخدام لغة PHP أو بلغة أخرى. ومع ذلك، عند كتابة عنوان URL في المتصفّح أو عند طلب عنوان URL في الرمز، مثلاً عند جلب عنوان URL بلغة PHP أو Perl، عليك استخدام العلامة &.

انسخ عنوان URL هذا والصقه في المتصفّح وجرِّب إجراء بعض التغييرات: أضِف قيمًا إضافية إلى البيانات (ولا تنسَ إضافة فاصلة قبل كل قيمة بيانات جديدة). أضِف تصنيفات جديدة (ضَع علامة | قبل كل قيمة جديدة). تكبير المخطط.

الرجوع إلى الأعلى

كيفية إنشاء رسم بياني

إليك كيفية إنشاء مخطط صورة:

  1. حدِّد نوع الرسم البياني. راجِع المعرض للحصول على قائمة بالرسومات البيانية، ويتم تحديد نوع الرسم البياني من خلال المعلّمة cht. ارسم جميع المكوّنات التي تريد أن يحتوي عليها الرسم البياني (المحاور والتسميات والخلفيات وما إلى ذلك)، وإذا لزم الأمر، حدّد أبعاد البكسل للمكوّنات المختلفة (إجمالي حجم الرسم البياني وحجم وسيلة الإيضاح وما إلى ذلك). عليك قراءة المستندات بعناية لتحديد نوع الرسم البياني أولاً، وإلا قد تكون تجربة استخدام موقعك الإلكتروني محبطة.
  2. إنشاء بيانات الرسم البياني وتنسيقها: يتم تحديد البيانات باستخدام مَعلمة chd. وعليك تحديد التنسيق الذي تريد استخدامه لبياناتك:
    • اختَر تنسيق بيانات. يمكنك استخدام تنسيق نص بسيط لبيانات الرسم البياني، وهو أمر سهل القراءة ولكنه يستغرق مساحة أكبر للإرسال، أو يمكنك استخدام أحد أنواع الترميز التي يكون إرسالها أصغر حجمًا لكنّها تحدّ من نطاق القيم التي يمكنك إرسالها.
    • حدِّد ما إذا كان يجب تغيير حجم بياناتك لتلائم الرسم البياني. تتوافق التنسيقات المختلفة مع نطاقات مختلفة من القيم. ننصحك بتوسيع نطاق بياناتك بحيث تغطي النطاق الكامل للقيم التي يسمح بها التنسيق، وذلك لجعل الاختلافات أكثر وضوحًا. يمكنك إجراء ذلك من خلال تغيير حجم بياناتك لتتلاءم مع تنسيق البيانات الذي تستخدمه، أو يمكنك استخدام تنسيق النص مع تحجيم مخصّص.
    • ترميز البيانات إذا لزم الأمر. وإذا اخترت تنسيقًا مرمّزًا، نقدّم بعض JavaScript لمساعدتك في أنواع الترميز الأخرى.
  3. حدِّد حجم الرسم البياني. يتم تحديد حجم الرسم البياني باستخدام المَعلمة chs. ويمكنك الاطّلاع على المستندات للتعرّف على التنسيق والحد الأقصى للقيم.
  4. أضِف معلَمات إضافية. تسرد مستندات كل رسم بياني المَعلمات الاختيارية المتاحة. تشمل الخيارات المعتادة التصنيفات والعناوين والألوان. تجدر الإشارة إلى أنّه يجب ترميز كل نص التصنيف أو العنوان بالترميز UTF-8. يُرجى العِلم أنّ العديد من المعلَمات تسمح لك بإدخال قيم متعدّدة. على سبيل المثال، تتيح لك المَعلمة chm وضع شكل في نقطة بيانات واحدة على رسم بياني. يمكنك وضع أشكال على نقاط بيانات متعددة باستخدام المعلَمة chm، ولكن لإجراء ذلك، لا تحدّد المعلَمة chm عدة مرات في عنوان URL (على سبيل المثال، WRONG: chm=square&chm=circle&chm=triangle). بدلاً من ذلك، تستخدم المعلمات التي تستخدم قيمًا متعددة محدِّدًا، مثل فاصلة أو شريط عمودي، بين قيم متعددة في المعلمة نفسها. وبالنسبة إلى chm، يكون شريطًا، لذا ستكون النتيجة على النحو التالي: RIGHT: chm=square|circle|triangle. اطّلع على تفاصيل كل مَعلمة لمعرفة كيفية تحديد مَعلمات متعدّدة.
  5. أنشئ سلسلة عنوان URL. يبدأ عنوان URL بـ https://chart.googleapis.com/chart? ويليه جميع المَعلمات المطلوبة (cht وchd وchs) والمَعلمات الاختيارية. ملاحظة: إذا كنت تستخدم عنوان URL الخاص بك في علامة <img>، ستحتاج إلى تغيير كل أحرف & إلى &amp; في الرابط. مثال: <img src="https://chart.googleapis.com/chart?chs=250x100&amp;chd=t:60,40&amp;cht=p3&amp;chl=Hello|World" />.
  6. استخدِم طريقة GET أو POST للحصول على الصورة. وتكون طريقة GET هي إمّا عند كتابة عنوان URL مباشرةً في المتصفّح أو في استخدامه في علامة <img>. لا يمكن أن يزيد طول عناوين URL عن 2,000، لذا إذا كانت لديك بيانات أكثر من ذلك أو كنت تريد تحليل الدم، ننصحك باستخدام طريقة POST بدلاً من ذلك، كما هو موضّح هنا.
  7. أنشِئ مناطق قابلة للنقر. يمكنك اختياريًا إنشاء خريطة صور للرسم البياني تتيح لك إضافة روابط تشعّبية أو النقر على عناصر إلى عناصر محدّدة في الرسم البياني. راجع إنشاء خريطة صور رسم بياني للحصول على التفاصيل.

الرجوع إلى الأعلى

مسرد مصطلحات الرسوم البيانية

في ما يلي بعض المصطلحات المهمة التي نستخدمها في هذه المستندات:

سلسلة
مجموعة بيانات ذات صلة في رسم بياني. يعتمد ما يُشكّل سلسلة على نوع الرسم البياني: في الرسم البياني الخطي، تكون السلسلة سطرًا واحدًا، وفي الرسم البياني الدائري، يكون كل إدخال عبارة عن شريحة، وجميع الشرائح معًا عبارة عن سلسلة. في الرسم البياني الشريطي، تتضمّن السلسلة جميع الأشرطة من مجموعة البيانات نفسها، وإما أن يتم تجميع السلاسل المختلفة جنبًا إلى جنب أو مكدسة فوق بعضها البعض، استنادًا إلى نوع الرسم البياني الشريطي. يوضِّح الرسم البياني التالي رسمًا بيانيًا شريطيًا مجمّعًا من سلسلتَين، إحداهما باللون الأزرق الداكن والأخرى باللون الأزرق الفاتح:
رسم بياني شريطي يعرض سلسلتين: القطط والكلاب
تصنيفات المحاور
القيم الرقمية أو النصية على طول كل محور في الرسم البياني السابق، كانت التصنيفات "يناير" و"فبراير" و"مارس" و"0" و"50" و"100".

مكونات الرسم البياني

وفي ما يلي بعض مكونات الرسم البياني:

مناطق مختلفة في الرسم البياني
منطقة الرسم البياني
المنطقة التي تعرض صورة المسلسل يُرجى الاطّلاع على الشريط الجانبي "مكوّنات الرسم البياني" لمعرفة مزيد من التفاصيل.
الشرح
منطقة صغيرة على الرسم البياني تصف السلسلة. في الرسم البياني أعلاه، يعرض القسم "القطط" و "الكلاب".
المعلَمة
زوج مفتاح=قيمة مستخدَم في عنوان URL. على سبيل المثال: chxt=x، حيث يكون chxt هو اسم المَعلمة وx هو قيمة المَعلمة.
GET وPOST
هناك طريقتان لإرسال عنوان URL للرسم البياني. ويتم إجراء GET عادةً من خلال كتابة عنوان URL في المتصفح أو من خلال جعله مصدر علامة <img>. إنّ طلبات POST أكثر تعقيدًا، ولكنها يمكن أن تتضمّن المزيد من البيانات. السبب الرئيسي لاستخدام POST بدلاً من GET هو أنّ طلب POST يمكن أن يأخذ بيانات أكثر بكثير من طلب GET (16 ألف حرف مقابل 2 ألف حرف). ويمكنك الاطّلاع على مقالة POST هنا.
شخصية Pip
الحرف |، الذي غالبًا ما يُستخدم باعتباره مُحدِّد لقيمة المَعلمة، أي حرف لتقسيم قيم متعدّدة. يتم أيضًا استخدام الفواصل وعلامات العطف (&) كمحددات في عنوان URL للرسم البياني.
الرسوم البيانية المركّبة
رسم بياني يتألف من نوعَين مختلفَين من الرسومات البيانية: على سبيل المثال، رسم بياني شريطي بخط خط، أو رسم بياني خطي يتضمّن علامات شمعدان راجع الرسوم البيانية المركّبة.

الرجوع إلى الأعلى

التحسينات

الآن بعد أن تعرفت على أساسيات إنشاء رسم بياني، إليك بعض التحسينات التي يمكنك استخدامها.

استخدام POST

يقتصر طول عناوين URL على 2 كيلوبايت، لذلك إذا كان الرسم البياني يحتوي على بيانات أكثر من ذلك، ستحتاج إلى استخدام POST بدلاً من GET، كما هو موضّح هنا. يتم استخدام GET عند كتابة عنوان URL للرسم البياني في شريط عناوين URL للمتصفّح، أو استخدامه كمصدر لعنصر <img> في صفحة ويب. تتطلّب طريقة POST برمجة إضافية بلغة أخرى، مثل PHP أو PERL.

إنشاء المخططات في JavaScript

يمكنك استخدام Google Visualization API لإنشاء رسوم بيانية لك. Google Visualization API هي واجهة برمجة تطبيقات تستند إلى JavaScript وتمنحك أدوات لإنشاء البيانات وتصفيتها ومعالجتها، أو طلب بيانات من جداول بيانات Google أو مواقع أخرى للحصول على بيانات. يمكنك استخدام واجهة برمجة التطبيقات للتمثيل البصري لإنشاء البيانات، ثم طلب البيانات من واجهة برمجة التطبيقات لمخططات الصور لعرض الرسم البياني على الصفحة. لمزيد من المعلومات، راجِع مستندات الرسم البياني للصور العامة أو راجِع معرض العروض المرئية للاطّلاع على أي رسومات بيانية من Google تم وضع علامة عليها (صورة).