تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

القيود

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

يمكنك الاتصال بـ google.charts.load مرة واحدة فقط. ولكن يمكنك إدراج جميع الحِزم التي ستحتاج إليها في مكالمة واحدة، وبذلك لن تكون هناك حاجة إلى إجراء مكالمات منفصلة.
إذا كنت تستخدم ChartWrapper، يجب تحميل جميع الحزم التي ستحتاج إليها بشكل صريح، بدلاً من الاعتماد على ChartWrapper لتحميلها تلقائيًا نيابة عنك.
بالنسبة إلى المخطط الجغرافي ومخطط الخريطة، عليك تحميل كل من أداة تحميل المكتبة القديمة وأداة تحميل المكتبة الجديدة. ونكرّر ذلك، فقط في الإصدارات السابقة للإصدار 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  });

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، عليك الانتظار حتى انتهاء التحميل. ولا يكفي الانتظار حتى ينتهي تحميل المستند. وبما أنّ هذه العملية قد تستغرق بعض الوقت قبل أن ينتهي التحميل، يجب تسجيل دالة معاودة الاتصال. ويمكن إجراء ذلك بثلاث طرق. ويمكنك إما تحديد إعداد 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();
      });

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

تتوفّر طريقة أخرى لتسجيل معاودة الاتصال وهي استخدام الوعد الذي يتم عرضه من المكالمة 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>

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

<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>

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

التالي: إعداد البيانات