Tải thư viện

Trang này cho biết cách tải thư viện Biểu đồ Google.

Tải thư viện cơ bản

Trừ một vài trường hợp ngoại lệ, tất cả các trang web có Google Biểu đồ phải bao gồm các dòng sau trong <head> của trang web:

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

Dòng đầu tiên của ví dụ này sẽ tự tải trình tải. Bạn chỉ có thể tải trình tải một lần, bất kể bạn dự định vẽ bao nhiêu biểu đồ. Sau khi tải trình tải, bạn có thể gọi hàm google.charts.load một hoặc nhiều lần để tải các gói cho các loại biểu đồ cụ thể.

Đối số đầu tiên của google.charts.load là tên hoặc số phiên bản, dưới dạng chuỗi. Nếu bạn chỉ định 'current', thì bản phát hành chính thức mới nhất của Google Charts sẽ được tải. Nếu bạn muốn thử bản dựng đề xuất cho bản phát hành tiếp theo, hãy sử dụng 'upcoming'. Nhìn chung, sẽ có rất ít sự khác biệt giữa hai phiên bản này và chúng sẽ hoàn toàn giống nhau ngoại trừ khi một bản phát hành mới đang diễn ra. Một lý do phổ biến để sử dụng upcoming là bạn muốn kiểm thử một loại biểu đồ hoặc tính năng mới mà Google sắp phát hành trong một hoặc hai tháng tới. (Chúng tôi thông báo các bản phát hành sắp tới trên diễn đàn của mình và bạn nên dùng thử các bản phát hành đó khi chúng tôi thông báo để đảm bảo rằng mọi thay đổi đối với biểu đồ của bạn đều được chấp nhận.)

Ví dụ ở trên giả định bạn muốn hiển thị một corechart (thanh, cột, đường, vùng, vùng chia bậc, bong bóng, hình bánh, vòng tròn, kết hợp, hình nến, biểu đồ, tán xạ). Nếu bạn muốn một loại biểu đồ khác hoặc bổ sung, hãy thay thế hoặc thêm tên gói thích hợp cho corechart ở trên (ví dụ: {packages: ['corechart', 'table', 'sankey']}. Bạn có thể tìm thấy tên gói trong phần "Đang tải" của trang tài liệu của từng biểu đồ.

Ví dụ này cũng giả định rằng bạn có một hàm JavaScript tên là drawChart được xác định ở đâu đó trong trang web của mình. Bạn có thể đặt tên cho hàm đó theo ý muốn, nhưng hãy đảm bảo rằng hàm đó là duy nhất trên toàn cầu và được xác định trước khi bạn tham chiếu hàm đó trong lệnh gọi đến google.charts.setOnLoadCallback.

Lưu ý: Các phiên bản trước của Google Charts sử dụng mã khác với mã ở trên để tải thư viện. Để cập nhật các biểu đồ hiện có để sử dụng mã mới, hãy xem phần Cập nhật mã trình tải thư viện.

Dưới đây là ví dụ đầy đủ về cách vẽ biểu đồ hình tròn bằng kỹ thuật tải cơ bản:

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

Thông tin về quá trình tải

Trước tiên, bạn phải tải chính trình tải, được thực hiện trong một thẻ script riêng biệt với src="https://www.gstatic.com/charts/loader.js". Thẻ này có thể nằm trong head hoặc body của tài liệu, hoặc có thể được chèn động vào tài liệu trong khi đang tải hoặc sau khi tải xong. 

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

Sau khi trình tải được tải, bạn có thể gọi google.charts.load. Bạn có thể gọi phương thức này trong thẻ script trong head hoặc body của tài liệu, đồng thời có thể gọi phương thức này trong khi tài liệu vẫn đang tải hoặc bất cứ lúc nào sau khi tài liệu tải xong.

Kể từ phiên bản 45, bạn có thể gọi google.charts.load nhiều lần để tải các gói bổ sung, mặc dù bạn nên tránh làm như vậy. Bạn phải cung cấp cùng một số phiên bản và chế độ cài đặt ngôn ngữ mỗi lần.

Hiện bạn có thể sử dụng tham số URL JSAPI autoload cũ, nhưng giá trị của tham số này phải sử dụng định dạng JSON và mã hoá URL nghiêm ngặt. Trong JavaScript, bạn có thể mã hoá jsonObject bằng mã sau: encodeURIComponent(JSON.stringify(jsonObject)).

Hạn chế

Nếu bạn đang sử dụng các phiên bản trước phiên bản 45, thì có một số hạn chế nhỏ nhưng quan trọng về cách bạn tải Google Charts:

  1. Bạn chỉ có thể gọi google.charts.load một lần. Tuy nhiên, bạn có thể liệt kê tất cả các gói mà bạn cần trong một lệnh gọi, vì vậy, bạn không cần thực hiện các lệnh gọi riêng biệt.
  2. Nếu đang sử dụng ChartWrapper, bạn phải tải rõ ràng tất cả các gói cần thiết thay vì dựa vào ChartWrapper để tự động tải các gói đó cho bạn.
  3. Đối với Geochart và Map Chart, bạn phải tải cả trình tải thư viện cũ và trình tải thư viện mới. Xin nhắc lại, việc này chỉ dành cho các phiên bản trước phiên bản 45 và bạn không nên làm việc này cho các phiên bản sau đó. 
    <script src="https://www.gstatic.com/charts/loader.js"></script>
<script src="https://www.google.com/jsapi"></script>

Tải tên hoặc số phiên bản

Đối số đầu tiên của lệnh gọi google.charts.load là tên hoặc số phiên bản. Chỉ có hai tên phiên bản đặc biệt tại thời điểm này và một vài phiên bản bị treo.

hồ sơ thanh toán
Đây là dành cho bản phát hành chính thức mới nhất, thay đổi mỗi khi chúng tôi phát hành một bản phát hành mới. Phiên bản này được kiểm thử kỹ lưỡng và không có lỗi, nhưng bạn nên chỉ định một phiên bản đã đóng băng cụ thể sau khi bạn hài lòng rằng phiên bản đó đang hoạt động.
sắp tới
Đây là dành cho bản phát hành tiếp theo, trong khi bản phát hành này vẫn đang được thử nghiệm và trước khi trở thành bản phát hành chính thức hiện tại. Vui lòng thường xuyên kiểm thử phiên bản này để biết sớm nhất có thể liệu có vấn đề nào cần giải quyết trước khi phiên bản này trở thành bản phát hành chính thức hay không.

Khi phát hành các phiên bản mới của Google Charts, một số thay đổi sẽ rất lớn, chẳng hạn như các loại biểu đồ hoàn toàn mới. Các thay đổi khác là nhỏ, chẳng hạn như cải tiến giao diện hoặc hành vi của các biểu đồ hiện có.

Nhiều nhà sáng tạo biểu đồ trên Google Chart điều chỉnh giao diện của biểu đồ cho đến khi biểu đồ đó trông đúng như họ mong muốn. Một số nhà sáng tạo có thể cảm thấy thoải mái hơn khi biết rằng các bảng xếp hạng của họ sẽ không bao giờ thay đổi, bất kể chúng tôi cải thiện những gì trong tương lai. Đối với những người dùng đó, chúng tôi hỗ trợ Google Charts đã cố định.

Các phiên bản biểu đồ đóng băng được xác định theo số và được mô tả trong Bản phát hành chính thức của chúng tôi. Để tải một phiên bản bị treo, hãy thay thế current hoặc upcoming trong lệnh gọi google.charts.load bằng số phiên bản bị treo:

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

Chúng tôi dự kiến các phiên bản bị đóng băng sẽ vẫn hoạt động vô thời hạn, mặc dù chúng tôi có thể ngừng cung cấp các phiên bản bị đóng băng có vấn đề về bảo mật. Chúng tôi thường không hỗ trợ các phiên bản bị đóng băng, ngoại trừ việc đề xuất bạn nâng cấp lên phiên bản mới hơn.

Tải cài đặt

Tham số thứ hai trong lệnh gọi google.charts.load là một đối tượng để chỉ định chế độ cài đặt. Các thuộc tính sau được hỗ trợ cho chế độ cài đặt.

gói hàng
Một mảng gồm 0 hoặc nhiều gói. Mỗi gói được tải sẽ có mã cần thiết để hỗ trợ một tập hợp chức năng, thường là một loại biểu đồ. Gói hoặc các gói bạn cần tải được liệt kê trong tài liệu cho từng loại biểu đồ. Bạn có thể tránh chỉ định bất kỳ gói nào nếu sử dụng ChartWrapper để tự động tải những gì cần thiết.
language
Mã cho ngôn ngữ hoặc ngôn ngữ bản địa cần dùng để tuỳ chỉnh văn bản có thể là một phần của biểu đồ. Hãy xem phần Ngôn ngữ để biết thêm thông tin chi tiết.
lệnh gọi lại
Một hàm sẽ được gọi sau khi các gói được tải. Ngoài ra, bạn có thể chỉ định hàm này bằng cách gọi google.charts.setOnLoadCallback như minh hoạ trong ví dụ trên. Hãy xem phần Callback để biết thêm thông tin chi tiết. 
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
mapsApiKey
(phiên bản 45) Chế độ cài đặt này cho phép bạn chỉ định một khoá mà bạn có thể sử dụng với Biểu đồ địa lý và Biểu đồ bản đồ. Bạn nên làm như vậy thay vì sử dụng hành vi mặc định có thể dẫn đến việc thỉnh thoảng điều tiết dịch vụ cho người dùng. Tìm hiểu cách thiết lập khoá của riêng bạn để sử dụng dịch vụ "API JavaScript của Google Maps" tại đây: Lấy khoá/Xác thực. Mã của bạn sẽ có dạng như sau: 
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
safeMode
(v47) Khi bạn đặt thành true, tất cả các biểu đồ và chú thích tạo HTML từ dữ liệu do người dùng cung cấp sẽ dọn dẹp dữ liệu đó bằng cách loại bỏ các phần tử và thuộc tính không an toàn. Ngoài ra (phiên bản 49 trở lên), bạn có thể tải thư viện ở chế độ an toàn bằng một lối tắt chấp nhận cùng chế độ cài đặt tải, nhưng luôn tải phiên bản "hiện tại": 
  google.charts.safeLoad({ packages: ['corechart'] });

Ngôn ngữ

Ngôn ngữ được dùng để tuỳ chỉnh văn bản cho một quốc gia hoặc ngôn ngữ, ảnh hưởng đến định dạng của các giá trị như đơn vị tiền tệ, ngày và số.

Theo mặc định, Google Biểu đồ được tải bằng ngôn ngữ "en". Bạn có thể ghi đè giá trị mặc định này bằng cách chỉ định rõ một ngôn ngữ trong phần cài đặt tải.

Để tải một biểu đồ được định dạng cho một ngôn ngữ cụ thể, hãy sử dụng chế độ cài đặt language như sau: 

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

Hãy truy cập vào đường liên kết này để xem ví dụ thực tế.

Số nhận cuộc gọi lại

Trước khi có thể sử dụng bất kỳ gói nào do google.charts.load tải, bạn phải đợi quá trình tải hoàn tất. Bạn không chỉ cần đợi tài liệu tải xong. Vì quá trình tải này có thể mất một chút thời gian, nên bạn cần đăng ký một hàm gọi lại. Có 3 cách để thực hiện việc này. Chỉ định chế độ cài đặt callback trong lệnh gọi google.charts.load hoặc gọi setOnLoadCallback truyền một hàm làm đối số hoặc sử dụng Lời hứa được trả về bằng lệnh gọi của google.charts.load.

Xin lưu ý rằng đối với tất cả các cách này, bạn cần cung cấp định nghĩa hàm thay vì gọi hàm. Định nghĩa hàm mà bạn cung cấp có thể là một hàm được đặt tên (vì vậy, bạn chỉ cần đặt tên cho hàm đó) hoặc một hàm ẩn danh. Khi các gói tải xong, hàm callback này sẽ được gọi mà không có đối số. Trình tải cũng sẽ đợi tài liệu tải xong trước khi gọi lệnh gọi lại.

Nếu muốn vẽ nhiều biểu đồ, bạn có thể đăng ký nhiều hàm gọi lại bằng setOnLoadCallback hoặc kết hợp các hàm đó thành một hàm. Tìm hiểu thêm về cách Vẽ nhiều biểu đồ trên một trang. 

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

Lệnh gọi lại thông qua Lời hứa

Một cách khác để đăng ký lệnh gọi lại là sử dụng Lời hứa được trả về từ lệnh gọi google.charts.load. Bạn có thể thực hiện việc này bằng cách thêm lệnh gọi vào phương thức then() bằng mã như sau. 

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

Một lợi ích của việc sử dụng Lời hứa là sau đó, bạn có thể dễ dàng vẽ thêm nhiều biểu đồ chỉ bằng cách tạo chuỗi các lệnh gọi .then(anotherFunction) khác. Việc sử dụng Lời hứa cũng liên kết lệnh gọi lại với các gói cụ thể cần thiết cho lệnh gọi lại đó. Đây là điều quan trọng nếu bạn muốn tải thêm các gói bằng một lệnh gọi khác của google.charts.load().

Cập nhật mã trình tải thư viện

Các phiên bản trước của Google Charts sử dụng mã khác để tải thư viện. Bảng dưới đây cho thấy mã trình tải thư viện cũ so với mã mới.

Mã trình tải thư viện cũ 
<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>
Mã trình tải thư viện mới 
<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
</script>

Để cập nhật các biểu đồ hiện có, bạn có thể thay thế mã trình tải thư viện cũ bằng mã mới. Tuy nhiên, hãy lưu ý đến các giới hạn về việc tải thư viện được mô tả ở trên.