تحميل المكتبات

توضّح هذه الصفحة كيفية تحميل مكتبات "رسومات Google".

تحميل المكتبة الأساسية

باستثناء بعض الحالات، يجب أن تتضمّن جميع صفحات الويب التي تتضمّن "رسومات Google البيانية" السطور التالية في <head> صفحة الويب:

<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
  ...
</script>

يحمِّل السطر الأول من هذا المثال أداة التحميل نفسها. يمكنك تحميل أداة التحميل مرة واحدة فقط بغض النظر عن عدد المخططات التي تخطط لرسمها. بعد تحميل أداة التحميل، يمكنك استدعاء الدالة google.charts.load مرة واحدة أو أكثر لتحميل حِزم لأنواع مخطّطات بيانية معيّنة.

الوسيطة الأولى لدالة google.charts.load هي اسم الإصدار أو رقمه، بتنسيق سلسلة. إذا حددت 'current'، سيؤدي ذلك إلى تحميل آخر إصدار رسمي من "مخططات Google". إذا أردت تجربة الإصدار التمهيدي للإصدار التالي، استخدِم 'upcoming' بدلاً من ذلك. بشكل عام، سيكون هناك اختلاف بسيط جدًا بين الاثنين، وستكونان متطابقة تمامًا إلا عندما يكون هناك إصدار جديد قيد التنفيذ. من الأسباب الشائعة لمحاولة استخدام upcoming أنّك تريد اختبار نوع رسم بياني جديد أو ميزة جديدة على وشك طرحها Google في الشهر أو الشهرَين المقبلَين. (نُعلِن عن الإصدارات القادمة على منتدى، وننصحك بتجربتها عند الإعلان عنها للتأكّد من أنّه يمكن قبول أي تغييرات على الرسوم البيانية).

يفترض المثال أعلاه أنك تريد عرض corechart (شريط، عمود، خط، مساحة، منطقة الخطوات، فقاعة، دائري، كعكة، دونات، مزيج، شمعدان، مدرّج تكراري، نقاط مبعثرة). إذا كنت تريد نوع رسم بياني مختلفًا أو إضافيًا، استبدِل corechart أعلاه باسم الحزمة المناسب أو أضِفه (مثلاً، {packages: ['corechart', 'table', 'sankey']}. يمكنك العثور على اسم الحزمة في القسم "التحميل" من صفحة المستندات لكل رسم بياني.

يفترض هذا المثال أيضًا أنّ لديك دالة JavaScript اسمها drawChart محدّدة في مكان ما في صفحة الويب. يمكنك تسمية هذه الدالة باسم تريده، ولكن تأكَّد من أنّها فريدة على مستوى العالم وأنّها محدّدة قبل الإشارة إليها في طلبك لسمة google.charts.setOnLoadCallback.

ملاحظة: كانت الإصدارات السابقة من "مخطّطات Google" تستخدم رمزًا برمجيًا يختلف عمّا ورد أعلاه لتحميل المكتبات. لتعديل الرسوم البيانية الحالية لاستخدام الرمز الجديد، اطّلِع على تعديل رمز أداة تحميل المكتبة.

في ما يلي مثال كامل على رسم رسم بياني دائري باستخدام أسلوب التحميل الأساسي:

<head>
  <script src="https://www.gstatic.com/charts/loader.js"></script>
  <script>
    google.charts.load('current', {packages: ['corechart']});
    google.charts.setOnLoadCallback(drawChart);

    function drawChart() {
      // Define the chart to be drawn.
      var data = new google.visualization.DataTable();
      data.addColumn('string', 'Element');
      data.addColumn('number', 'Percentage');
      data.addRows([
        ['Nitrogen', 0.78],
        ['Oxygen', 0.21],
        ['Other', 0.01]
      ]);

      // Instantiate and draw the chart.
      var chart = new google.visualization.PieChart(document.getElementById('myPieChart'));
      chart.draw(data, null);
    }
  </script>
</head>
<body>
  <!-- Identify where the chart should be drawn. -->
  <div id="myPieChart"/>
</body>

جارٍ تحميل التفاصيل

عليك أولاً تحميل أداة التحميل نفسها، ويتم ذلك في علامة script منفصلة باستخدام src="https://www.gstatic.com/charts/loader.js". يمكن أن تكون هذه العلامة في head أو body من المستند، أو يمكن إدراجها ديناميكيًا في المستند أثناء تحميله أو بعد اكتمال التحميل. 

<script src="https://www.gstatic.com/charts/loader.js"></script>

بعد تحميل أداة التحميل، يمكنك الاتصال برقم google.charts.load. يمكنك العثور على مكان الملف في علامة script ضمن head أو body من المستند، ويمكنك استدعاؤه إما أثناء تحميل المستند أو في أي وقت بعد انتهاء تحميله.

اعتبارًا من الإصدار 45، يمكنك استدعاء google.charts.load أكثر من مرة لتحميل حِزم إضافية، ولكن من الأفضل تجنُّب ذلك. يجب تقديم رقم الإصدار وإعدادات اللغة نفسها في كل مرة.

يمكنك الآن استخدام مَعلمة عنوان URL autoload القديمة في JSAPI، ولكن يجب أن تستخدم قيمة هذه المَعلمة تنسيق JSON صارمًا وترميز عنوان URL. في JavaScript، يمكنك ترميز jsonObject باستخدام الرمز التالي: encodeURIComponent(JSON.stringify(jsonObject)).

القيود

إذا كنت تستخدم الإصدارات السابقة للإصدار 45، هناك قيدان بسيطان ولكنهما مهمان في طريقة تحميل "رسومات Google":

  1. يمكنك الاتصال برقم google.charts.load مرة واحدة فقط. ولكن يمكنك إدراج جميع الحِزم التي ستحتاج إليها في مكالمة واحدة، ما يغنيك عن إجراء مكالمات منفصلة.
  2. إذا كنت تستخدم ChartWrapper، يجب تحميل جميع الحزم التي ستحتاجها بشكل صريح، بدلاً من الاعتماد على ChartWrapper لتحميلها تلقائيًا نيابةً عنك.
  3. بالنسبة إلى الرسم البياني الجغرافي والرسم البياني على الخريطة، يجب تحميل كل من أداة تحميل المكتبة القديمة وأداة تحميل المكتبة الجديدة. يُرجى العلم أنّ هذا الإجراء مخصّص للإصدارات الأقدم من الإصدار 45، ويجب عدم اتّخاذه للإصدارات الأحدث. 
    <script src="https://www.gstatic.com/charts/loader.js"></script>
<script src="https://www.google.com/jsapi"></script>

تحميل اسم الإصدار أو رقمه

الوسيطة الأولى لدالة google.charts.load هي اسم الإصدار أو رقمه. لا يوجد سوى اسمين إصدارين خاصين في الوقت الحالي والعديد من الإصدارات المجمدة.

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

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

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

يتم تحديد إصدارات الرسوم البيانية الثابتة حسب الرقم، ويتم وصفها في الإصدارات الرسمية. لتحميل نسخة ثابتة، عليك استبدال current أو upcoming في طلب google.charts.load برقم الإصدار الثابت:

<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
    google.charts.load('43', {packages: ['corechart']});
    google.charts.setOnLoadCallback(drawChart);
    ...
</script>

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

تحميل الإعدادات

المَعلمة الثانية في طلب google.charts.load هي عنصر لتحديد الإعدادات. السمات التالية متوافقة مع الإعدادات.

طرود
مصفوفة من حِزم صفرية أو أكثر ستحتوي كل حزمة يتم تحميلها على الرمز البرمجي المطلوب لتفعيل مجموعة من الوظائف، وعادةً ما يكون نوعًا من أنواع الرسوم البيانية. يتم إدراج الحزمة أو الحِزم التي تحتاج إلى تحميلها في المستندات الخاصة بكل نوع من الرسوم البيانية. يمكنك تجنُّب تحديد أي حِزم إذا كنت تستخدم ChartWrapper لتحميل ما سيكون مطلوبًا تلقائيًا.
language
رمز اللغة أو المنطقة التي يجب استخدامها لتخصيص النص الذي قد يكون جزءًا من الرسم البياني. يمكنك الاطّلاع على اللغات لمعرفة المزيد من التفاصيل.
رد الاتصال
دالة سيتمّ استدعاؤها بعد تحميل الحِزم. وبدلاً من ذلك، يمكنك تحديد هذه الدالة من خلال استدعاء google.charts.setOnLoadCallback كما هو موضّح في المثال أعلاه. يُرجى الاطّلاع على معاودة الاتصال لمعرفة مزيد من التفاصيل. 
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
mapsApiKey
(الإصدار 45) يتيح لك هذا الإعداد تحديد مفتاح يمكنك استخدامه مع الرسم البياني الجغرافي ومخطط الخرائط. قد تحتاج إلى إجراء ذلك بدلاً من استخدام السلوك التلقائي الذي قد يؤدي إلى إبطاء الخدمة من حين لآخر للمستخدمين. تعرَّف على كيفية إعداد مفتاحك الخاص لاستخدام خدمة "Google Maps JavaScript API" على هذا الرابط: الحصول على مفتاح/مصادقة. ستبدو التعليمة البرمجية على النحو التالي: 
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
safeMode
(v47) عند ضبط هذه السياسة على "صحيح"، ستتم إزالة العناصر والسمات غير الآمنة من كل الرسوم البيانية وتلميحات الأدوات التي تنشئ HTML من البيانات التي يقدّمها المستخدمون. وبدلاً من ذلك (الإصدار 49 والإصدارات الأحدث)، يمكن تحميل المكتبة في الوضع الآمن باستخدام اختصار يقبل إعدادات التحميل نفسها، ولكن مع تحميل الإصدار "الحالي" دائمًا: 
  google.charts.safeLoad({ packages: ['corechart'] });

اللغات

تُستخدم اللغات لتخصيص النص لبلد أو لغة، ما يؤثر في تنسيق قيم مثل العملات والتواريخ والأرقام.

يتم تحميل "رسومات Google" تلقائيًا باللغة الإنجليزية (en). يمكنك إلغاء هذه القيمة التلقائية من خلال تحديد لغة معيّنة في إعدادات التحميل.

لتحميل رسم بياني منسَّق بلغة معيّنة، استخدِم الإعداد language على النحو التالي: 

  // Load Google Charts for the Japanese locale.
  google.charts.load('current', {'packages':['corechart'], 'language': 'ja'});

يمكنك الانتقال إلى هذا الرابط للاطّلاع على مثال عملي.

معاودة الاتصال

قبل أن تتمكّن من استخدام أي من الحِزم التي حمّلها google.charts.load، عليك الانتظار إلى أن تنتهي عملية التحميل. لا يكفي الانتظار إلى أن ينتهي loadingتحميل المستند. وبما أنّ هذه العملية قد تستغرق بعض الوقت قبل أن ينتهي التحميل، يجب تسجيل دالة معاودة الاتصال. هناك ثلاث طرق لإجراء ذلك. إما تحديد إعداد callback في طلب google.charts.load، أو طلب setOnLoadCallback مع تمرير دالة كوسيطة، أو استخدام الوعد الذي يتم إرجاعه من خلال طلب google.charts.load.

يُرجى العِلم أنّه عليك تقديم تعريف للدالة لكل هذه الطرق بدلاً من استدعاء الدالة. يمكن أن يكون تعريف الدالة الذي تقدّمه إما دالة مُسمّاة (لذا ما عليك سوى تقديم اسمها) أو دالة مجهولة. عند انتهاء تحميل الحزم، سيتم استدعاء دالة الاستدعاء هذه بدون وسيطات. سينتظر أداة التحميل أيضًا انتهاء تحميل المستند قبل استدعاء الدالة المرجعية.

إذا كنت تريد رسم أكثر من رسم بياني واحد، يمكنك إما تسجيل أكثر من دالة callback واحدة باستخدام setOnLoadCallback، أو يمكنك دمجها في دالة واحدة. اطّلِع على مزيد من المعلومات حول كيفية إنشاء رسوم بيانية متعددة في صفحة واحدة. 

  google.charts.setOnLoadCallback(drawChart1);
  google.charts.setOnLoadCallback(drawChart2);
  // OR
  google.charts.setOnLoadCallback(
    function() { // Anonymous function that calls drawChart1 and drawChart2
         drawChart1();
         drawChart2();
      });

معاودة الاتصال من خلال Promise

تتوفّر طريقة أخرى لتسجيل معاودة الاتصال وهي استخدام الوعد الذي يتم عرضه من المكالمة google.charts.load. يمكنك إجراء ذلك من خلال إضافة طلب إلى طريقة then() باستخدام رمز يبدو على النحو التالي. 

  google.charts.load('upcoming', {packages: ['corechart']}).then(drawChart);

من مزايا استخدام Promise أنّه يمكنك بعد ذلك بسهولة إنشاء المزيد من الرسوم البيانية من خلال تسلسل المزيد من طلبات .then(anotherFunction). يؤدي استخدام Promise أيضًا إلى ربط طلب إعادة الاتصال بالحِزم المحدّدة المطلوبة ل طلب إعادة الاتصال هذا، وهو أمر مهم إذا كنت تريد تحميل المزيد من الحِزم من خلال طلب آخر من google.charts.load().

تعديل رمز أداة تحميل المكتبة

كانت الإصدارات السابقة من "رسومات Google" تستخدم رمزًا مختلفًا لتحميل المكتبات. يعرض الجدول أدناه رمز أداة تحميل المكتبة القديم مقارنةً بالرمز الجديد.

رمز أداة تحميل المكتبة القديمة 
<script type="text/javascript" src="https://www.google.com/jsapi"></script>
<script type="text/javascript">
  google.load("visualization", "1", {packages:["corechart"]});
  google.setOnLoadCallback(drawChart);
</script>
رمز أداة تحميل المكتبة الجديدة 
<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
</script>

لتعديل الرسوم البيانية الحالية، يمكنك استبدال رمز أداة تحميل المكتبة القديم بالرمز الجديد. ومع ذلك، يجب مراعاة القيود المفروضة على تحميل المكتبات الموضّحة أعلاه.