此页面介绍了如何加载 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> |
如需更新现有图表,您可以将旧的库加载器代码替换为新代码。但请注意,在加载库时受到上述限制。