本页介绍了如何加载 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>
正在加载详情
首先,您必须加载加载器本身,加载过程是在单独的 script
标记中通过 src="https://www.gstatic.com/charts/loader.js"
完成的。此标记可以位于文档的 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 自动为您加载它们。
- 对于 Geochart 和地图图表,您必须同时加载旧的库加载器和新的库加载器。同样,这仅适用于 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 });
- 安全模式
- (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> |
如需更新现有图表,您可以将新库加载器代码替换为新代码。 不过,请注意上述加载库方面的限制。