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

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

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

نظرة عامة

يتم إرسال البيانات لجميع الرسوم البيانية تقريبًا باستخدام المعلمة 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.

chd=t:_,30,-30,50,80,200

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

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

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

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

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

البنية

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

أمثلة:

chd=t:5,30,50,80,200 chds=a لاحظ أنه يجب عدم استخدام القيم < 0 للمخططات الدائرية.

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 في أعلى المحور الصادي. تجدر الإشارة أيضًا إلى أنّ النطاق التلقائي للمحور y لا يزال يتراوح بين 0 و100، على الرغم من معلَمة chds، وبالتالي لا تعكس قيم التصنيف قيم البيانات الفعلية.

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 وترميزها بالكامل.

مثال:

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

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

يتيح لك تنسيق الترميز الموسَّع تحديد قيم أعداد صحيحة من 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 لأعلى المقياس.

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

مخططات Pie and Venn Charts: باستخدام الرسمَين البيانيَين الدائريَين و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);

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