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

توضّح هذه الصفحة كيفية تحميل مكتبات "الرسم البياني من 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 القديمة JSAPI autoload، ولكن يجب أن تستخدم قيمة هذه المعلمة تنسيق JSON صارمة وترميز عنوان URL. في JavaScript، يمكنك ترميز jsonObject باستخدام هذا الرمز: encodeURIComponent(JSON.stringify(jsonObject)).

القيود

إذا كنت تستخدم إصدارات قبل الإصدار v45، هناك بعض القيود البسيطة، ولكنها مهمة بشأن كيفية تحميل "خرائط Google":

  1. يمكنك الاتصال بـ google.charts.load مرة واحدة فقط. ولكن يمكنك إدراج كل الحِزم التي ستحتاج إليها في مكالمة واحدة، لذا لا حاجة إلى إجراء مكالمات منفصلة.
  2. إذا كنت تستخدم ChartWrapper، يجب تحميل كل الحِزم التي تحتاج إليها بشكل صريح، بدلاً من الاعتماد على Chartraapper لتحميلها تلقائيًا.
  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) يتيح لك هذا الإعداد تحديد مفتاح يمكنك استخدامه مع الموقع الجغرافي ورسم بياني للخريطة. قد تريد إجراء ذلك بدلاً من استخدام السلوك التلقائي، ما قد يؤدي إلى حظر المستخدمين من حين إلى آخر للخدمة. يمكنك الاطّلاع على كيفية إعداد مفتاحك الخاص لاستخدام خدمة "واجهة برمجة تطبيقات JavaScript ل"خرائط Google" هنا: الحصول على مفتاح/مصادقة. سيظهر الرمز الخاص بك على النحو التالي: 
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
الوضع الآمن
(الإصدار 47) عند الضبط على "صحيح"، فإن جميع الرسوم البيانية والتلميحات التي تنشئ 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، عليك الانتظار حتى ينتهي التحميل. ولا يكفي الانتظار حتى ينتهي تحميل المستند. وبما أنّ عملية التحميل قد تستغرق بعض الوقت، عليك تسجيل دالة رد اتصال. وهناك ثلاث طرق لإجراء ذلك. يمكنك إما تحديد إعداد callback في الطلب google.charts.load، أو استدعاء setOnLoadCallback بعد تمرير دالة كوسيطة، أو استخدام الوعد الذي يتم عرضه من خلال استدعاء google.charts.load.

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

إذا كنت تريد رسم أكثر من رسم بياني واحد، يمكنك تسجيل أكثر من دالة استدعاء واحدة باستخدام 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). ومن خلال استخدام ميزة "الوعد"، يتم أيضًا ربط معاودة الاتصال بحزم البيانات المطلوبة لمعاودة الاتصال هذه، وهو أمر مهم إذا كنت تريد تحميل المزيد من الحِزم من خلال استدعاء آخر لـ 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>

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