加载库
此页面显示了如何加载 Google 图表库。
基本库加载
除了少数例外,所有带有 Google Charts 的网页都应该在网页的 中包含以下几行<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 Charts。如果您想尝试下一个版本的候选版本,请'upcoming'
改用。一般来说,两者之间几乎没有什么区别,除非有新版本正在进行中,否则它们将完全相同。使用的一个常见原因upcoming
是您想测试 Google 将在未来一两个月内发布的新图表类型或功能。(我们在我们的论坛上宣布即将发布的版本, 并建议您在发布时试用它们,以确保对您的图表所做的任何更改都是可以接受的。)
上面的示例假设您要显示corechart
(条形、列、线、区域、阶梯区域、气泡、饼图、甜甜圈、组合、烛台、直方图、散点图)。如果您想要不同的或附加的图表类型,请替换或添加上述适当的包名称corechart
(例如,{packages: ['corechart', 'table', 'sankey']}
您可以在每个图表的文档页面的“加载”部分中找到包名称。
此示例还假设您drawChart
在网页中的某处定义了一个名为 JavaScript 的函数。您可以随意命名该函数,但请确保它是全局唯一的,并且在调用 google.charts.setOnLoadCallback
.
注意:以前版本的 Google Charts 使用与上述不同的代码来加载库。要更新现有图表以使用新代码,请参阅更新库加载程序代码。
这是使用基本加载技术绘制饼图的完整示例:
<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
. 您可以在文档script
的head
或 标签中body
调用它,您可以在文档仍在加载时或在加载完成后的任何时间调用它。
从版本 45 开始,您可以google.charts.load
多次调用以加载其他包,但如果可以避免这样做会更安全。您必须每次提供相同的版本号和语言设置。
您现在可以使用旧的 JSAPI autoload
URL 参数,但此参数的值必须使用严格的 JSON 格式和 URL 编码。在 JavaScript 中,您可以 jsonObject
使用以下代码进行编码: encodeURIComponent(JSON.stringify(jsonObject))
.
限制
如果您使用的是 v45 之前的版本,则加载 Google Charts 的方式存在一些次要但重要的限制:
- 您只能调用
google.charts.load
一次。但是您可以在一次调用中列出您需要的所有软件包,因此无需进行单独调用。 - 如果您使用的是 ChartWrapper,则必须显式加载您需要的所有包,而不是依赖 ChartWrapper 自动为您加载它们。
- 对于Geochart和 Map Chart,您必须同时加载旧库加载器和新库加载器。再次,这是只针对之前V45的版本,你应该不会更高版本做到这一点。
加载版本名称或编号
您google.charts.load
调用的第一个参数是版本名称或编号。目前只有两个特殊版本名称,以及几个冻结版本。
当前:
这是针对最新的官方版本,每次我们推出新版本时都会发生变化。理想情况下,此版本经过良好测试且没有错误,但是一旦您对它的工作感到满意,您可能希望指定一个特定的冻结版本。
未来:
这是为下一个版本准备的,它仍在测试中,在它成为正式的
当前版本之前。请定期测试此版本,以便您在此版本正式发布之前尽快了解是否存在需要解决的问题。
当我们发布新版本的 Google Charts 时,一些变化很大,比如全新的图表类型。其他更改很小,例如对现有图表的外观或行为的增强。
许多 Google 图表创建者会微调图表的外观和风格,直到完全符合他们的要求。一些创作者可能会更自在地知道他们的图表永远不会改变,无论我们将来做出什么改进。对于这些用户,我们支持冻结的Google 图表。
冻结图表版本由编号标识,并在我们的官方版本中进行了描述 。要加载冻结版本,请替换current
或upcoming
在您的调用中google.charts.load
使用冻结版本号:
<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 自动加载所需的内容,则可以避免指定任何包。
语
用于自定义可能是图表一部分的文本的语言或区域设置的代码。有关更多详细信息,请参阅语言环境。
打回来
加载包后将调用的函数。或者,您可以通过调用来指定此函数,google.charts.setOnLoadCallback
如上例所示。有关更多详细信息,请参阅 回调。
google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
地图API密钥
(v45) 此设置可让您指定可用于 Geochart和 Map Chart 的键。您可能希望这样做而不是使用默认行为,这可能会导致您的用户的服务偶尔受到限制。在此处了解如何设置您自己的密钥以使用“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 Charts 加载了“en”语言环境。您可以通过在加载设置中明确指定区域设置来覆盖此默认值。
要加载为特定语言环境设置格式的图表,请使用如下language
设置:
// Load Google Charts for the Japanese locale.//选择适合自己的语言 google.charts.load('current', {'packages':['corechart'], 'language': 'ja'});
打回来
在您可以使用任何加载的包之前,google.charts.load
您必须等待加载完成。仅仅等待文档完成加载是不够的。由于此加载完成可能需要一些时间,因此您需要注册一个回调函数。有三种方法可以做到这一点。callback
在您的google.charts.load
调用中指定一个 设置,或者调用 setOnLoadCallback
传递一个函数作为参数,或者使用调用返回的 Promise google.charts.load
。
请注意,对于所有这些方式,您都需要提供函数定义,而不是调用函数。您提供的函数定义可以是命名函数(因此您只需提供其名称)或匿名函数。当包完成加载时,将不带参数调用此回调函数。在调用回调之前,加载器还将等待文档完成加载。
如果要绘制多个图表,可以使用 注册多个回调函数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 Charts 使用不同的代码来加载库。下表显示了旧的库加载器代码与新的。
<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>
要更新现有图表,您可以用新代码替换旧的库加载器代码。但是,请记住上述加载库的 限制。