此页面由 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（条形图、柱形图、折线图、面积图、阶梯形面积图、气泡图、饼图、甜甜圈图、组合图、K 线图、直方图、散点图）。如果您想要使用其他或额外的图表类型，请将上面的 corechart 替换为或添加适当的软件包名称（例如{packages: ['corechart', 'table', 'sankey']}。您可以在每个图表文档页面的“加载”部分找到软件包名称。

本示例还假定您在网页的某个位置定义了一个名为 drawChart 的 JavaScript 函数。您可以随意为该函数命名，但请确保该函数是全局唯一的，并且在您调用 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>

正在加载详细信息

首先，您必须加载加载器本身，这可以在包含 src="https://www.gstatic.com/charts/loader.js" 的单独 script 标记中完成。此代码可以位于文档的 head 或 body 中，也可以在文档加载期间或加载完成后动态插入到文档中。

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

加载器加载完毕后，您可以随意调用 google.charts.load。您可以在文档的 head 或 body 中的 script 标记中调用它，并且可以在文档仍在加载时或加载完成后的任何时间调用它。

从版本 45 开始，您可以多次调用 google.charts.load 以加载其他软件包，但最好避免这样做。您每次都必须提供相同的版本号和语言设置。

您现在可以使用旧版 JSAPI autoload 网址参数，但此参数的值必须使用严格的 JSON 格式和网址编码。在 JavaScript 中，您可以使用以下代码对 jsonObject 进行编码：encodeURIComponent(JSON.stringify(jsonObject))。

限制

如果您使用的是v45 之前的版本，则在加载 Google 图表时会遇到一些细微但重要的限制：

您只能调用 google.charts.load 一次。不过，您可以在一次调用中列出所需的所有软件包，这样就无需进行单独的调用。
如果您使用的是 ChartWrapper，则必须显式加载所需的所有软件包，而不是依赖 ChartWrapper 自动为您加载这些软件包。
对于地理图表和地图图表，您必须同时加载旧版库加载器和新版库加载器。再次提醒，这仅适用于 v45 之前的版本，对于更高版本，您不应这样做。
```
<script src="https://www.gstatic.com/charts/loader.js"></script>
<script src="https://www.google.com/jsapi"></script>
```

加载版本名称或编号

google.charts.load 调用的第一个参数是版本名称或编号。目前只有两个特殊版本名称和几个冻结版本。

当前: 这是最新的官方版本，每当我们推出新版本时，都会发生变化。理想情况下，此版本应经过充分测试且没有 bug，但在您确信其正常运行后，可能需要改为指定特定的冻结版本。
即将到来的: 这是针对下一版本的，该版本目前仍在测试中，尚未成为当前的正式版本。请定期测试此版本，以便尽快了解在该版本成为正式版之前是否有任何问题需要解决。

当我们发布新版 Google 图表时，有一些重大变化，例如全新的图表类型。其他更改较小，例如改进现有图表的外观或行为。

许多 Google 图表制作者都会对图表的外观和风格进行微调，直到达到他们想要的效果。一些创作者可能会更愿意知道他们的图表永远不会改变，无论我们未来做出哪些改进。对于这些用户，我们支持冻结的 Google 图表。

冻结的排行榜版本通过数字标识，详情请参阅我们的官方版本。如需加载冻结的版本，请将 google.charts.load 调用中的 current 或 upcoming 替换为冻结的版本号：

<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

应用于自定义可能包含在图表中的文本的语言或语言区域的代码。如需了解详情，请参阅语言区域。

callback

一个在软件包加载完毕后调用的函数。或者，您也可以通过调用 google.charts.setOnLoadCallback 来指定此函数，如上例所示。如需了解详情，请参阅回调。

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

mapsApiKey

(v45) 通过此设置，您可以指定可与地理图表和地图图表搭配使用的键。您可能需要这样做，而不是使用默认行为，因为默认行为可能会导致用户的服务偶尔出现节流。如需了解如何设置自己的密钥以使用“Google Maps JavaScript API”服务，请参阅以下链接：获取密钥/进行身份验证。您的代码应如下所示：

  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });

safeMode

(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，或者使用调用 google.charts.load 返回的 Promise。

请注意，对于所有这些方法，您都需要提供函数定义，而不是调用函数。您提供的函数定义可以是命名函数（只需指定其名称），也可以是匿名函数。当软件包加载完毕时，系统会调用此回调函数，但不传递任何参数。加载器还会等待文档加载完成，然后再调用回调。

如果您想绘制多个图表，可以使用 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 调用返回的 Promise。为此，请添加对 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>

如需更新现有图表，您可以将旧的库加载器代码替换为新代码。不过，请注意上面介绍的加载库的限制。