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

يشرح هذا المستند كيفية إرسال بيانات المخطط إلى Google Chart API.

جدول المحتويات

  1. نظرة عامّة
  2. تنسيق النص الأساسي
  3. تنسيق النص من خلال تحجيم تلقائي
  4. تنسيق النص مع تغيير الحجم المخصّص
  5. تنسيق ترميز بسيط
  6. تنسيق الترميز الموسّع
  7. قياس البيانات وقياس المحور
  8. النص البرمجي لترميز JavaScript

نظرة عامة

يتم إرسال بيانات جميع الرسوم البيانية تقريبًا باستخدام المَعلمة chd. ويجب إرسال البيانات بأحد التنسيقات التالية:

  • تنسيق النص الأساسي هو في الأساس أرقام نقاط عائمة بسيطة تتراوح بين 0 و100، بشكل شامل. إنّ هذا التنسيق سهل القراءة والكتابة يدويًا.
  • يعمل تنسيق النص مع تغيير الحجم التلقائي على تحجيم الرسم البياني ليلائم بياناتك.
  • يشبه تنسيق النص مع تحجيم مخصّص تنسيق النص الأساسي، ولكنّه يتيح لك تحديد نطاق مخصّص باستخدام مَعلمة عنوان URL ثانية.
  • يتيح لك تنسيق الترميز البسيط تحديد قيم عدد صحيح تتراوح من 0 إلى 61، بما في ذلك القيم الواقعة بينهما، والتي يتم ترميزها بحرف أبجدي رقمي واحد. ينتج عن هذا الترميز أقصر سلسلة بيانات بين أي تنسيق من تنسيقات البيانات (إذا كانت أي قيم أكبر من 9).
  • يتيح لك تنسيق الترميز الموسَّع تحديد قيم عدد صحيح تتراوح بين 0 و4095، بما في ذلك القيم الواقعة بينهما، والتي يتم ترميزها بحرفَين أبجديَين رقميَّين. يناسب الترميز الموسَّع الرسم البياني الذي يحتوي على الكثير من البيانات ونطاق بيانات كبير.

يتم تعديل قيم البيانات لتلائم التنسيق المستخدَم. راجِع قياس البيانات وقياس المحور للحصول على شرح حول طريقة معالجة البيانات كي تتوافق مع الرسم البياني.

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

تنسيق النص الأساسي

تتيح لك البيانات الأساسية بتنسيق النص تحديد قيم النقاط العائمة على شكل أرقام تتراوح بين 0 و100. يتم وضع علامة على القيم التي تقل عن صفر على أنّها غير متوفّرة، ويتم اقتطاع القيم التي تزيد عن 100 لتصبح 100. وتتمثل ميزة التنسيق الأساسي للنص في أنّ القيم سهلة القراءة والفهم في عنوان URL، وتوضّح تصنيفات المحاور التلقائية قيم البيانات بدقة. ومع ذلك، ينتج عن تنسيق النص (سواء كان بسيطًا أو يتضمّن معلَمات مخصّصة) أطول سلسلة بيانات من جميع التنسيقات.

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

البنية:

chd=t:val,val,val|val,val,val...
<data>
تتكون كل سلسلة من قيمة واحدة أو أكثر مفصولة بفواصل. افصل بين السلاسل المتعددة باستخدام حرف الشرطة المستقيمة (|). والقيم هي أرقام النقاط العائمة من 0 إلى 100، بشكل شامل. ويتم اعتبار القيم الأقل من الصفر أو حرف الشرطة السفلية ( _ ) قيمًا فارغة. يتم اقتطاع القيم التي تزيد عن 100 لتصبح 100.

 

مثال:

جدول مكون من خمس قيم. وتُعتبر الشرطة السفلية قيمة فارغة، وتقع القيمة -30 تحت الحد الأدنى للقيمة، لذلك يتم إسقاطها، ويتم اقتطاع القيمة 200 لتصبح 100. رسم بياني شريطي يتضمن 5 قيم وترميز نص.
chd=t:_,30,-30,50,80,200

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

تنسيق النص من خلال تحجيم تلقائي

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

ستعرض أي قيم علامة معروضة على الرسم البياني قيمها الفعلية، وليس قيمها التي تم قياسها.

لا تعمل هذه الميزة إلا مع القيم بتنسيق نصي ولا تعمل مع جميع أنواع الرسوم البيانية. جرّب نوع الرسم البياني لمعرفة ما إذا كان متوافقًا.

البنية

cht=t:val,val,val...
chds=a

أمثلة:


chd=t:5,30,50,80,200
chds=a

لاحظ أنه يجب ألا تستخدم قيمًا < 0 للمخططات الدائرية.

 رسم بياني شريطي يتضمن 5 قيم وترميز نص.
chd=t:-5,30,-30,50,80,200
chds=a

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

تنسيق النص مع تغيير الحجم المخصّص

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

بالنسبة إلى التحجيم التلقائي، حدِّد chds=a.

وينتج عن تنسيق النص (سواء كان بسيطًا أو يتضمّن مَعلمات مخصّصة) أطول سلسلة بيانات من جميع التنسيقات.

البنية:

يتطلب تنسيق النص مع تحجيم مخصّص مَعلمتَين:

chd=t:val,val,val|val,val,val
chds=<series_1_min>,<series_1_max>,...,<series_n_min>,<series_n_max>
chd=t:<data>
هذا التنسيق هو نفسه تنسيق البيانات العادي: قيمة واحدة أو أكثر مفصولة بفواصل لكل سلسلة وسلاسل متعددة مفصولة برمز شَرطة رأسية (|). يتم تحديد نطاق القيم المسموح بها في كل سلسلة من خلال المَعلمة chds.
أمر chds
مجموعة من قيم الحد الأدنى والأقصى المسموح بها لكل سلسلة بيانات، مع الفصل بينها بفواصل. يجب توفير حد أقصى وحد أدنى. وفي حال توفير أزواج أقل من العدد الموجود في سلاسل البيانات، يتم تطبيق زوج آخر من البيانات على جميع سلاسل البيانات المتبقية. يُرجى العِلم أنّ هذا الإجراء لا يؤدي إلى تغيير نطاق المحور. ولتغيير نطاق المحور، عليك ضبط المَعلمة chxr. تتراوح القيم الصالحة من (+/-)9.999e(+/-)199. يمكنك تحديد قيم إما بالترميز العادي أو E.
<series_1_min>
الحد الأدنى للقيمة المسموح بها في السلسلة الأولى. ويتم وضع علامة على القيم الدنيا على أنّها غير متوفّرة.
<series_1_max>
الحد الأقصى للقيمة المسموح بها في السلسلة الأولى ويتم اقتطاع القيم الأعلى إلى هذه القيمة.

 

مثال:

مخطط شريطي بمقياس أدنى/أقصى من -80—140. تندرج القيم 30 و-60 و50 و140 و80 ضمن المقياس، لذا لا يتم اقتطاعها. ونشير إلى أنّه يتم تعديل الخط الصفري بالنسبة إليك، حيث يساوي 80/(140 + 80) = 0.36 من بداية المحور ص.

يُرجى العلم أيضًا أنّ نطاق المحور ص التلقائي لا يزال يتراوح من 0 إلى 100، على الرغم من المَعلمة chds، لذلك لا تعكس قيم التصنيف قيم البيانات الفعلية.

 رسم بياني شريطي يتضمن 5 قيم، وترميز نص مع تغيير حجم البيانات.

chd=t:30,-60,50,140,80,-90
chds=-80,140

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

تنسيق ترميز بسيط

يتيح لك تنسيق الترميز البسيط تحديد قيم عدد صحيح تتراوح بين 0 و61، بما في ذلك، مع التشفير بحرف أبجدي رقمي واحد. وينتج عن ذلك أقصر عنوان URL لسلسلة بيانات بين جميع تنسيقات البيانات. وإذا كان لديك رسم بياني خطي أو شريطي أطول من 100 بكسل على طول محور البيانات، ننصحك باستخدام تنسيق آخر. ويرجع ذلك إلى أنّه في حال توفُّر 62 قيمة بيانات فقط، تكون دقة البيانات أكبر بكثير من دقة العرض، ولن تظهر القيم إلا قليلاً (ليست كثيرًا، ولكن مرئية في الرسوم البيانية الأكبر).

يُرجى العِلم أنّك إذا كنت تستخدم المعلَمة chds بترميز بسيط، لن يتأثر حجم عنصر البيانات على الرسم البياني، ولكن ستتأثر أي قيم لعلامة نقطة البيانات.

البنية:

chd=s:
  <series_1>
    ,...,
  <series_n>
<series_1>
سلسلة، حيث يكون كل حرف نقطة بيانات واحدة، ويتم الفصل بين السلسلة بفاصلة. ولا يتم الفصل بين القيم الفردية ضمن سلسلة معيّنة. وفي ما يلي أحرف البيانات المتوافقة والقيم المقابلة لها:
  • A—Z، حيث A = 0، B = 1، وهكذا، Z = 25
  • a—z، حيث a = 26، b = 27، وهكذا، z = 51
  • 0(zero)—9، حيث 0 = 52 و9 = 61
  • يشير حرف الشرطة السفلية (_) إلى قيمة ناقصة.

يمكنك استخدام الأداة التالية لترميز قيمة واحدة، أو رمز JavaScript لتغيير حجم سلسلة عنوان URL بالكامل وترميزها.

مثال:

تعادل السلسلة chd=t:1,19,27,53,61,-1|12,39,57,45,51,27 المرمّزة بالنص. <title="chs=320x200&cht=bvs&chd=s:btb19_,mn5tzb&chco=ffcc33,ffe9a4&chxr=0,0,61,5&chxt=y" alt="مخطط شريطي مكدس مع سلسلتين وستة قيم لكل منهما، ترميز بسيط." src="/static.png/static.
chd=s:BTb19_,Mn5tzb

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

تنسيق الترميز الموسّع

يتيح لك تنسيق الترميز الموسَّع تحديد قيم عدد صحيح تتراوح بين 0 و4095، بما في ذلك القيم الواقعة بينهما، والتي يتم ترميزها باستخدام حرفَين أبجديَين رقميَّين. وتستخدم بنية مختلفة قليلاً عن الترميز البسيط.

يُرجى العِلم أنّك إذا كنت تستخدم المَعلمة chds بترميز بسيط، لن يتأثر حجم عنصر البيانات على الرسم البياني، ولكن ستتأثر أي قيم لعلامة نقطة بيانات.

البنية:

chd=e:
  <series_1>
    ,...,
  <series_n>
<series_1>
سلسلة يكون فيها كل حرفين نقطة بيانات واحدة، ويتم الفصل بين السلسلة بفاصلة. ولا يتم الفصل بين القيم الفردية في سلسلة معيّنة. وفي ما يلي أحرف الترميز المتوافقة:
  • A—Z
  • a—z
  • 0—9
  • الفترة (.)
  • واصلة (-)
  • وتتم الإشارة إلى القيم المفقودة باستخدام شرطة سفلية مزدوجة (__).

في ما يلي وصف مختصر للقيم المشفرة:

  • AA = 0، وAB = 1، وهكذا حتى AZ = 25
  • Aa = 26، وAb = 27، وهكذا Az = 51
  • A0 = 52، وA1 = 53، وهكذا A9 = 61
  • A- = 62، A. = 63
  • BA = 64، وBB = 65، وهكذا BZ = 89
  • Ba = 90، وBb = 91، وهكذا حتى Bz = 115
  • B0 = 116، B1 = 117، وهكذا B9 = 125
  • B- = 126، B. = 127
  • 9A = 3904، و9B = 3905، وهكذا حتى 9Z = 3929
  • 9a = 3930، و9b = 3931، وهكذا حتى 9z = 3955
  • 90 = 3956، 91 = 3957، وهكذا حتى 99 = 3965
  • 9- = 3966، 9. = 3967
  • -A = 3968، و-B = 3969، وهكذا -Z = 3993
  • -a = 3994، و-b = 3995، وهكذا حتى -z = 4019
  • -0 = 4020 و-1 = 4021، وهكذا حتى -9 = 4029
  • -- = 4030، -. = 4031
  • .A = 4032، و.B = 4033، وهكذا حتى .Z = 4057
  • .a = 4058، و.b = 4059، وهكذا حتى .z = 4083
  • .0 = 4084 و.1 = 4085، وهكذا حتى .9 = 4093
  • .- = 4094، .. = 4095

يمكنك استخدام الأداة التالية لترميز قيمة واحدة، أو رمز JavaScript لتغيير حجم سلسلة عنوان URL بالكامل وترميزها.

مثال:

تعادل السلسلة chd=t:90,1000,2700,3500|3968,-1,1100,250 المرمّزة بالنص. رسم بياني شريطي مكدَّس يتضمن سلسلتين من أربع قيم لكل منهما، ترميز موسع.
chd=e:BaPoqM2s,-A__RMD6

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

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

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

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

يُرجى العلم أنّه يتم احتساب قيم تصنيف المحور على مقياس مستقل تمامًا ولا علاقة لها بقيم البيانات، ولكن يجب استخدام النطاق التلقائي من 0 إلى 100. ومع ذلك، يمكنك تغيير هذا النطاق.

يصف هذا القسم كلتا المشكلتَين.

يتم تعديل حجم البيانات لتناسب نطاق التنسيق [كل الرسوم البيانية باستثناء Pie وVenn].

تتوافق التنسيقات المختلفة مع نطاقات قيم مختلفة. يتم تغيير حجم البيانات وفقًا لنطاق التنسيق الخاص بك، بحيث يتم عرض أقصى قيمة يدعمها التنسيق في أعلى ذلك المحور، ويتم عرض الحد الأدنى لقيمة التنسيق في الجزء السفلي. تعرض الأمثلة التالية القيمة نفسها (100) باستخدام تنسيق النص الأساسي (النطاق من 0 إلى 100)، ونص بحجم مخصّص (نطاق مخصّص من 0 إلى 200)، وتنسيق الترميز الممتد (النطاق من 0 إلى 4095).

تنسيق النص الأساسي تنسيق النص مع تحجيم مخصص تنسيق الترميز الموسّع
رسم بياني شريطي يتضمن نص أساسي مع تحجيم مخصص

القيمة: 100 (chd=t:100)

نطاق التنسيق: من 0 إلى 100

يتم عرض 100 كـ 100/100 أعلى المقياس.

القيمة 100 (chd=t:100, chds=0,200)

نطاق التنسيق: من 0 إلى 200

يتم عرض 100 100/200 أعلى المقياس.

القيمة: 100 (chd=e:Bk)

نطاق التنسيق: من 0 إلى 4095

يتم عرض 100 على هذا النحو 100/4095 أعلى المقياس.

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

الرسوم البيانية الدائرية والمخططات المتجانبة: في حال استخدام الرسمَين البيانيَين الدائريَين وVenn، تكون جميع القيم نسبية إلى بعضها بعضًا، وليس بمقياس إجمالي الرسم البياني.

chd=e:BkDIEs chd=t:100,200,300
chds=0,300

يتم احتساب نطاق تصنيف المحور بشكل مستقل [شريطي وخطي ورادار ومبعثر ومخطط شمعدان]

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

نطاق المحور التلقائي هو 0—100، بغض النظر عن قيم البيانات أو حجم البيانات. على سبيل المثال، إذا عرضت المحور ص باستخدام تصنيفات المحاور التلقائية على رسم بياني يستخدم الترميز الممتد (النطاق 0 و4095)، ستظل تصنيفات المحور ص تقرأ ما بين 0 و100 ما لم تغيّر ذلك صراحةً، كما هو موضّح أدناه. في ما يلي مثال يعرض تصنيفات المحور y التلقائية في رسم بياني شريطي ممتد للترميز مع قيمة بيانات 100:


chd=e:Bk (ما يعادل chd=t:100)

ومع ذلك، يمكنك تحديد نطاق المحور باستخدام المَعلمة chxr. إذا كنت تريد أن تعكس قيم المحور قيم البيانات الفعلية، عليك تحديد الحد الأدنى والأقصى لقيم المحور التي تتطابق مع نطاق التنسيق. يُرجى العلم بأنّ تنسيق النص الأساسي له مقياس من 0 إلى 100، لذلك إذا كنت تستخدم تنسيق النص الأساسي (بدون ضبط مخصّص)، ستطابق قيم المحور قيم البيانات تلقائيًا. لِنوضِّح ذلك من خلال بعض الأمثلة. إليك ثلاثة رسوم بيانية تتضمن البيانات نفسها (15 و26 و51,61)، ولكن بتنسيقات مختلفة ومقاييس محاور مختلفة:

ترميز بسيط، بدون تحجيم المحور ترميز بسيط، المحور الموسّع نص أساسي، بدون تحجيم المحور

chd=s:Paz9
 

نطاق قيمة الترميز البسيط: من 0 إلى 61

نطاق المحور التلقائي (0—100)

نطاق الترميز أصغر من نطاق محور التصنيف، لذا لا تتوافق الأشرطة مع القيمة الفعلية في تصنيف المحور. ومع ذلك، تكون الأشرطة متناسبة مع بعضها البعض بشكل صحيح.

chd=s:Paz9
    chxr=0,0,61,10

نطاق قيمة الترميز البسيط: من 0 إلى 61

تم ضبط نطاق المحور صراحةً على القيمة 0—61

نطاق الترميز ونطاق المحور متساويان، بحيث تتوافق الأشرطة مع قيمتها الصحيحة على المحور.

chd=t:15,26,51,61
 

نطاق قيمة تنسيق النص الأساسي: 0—100

نطاق المحور التلقائي (0—100)

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

وبما أنّ نطاق تنسيق النص أكبر من نطاق تنسيق الترميز البسيط (100 وحدة في مقابل 61 وحدة)، تكون الأشرطة أصغر هنا منها في الرسوم البيانية الأخرى، ولكن تبقى كلّ الرسوم البيانية متناسبة مع بعضها البعض.

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

النص البرمجي لترميز JavaScript

عند الاستخدام الفعلي، قد يكون من الأسهل ترميز البيانات آليًا بدلاً من ترميزها يدويًا.

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

var simpleEncoding =
  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';

// This function scales the submitted values so that
// maxVal becomes the highest value.
function simpleEncode(valueArray,maxValue) {
  var chartData = ['s:'];
  for (var i = 0; i < valueArray.length; i++) {
    var currentValue = valueArray[i];
    if (!isNaN(currentValue) && currentValue >= 0) {
    chartData.push(simpleEncoding.charAt(Math.round((simpleEncoding.length-1) *
      currentValue / maxValue)));
    }
      else {
      chartData.push('_');
      }
  }
  return chartData.join('');
}

// Same as simple encoding, but for extended encoding.
var EXTENDED_MAP=
  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-.';
var EXTENDED_MAP_LENGTH = EXTENDED_MAP.length;
function extendedEncode(arrVals, maxVal) {
  var chartData = 'e:';

  for(i = 0, len = arrVals.length; i < len; i++) {
    // In case the array vals were translated to strings.
    var numericVal = new Number(arrVals[i]);
    // Scale the value to maxVal.
    var scaledVal = Math.floor(EXTENDED_MAP_LENGTH *
        EXTENDED_MAP_LENGTH * numericVal / maxVal);

    if(scaledVal > (EXTENDED_MAP_LENGTH * EXTENDED_MAP_LENGTH) - 1) {
      chartData += "..";
    } else if (scaledVal < 0) {
      chartData += '__';
    } else {
      // Calculate first and second digits and add them to the output.
      var quotient = Math.floor(scaledVal / EXTENDED_MAP_LENGTH);
      var remainder = scaledVal - EXTENDED_MAP_LENGTH * quotient;
      chartData += EXTENDED_MAP.charAt(quotient) + EXTENDED_MAP.charAt(remainder);
    }
  }

  return chartData;
}

لترميز البيانات، يجب استدعاء الدالة simpleEncode أو extendedEncode، مع تمرير الصفيف الذي يحتوي على بياناتك (valueArray) والحدّ الأقصى لقيمة بياناتك (maxValue). لإنشاء مسافة بين أعلى قيمة وأعلى الرسم البياني، اضبط maxValue ليكون أكبر من أكبر رقم في مصفوفة البيانات، على النحو التالي:

var valueArray = new Array(0,1,4,4,6,11,14,17,23,28,33,36,43,59,65);
var maxValue = 70;
simpleEncode(valueArray, maxValue);

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