کتابخانه ها را بارگیری کنید

این صفحه نحوه بارگیری کتابخانه های نمودار گوگل را نشان می دهد.

بارگذاری کتابخانه پایه

به جز چند استثنا، همه صفحات وب دارای نمودارهای گوگل باید خطوط زیر را در <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']} . نام بسته را می‌توانید در ' پیدا کنید بخش بارگیری صفحه اسناد برای هر نمودار.

این مثال همچنین فرض می کند که یک تابع جاوا اسکریپت به نام 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 استفاده کند. در جاوا اسکریپت، می توانید رمزگذاری jsonObject با این کد انجام دهید: encodeURIComponent(JSON.stringify(jsonObject)) .

محدودیت ها

اگر از نسخه‌های قبل از نسخه ۴۵ استفاده می‌کنید، چند محدودیت جزئی اما مهم در نحوه بارگیری نمودارهای Google وجود دارد:

  1. فقط یک بار می توانید با google.charts.load تماس بگیرید. اما می‌توانید تمام بسته‌هایی را که در یک تماس نیاز دارید فهرست کنید، بنابراین نیازی به برقراری تماس جداگانه نیست.
  2. اگر از ChartWrapper استفاده می‌کنید، به جای اینکه به ChartWrapper برای بارگیری خودکار آن‌ها برای شما تکیه کنید، باید صراحتاً تمام بسته‌های مورد نیاز خود را بارگیری کنید.
  3. برای Geochart و Map Chart ، باید هم بارکننده کتابخانه قدیمی و هم بارکننده کتابخانه جدید را بارگیری کنید. باز هم، این فقط برای نسخه های قبل از v45 است و برای نسخه های بعدی نباید این کار را انجام دهید. 
    <script src="https://www.gstatic.com/charts/loader.js"></script>
<script src="https://www.google.com/jsapi"></script>

بارگذاری نام یا شماره نسخه

اولین آرگومان تماس google.charts.load شما نام یا شماره نسخه است. در حال حاضر تنها دو نام نسخه ویژه و چندین نسخه ثابت وجود دارد.

جاری
این برای آخرین نسخه رسمی است که هر بار که نسخه جدیدی را منتشر می کنیم تغییر می کند. این نسخه در حالت ایده آل به خوبی تست شده و بدون اشکال است، اما ممکن است بخواهید به جای آن یک نسخه منجمد خاص را مشخص کنید، زمانی که از کارکرد آن راضی شدید.
آینده
این برای نسخه بعدی است، در حالی که هنوز در حال آزمایش است و قبل از اینکه نسخه رسمی فعلی شود. لطفاً این نسخه را مرتباً آزمایش کنید تا در اسرع وقت بدانید که آیا مشکلاتی وجود دارد که باید قبل از انتشار رسمی این نسخه برطرف شود.

وقتی نسخه‌های جدید نمودارهای 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 برای بارگیری خودکار موارد مورد نیاز استفاده می‌کنید، می‌توانید از تعیین بسته‌ها اجتناب کنید.
زبان
کد زبان یا محلی که باید برای سفارشی کردن متنی باشد که ممکن است بخشی از نمودار باشد. برای جزئیات بیشتر به Locales مراجعه کنید.
پاسخ به تماس
تابعی که پس از بارگیری بسته ها فراخوانی می شود. یا می توانید این تابع را با فراخوانی google.charts.setOnLoadCallback همانطور که در مثال بالا نشان داده شده است مشخص کنید. برای جزئیات بیشتر به Callback مراجعه کنید.
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
mapsApiKey
(نسخه 45) این تنظیم به شما امکان می دهد کلیدی را مشخص کنید که می توانید با Geochart و Map Chart استفاده کنید. ممکن است بخواهید این کار را به جای استفاده از رفتار پیش‌فرض انجام دهید که ممکن است منجر به کاهش گاه به گاه سرویس برای کاربران شما شود. نحوه تنظیم کلید خود را برای استفاده از سرویس «Google Maps JavaScript API» در اینجا بیاموزید: یک کلید/احراز هویت دریافت کنید. کد شما چیزی شبیه به این خواهد بود:
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
حالت امن
(v47) وقتی روی true تنظیم شود، تمام نمودارها و نکات ابزاری که HTML را از داده های ارائه شده توسط کاربر تولید می کنند، با حذف عناصر و ویژگی های ناامن، آن را پاکسازی می کنند. متناوباً (v49+)، کتابخانه را می‌توان در حالت امن با استفاده از میانبری بارگیری کرد که تنظیمات بارگیری یکسان را می‌پذیرد، اما همیشه نسخه «جاری» را بارگیری می‌کند:
  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 استفاده کنید، باید منتظر بمانید تا بارگیری به پایان برسد. فقط منتظر ماندن برای اتمام بارگیری سند کافی نیست. از آنجایی که ممکن است مدتی طول بکشد تا این بارگیری به پایان برسد، باید یک تابع تماس را ثبت کنید. سه راه برای این کار وجود دارد. یا در تماس google.charts.load خود یک تنظیم callback به تماس را مشخص کنید، یا با ارسال تابعی به عنوان آرگومان، setOnLoadCallback را فراخوانی کنید، یا از Promise استفاده کنید که با فراخوانی 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

یکی دیگر از راه‌های ثبت پاسخ تماس خود استفاده از Promise است که از تماس google.charts.load برگردانده می‌شود. این کار را با افزودن یک فراخوانی به متد then() با کدی شبیه به زیر انجام می دهید.

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

یکی از مزایای استفاده از Promise این است که می‌توانید به راحتی نمودارهای بیشتری را فقط با زنجیر کردن تماس‌های .then(anotherFunction) بیشتری رسم کنید. استفاده از Promise همچنین پاسخ تماس را به بسته‌های خاص مورد نیاز برای آن تماس مرتبط می‌کند، که اگر می‌خواهید بسته‌های بیشتری را با تماس دیگری از google.charts.load() بارگیری کنید، مهم است.

کد لودر کتابخانه را به روز کنید

نسخه های قبلی نمودارهای گوگل از کدهای مختلفی برای بارگیری کتابخانه ها استفاده می کردند. جدول زیر کد لودر کتابخانه قدیمی را در مقابل کد جدید نشان می دهد.

کد لودر کتابخانه قدیمی
<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>

برای به‌روزرسانی نمودارهای موجود، می‌توانید کد قدیمی بارگذار کتابخانه را با کد جدید جایگزین کنید. با این حال، محدودیت های بارگیری کتابخانه ها را که در بالا توضیح داده شد، در نظر داشته باشید.