Tải thư viện

Trang này hướng dẫn cách tải thư viện Google Graph.

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

Ngoại trừ một số trường hợp ngoại lệ, tất cả trang web có Biểu đồ của Google 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 tải chính trình tải. Bạn chỉ có thể tải trình tải một lần bất kể bạn 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 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ì thao tác này sẽ tải bản phát hành chính thức mới nhất của Google Chart. Nếu bạn muốn dùng thử bản phát hành tiếp theo, hãy dùng 'upcoming'. Nhìn chung, có rất ít sự khác biệt giữa hai phần tử này và các lượt chuyển đổi này sẽ hoàn toàn giống nhau, ngoại trừ thời điểm có bản phát hành mới. Một lý do phổ biến để sử dụng upcoming là bạn muốn thử nghiệm 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 và khuyên bạn nên dùng thử khi được 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, dòng, khu vực, khu vực bậc, bong bóng, hình tròn, bánh donut, tổ hợp, nến, biểu đồ, tán xạ). Nếu bạn muốn một loại biểu đồ khác hoặc biểu đồ bổ sung, hãy thay thế hoặc thêm tên gói phù 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" trên trang tài liệu cho từng biểu đồ.

Ví dụ này cũng giả định rằng bạn có một hàm JavaScript có tên là drawChart được định nghĩa ở một vị trí nào đó trong trang web của bạn. Bạn có thể đặt tên cho hàm đó theo bất kỳ cách nào bạn 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 trong lệnh gọi google.charts.setOnLoadCallback.

Lưu ý: Các phiên bản trước của biểu đồ Google 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ó nhằm 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ụ hoàn chỉnh 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>

Chi tiết tải

Trước tiên, bạn phải tải chính trình tải này. Việc này được thực hiện trong một thẻ script riêng biệt có 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 đã tải, bạn có thể gọi google.charts.load. Vị trí bạn gọi có thể là trong một thẻ script trong head hoặc body của tài liệu. Bạn có thể gọi tài liệu đó 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. Tuy nhiên, việc này sẽ an toàn hơn nếu bạn có thể 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 autoload API JS cũ, nhưng giá trị của tham số này phải sử dụng nghiêm ngặt định dạng JSON và mã hóa URL. Trong JavaScript, bạn có thể mã hoá jsonObject bằng mã này: encodeURIComponent(JSON.stringify(jsonObject)).

Hạn chế

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

  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 cần thiết trong một lệnh gọi, nên bạn không cần thực hiện lệnh gọi riêng.
  2. Nếu đang sử dụng GraphWrapper, bạn phải tải tất cả các gói bạn sẽ cần, thay vì dựa vào ChartWrapper để tự động tải các gói đó cho bạn.
  3. Đối với Sơ đồ địa lý và Biểu đồ bản đồ, 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ỉ áp dụng 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 này. 
    <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 phiên bản hoặc số. Hiện tại, chỉ có hai tên phiên bản đặc biệt và một số phiên bản bị treo.

cường độ dòng điện
Đây là bản phát hành chính thức mới nhất. Bản phát hành này sẽ thay đổi mỗi lần chúng tôi ra mắt một bản phát hành mới. Phiên bản này nên được thử nghiệm tốt và không có lỗi. Tuy nhiên, bạn nên chỉ định một phiên bản cụ thể được đóng băng sau khi đã hài lòng với phiên bản này.
sắp tới
Đây là bản phát hành tiếp theo, trong khi vẫn đang trong quá trình thử nghiệm và chưa có phiên bản chính thức hiện tại. Vui lòng kiểm tra phiên bản này thường xuyên để bạn biết sớm nhất có thể có bất kỳ 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 không.

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

Nhiều nhà sáng tạo trên Google Biểu đồ sẽ điều chỉnh giao diện của biểu đồ cho đến khi chính xác những gì họ 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 biểu đồ 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 này, chúng tôi hỗ trợ frozen Google Chart.

Các phiên bản biểu đồ đông lạnh đượ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 phiên bản cố định, 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 rằng các phiên bản bị treo sẽ vẫn có sẵn vô thời hạn, mặc dù chúng tôi có thể gỡ bỏ các phiên bản bị treo có lo ngại về bảo mật. Chúng tôi thường sẽ không hỗ trợ các phiên bản bị treo, ngoại trừ việc đề xuất một cách không hữu ích rằng bạn nên nâng cấp lên một phiên bản mới hơn.

Tải chế độ cài đặt

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

gói hàng
Một mảng không có gói nào trở lên. 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 yêu cầu.
language
Mã cho ngôn ngữ cần tùy 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.
cuộc 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 họa trong ví dụ trên. Hãy xem phần Gọi lại để biết thêm thông tin. 
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
APIApiApi
(v45) Chế độ cài đặt này cho phép bạn chỉ định một khoá mà bạn có thể dùng với Sơ đồ địa lý và Biểu đồ bản đồ. Bạn có thể muốn thực hiện việc này thay vì sử dụng hành vi mặc định (có thể dẫn đến việc điều chỉnh dịch vụ không thường xuyên cho người dùng). Hãy 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: Nhận 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  });
Chế độ an toàn
(v47) Khi bạn bật chính sách này, tất cả biểu đồ và chú giải công cụ 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 (v49+), thư viện có thể được tải ở chế độ an toàn bằng cách sử dụng lối tắt chấp nhận cùng một 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ữ

Locale đượ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 việc định dạng các giá trị như 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õ ngôn ngữ trong phần cài đặt tải.

Để tải 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 đường liên kết này để xem ví dụ trực tiếp.

Lệnh 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 tải xong. Chỉ cần chờ tài liệu tải xong là đủ. Vì có thể mất một chút thời gian trước khi tải xong nên bạn cần đăng ký một hàm callback. Có 3 cách để thực hiện việc này. Hãy chỉ định một tuỳ chọn 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 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 (để bạn chỉ cần đặt tên) hoặc là 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 cách sử dụng setOnLoadCallback hoặc bạn có thể kết hợp các hàm này 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();
      });

Gọi lại qua Promise

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

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

Một lợi ích của việc sử dụng Promise là bạn có thể dễ dàng vẽ được nhiều biểu đồ hơn chỉ bằng cách sắp xếp thêm nhiều lệnh gọi .then(anotherFunction). Việc sử dụng Promise cũng liên kết lệnh gọi lại đến các gói cụ thể cần thiết cho lệnh gọi lại đó. Điều này rất quan trọng nếu bạn muốn tải thêm nhiều gói bằng một lệnh gọi google.charts.load() khác.

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

Các phiên bản trước của Google Bảng xếp hạng đã sử dụng mã khác để tải thư viện. Bảng bên dưới thể hiện 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 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 ý các giới hạn khi tải thư viện được mô tả ở trên.