此页面由 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>

如需更新现有图表，您可以将旧的库加载器代码替换为新代码。但请注意，在加载库时受到上述限制。