Google Chart API 参考 中文版
文档信息
翻译: Cloudream ,最后修改:02/22/2008 06:11:08
英文版版权归 Google , 转载此中文版必须以链接形式注明原文地址、译者信息及本声明。
API 参考:http://labs.cloudream.name/google/chart/api.html
常见问题:http://labs.cloudream.name/google/chart/faq.html
简介
Google Chart API 为您提供动态创建图表的功能。单击下边的网址查看示例演示:
http://chart.apis.google.com/chart?cht=p3&chd=s:hW&chs=250x100&chl=Hello|World
您应该看到如下图表
目录
目的
本文档为使用 Google Chart API 的开发者提供 API 参考及参数说明。
使用方针
每位用户每天可发送 50,000 次请求。超过此限制后 Google 将暂时拒绝您的请求,若您继续发送请求,Google 可能会永久拒绝您的服务请求。
简介
Google Chart API 为每个请求返回一个 PNG 格式图片。目前提供如下类型图表:折线图、柱状图、饼图、维恩图、散点图。您可以设定图表尺寸、颜色和图例。
您可以在网页中使用<img>
元素插入图表,当浏览器打开该网页时,Chart API 提供即时图表。
本文档内所有图表由 Chart API 生成,查看某图片方法:
- 如果您使用 Firefox ,在图片上单击右键,选择“查看图片”或“属性”。
- 如果您使用 Internet Explorer ,在图片上单击右键,选择“属性”。
本文档将介绍 Chart API 所有参数设置。
URL格式
所有 Chart API URL 都应使用如下格式:
http://chart.apis.google.com/chart?<parameter 1>&<parameter 2>&<parameter n>
注意:每个 URL 所有字符必须在同一行内。
多个参数间使用 & 作为分隔符,您可以使用任意多个参数,如下图:
http://chart.apis.google.com/chart?cht=lc&chs=200x125&chd=s:helloWorld&chxt=x,y&chxl=0:|Mar|Apr|May|June|July|1:||50+Kb
参数解释:
-
http://chart.apis.google.com/chart?
Chart API 调用地址。 -
&
参数分隔符。 -
chs=200x125
图表尺寸。 -
chd=s:helloWorld
图表数据值。 -
cht=lc
图表类型。 -
chxt=x,y
显示 x、y 轴坐标。 -
chxl=0:|Mar|Apr|May|June|July|1:||50+Kb
x、y 轴坐标值。
你可以在网页中使用img
元素插入图表,如:
<img src="http://chart.apis.google.com/chart?chs=200x125&chd=s:helloWorld&cht=lc&chxt=x,y&chxl=0:|Mar|Apr|May|June|July|1:||50+Kb" alt="Sample chart" />
注意:在HTMLimg
元素中,URL 属性中&
字符应书写为转义字符&
。
必须、可选参数
图表尺寸
参数格式:chs=<像素宽度>x<像素高度>
例如:chs=300x200
,表示一个 300 像素宽、200 像素高的图表。
单个图表最大尺寸为 300,000 平方像素,宽高最大为 1000 像素,以下尺寸均为最大可用尺寸:1000x300,300x1000,600x500,500x600,800x375 和 375x800 等。
图表数据
图表数据有三种格式:
- 简单编码 包含 62 个数值,每个数值占据 5 个像素,适用于 300 像素大小的折线图和柱状图,所有图表类型都可以使用简单编码数据。
- 文本编码 包含 1000 个数值,使用 0.0 至 100.0 的浮点数,每十个数值占据 5 个像素,在仅使用整数的情况下,适用于 500 像素以内的图表。如需要更高精度,可使用一位小数数字(如 92.6)
- 扩展编码 包含 4096 个数值,适用于高精度或大型图表。
注意:文本编码和扩展编码使用多个字符表示一个数值。简单编码生成图表的效率最高。
简单编码
简单编码格式为
chd=s:<数值字符串>
其中<数值字符串>
可包含a-z
、A-Z
、0-9
、_
和,
。
含义如下
- 大写字母
A
= 0、B
= 1,以此类推,Z
= 25。 - 小写字母
a
= 26、b
= 27,以此类推,z
= 51。 - 数字
0
= 52,以此类推,9
= 61. - 下划线
_
表示空值。 - 逗号
,
为数据分组符号。
注意:简单编码中,图表底端为 0 ,图表顶端为 61 ,中间数值在垂直方向平均分布。
文本编码
文本编码格式为
chd=t:<数值字符串>
其中<数值字符串>
为0.0
至100.0
的浮点数、-1
(负一)和|
(竖线)。
含义如下
- 浮点数字
0.0
= 0,以此类推100.0
= 100。 - 负一
-1
表示空值。 - 竖线
|
为数据分组符号。
注意:文本编码中,图表底端为 0.0 ,图表顶端为 100.0 ,中间数值在垂直方向平均分布。
扩展编码
文本编码格式为
chd=e:<数值字符串>
其中<数值字符串>
为A-Z
、a-z
、0-9
、连字符-
、小数点.
、下划线_
和逗号,
。
含义如下
-
AA
= 0、AZ
= 25、Aa
= 26、Az
= 51、A0
= 52、A9
= 61、A-
= 62、A.
= 63、BA
= 64、BZ
= 89、.A
= 4032、.Z
= 4057、.a
= 4058、.z
= 4083、.0
= 4084、.9
= 4093、.-
= 4094、..
= 4095。 - 两个下划线
__
表示空值。 - 逗号
,
为数据分组符号。
注意:文本编码中,图表底端为 0 ,图表顶端为 4095 ,中间数值在垂直方向平均分布。
JavaScript 数值转换代码
如您所知,使用程序来自动将数值转换为 Chart API 数值比手动转换快捷得多。
下边这段 JavaScript 代码用于将数据转换为简单编码格式。第一个参数需为数据数组,负数将被转换为空值_
。
第二个参数为数据中最大值。在折线图和柱状图中,如果您希望图表顶端与最大值间有一定空间,可以使此参数值大于数据中最大值。
var simpleEncoding = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
function
simpleEncode(values,maxValue) {
var chartData = ['s:'];
for (var i
= 0; i < values.length; i++) {
var currentValue = values[i];
if
(!isNaN(currentValue) && currentValue >= 0)
{
chartData.push(simpleEncoding.charAt(Math.round((simpleEncoding.length-1)
* currentValue / maxValue)));
}
else
{
chartData.push('_');
}
}
return
chartData.join('');
}
图表粒度指导
不要为图表设定过多数据点。例如,显示布兰妮·斯皮尔斯过去十年的流行程度,如果每天搜索量作为一个数据点的话,将有 3,600 个数据点,对于 URL
来说数据太多了,Chart API 也不会生成粒度如此密的图表—— 1024 像素宽的显示器上每个数据点之占据四分之一个像素。下边的示例解释这个问题。
200x100 像素图,20 个数据点(每个数据点占 10 个像素)
40 个数据点(每个数据点占 5 个像素)
80 个数据点(每个数据点仅占 2.5 个像素)
图表类型
目前有五种图表类型:
折线图
折线图参数为
cht=<折线图类型>
<折线图类型>
可选择lc
或lxy
。
参数 | 说明 | 示例 |
---|---|---|
cht=lc |
直线图,x 轴方向均匀分布。 |
|
cht=lxy |
每条数据线使用两组数据,第一组指定 x 轴坐标,第二组指定 y 轴坐标。
第一组数据为空时数据线将在 x 数据点形状使用参数 数据线颜色参考颜色一节。 |
|
柱状图
柱状图参数为
cht=<柱状图类型>
<柱状图类型>
可选择bhs
、bhg
、bvs
和bvg
。
参数 | 说明 | 示例 |
---|---|---|
cht=bhs
|
水平(Horizontal)或垂直(Vertical)柱状图。
多组数据将绘制为层叠柱状图,所以必须设置颜色参数,具体参看颜色一节。 |
cht=bhs chco=ff0000,00aa00 cht=bvs chco=cc0000,00aa00
|
cht=bhg
|
水平(Horizontal)或垂直(Vertical)独立柱状图,可设定颜色,多组数据将分别绘制。 |
cht=bhg chco=cc0000,00aa00 cht=bvg chco=cc0000,00aa00
|
chbh |
柱状图尺寸处理方法与其它类型图表不同。
对于垂直柱状图 所以您可以指定更细的柱状图图表。 注意:第二个参数决定各组数据树状图间空白,组内数据间空白为该值一半。 |
chbh 未设置cht=bhs chbh=10 cht=bhs
|
饼图
饼图参数为
cht=<饼图类型>
<饼图类型>
可选择p
或p3
。
- 仅支持一组数据,后续数据将被忽略。
- 更多可用参数请参看可选参数。
Google Chart API
根据chs
参数决定饼图半径。请将宽高比设置为较大比例以使标注能完整显示。当标注不完整时说明宽高比偏小。
参数 | 说明 | 示例 |
---|---|---|
cht=p |
平面饼图。
使用 为设定颜色时,饼图颜色将在橘黄色和浅黄色间插值计算出。设置颜色参数请参看颜色一节。 |
|
cht=p3 |
三维饼图。
使用 |
|
维恩图
维恩图参数为cht=v
一组数据包含以下七个数值:
- 前三个数值表示 A、B、C 的相对大小关系。
- 第四个数值表示 A 和 B 重叠数值。
- 第五个数值表示 B 和 C 重叠数值。
- 第六个数值表示 A 和 C 重叠数值。
- 第七个数值表示 A、B、C 重叠数值。
参数 | 说明 | 示例 |
---|---|---|
cht=v |
示例中三个圆圈数值分别为 100、80、60,两两间重叠数值为 30。
更多可用参数请参看可选参数。 |
|
散点图
散点图参数为cht=s
参数 | 说明 | 示例 |
---|---|---|
cht=s |
需要至少两组数据,第一组指定 x 轴坐标,第二组指定 y 轴坐标。 默认数据点形状为圆圈,设定其它形状请使用 默认数据点颜色为蓝色,设置颜色请参看颜色一节。 您可能注意到了,在演示图表中,数据点拥有不同大小。如需此特性,可设置第三组数据。 |
|
颜色
使用 6 或 8 位的十六进制颜色参数,格式RRGGBB
,示例:
-
FF0000
= 红色 -
00FF00
= 绿色 -
0000FF
= 蓝色 -
000000
= 黑色 -
FFFFFF
= 白色
您可以附加两位来设定透明度,代码00
与FF
之间,00
表示完全透明,FF
表示完全不透明。
-
0000FFFF
= 不透明蓝色 -
0000FF00
= 透明蓝色
有效的颜色设定:
数据颜色
设定折线图、柱状图、维恩图和饼图数据颜色。
chco=
<颜色参数1>,
...
<颜色参数n>
其中<颜色参数1>
及后续延续参数均使用十六进制参数。
参数 | 说明 | 示例 |
---|---|---|
chco |
示例中有三组指定颜色的数据。 |
|
同样有三组数据,但只设定了两组颜色,所以最后一组数据使用最后一个颜色设定(红色FF0000 )。 |
|
|
在柱状图中,如果数据组数比颜色组数多,则数据颜色交替使用颜色设定。示例中,第三组数据使用第一个数据颜色,如果只设定了一种颜色,则所有数据都为该颜色。 |
|
|
同一组数据,设定了三组颜色。 |
|
|
在饼图中,如果数据组数比颜色组数多,则数据颜色使用颜色间内插值计算补足。 |
|
|
在维恩图中,如果数据组数比颜色组数多,多余数据组使用最后一个颜色。 |
|
区域填充、背景颜色
设定背景填充:
chf=
<bg 或 c><填充类型>
其中
实心填充
设定参数格式:
chf=
<bg 或
c>,s,<颜色>|<bg 或 c>,s,<颜色>
其中
-
<bg 或 c>
中bg
表示背景,c
表示图表区域。 -
s
代表实心填充。 -
<颜色>
为十六进制颜色RRGGBB
参数。 - 竖线
|
为填充数据组分隔符,最后一组数据后无需分隔符。
参数 | 说明 | 示例 |
---|---|---|
chf |
示例中使用灰色(EFEFEF )填充背景。 |
|
示例中使用灰色(EFEFEF )填充背景,黑色(000000 )填充图表区域。您可以为折线图和散点图同时设置背景和图表区域填充。 |
|
|
饼图、维恩图、柱状图只能设置背景颜色。 |
|
线性渐变
设定参数格式:
chf=<bg or c>,lg,<angle>,<color 1>,<offset
1>,<color n>,<offset n>
其中
-
<bg 或 c>
中bg
表示背景,c
表示图表区域。 -
lg
代表线性渐变。 -
<angle>
设定填充旋转角度,值在0
垂直与90
水平之间。 -
<颜色>
为十六进制颜色RRGGBB
参数。 -
<offset>
表示偏移量,必须在0
和1
之间,0
表示最靠左端,1
表示最靠右端。
参数 | 说明 | 示例 |
---|---|---|
chf |
图表区域填充水平线性渐变(左至右),0 度旋转。
蓝色( 白色( 图表背景设置为灰色( |
|
图表区域填充倾斜线性渐变(左下至右上),45 度旋转。
白色( 蓝色( 图表背景设置为灰色( |
|
|
图表区域填充垂直线性渐变(上至下),90 度旋转。
蓝色( 白色( 图表背景设置为灰色( |
|
线性条纹
设定参数格式:
chf=<bg or c>,ls,<angle>,<color 1>,<width
1>,<color n>,<width n>
其中
-
<bg 或 c>
中bg
表示背景,c
表示图表区域。 -
ls
代表线性条纹。 -
<angle>
设定填充旋转角度,值在0
垂直与90
水平之间。 -
<颜色>
为十六进制颜色RRGGBB
参数。 -
<width>
必须在0
和1
之间,1
表示完整宽度。重复填充条纹直至达到完整宽度。
参数 | 说明 | 示例 |
---|---|---|
chf |
图表区域填充垂直线性条纹,0 度旋转。
灰色( 白色( 交替显示条纹直至填充满图表。 图表背景未设置。 |
|
图表区域填充水平线性条纹,90 度旋转。
深灰色( 浅灰色( 交替显示条纹直至填充满图表。 图表背景未设置。 |
|
标注
可用标注类型:
图表标题
标题参数:
chtt=<图表标题>
参数 | 说明 | 示例 |
---|---|---|
chtt |
使用加号+ 代表空格。
竖线 |
|
设定标题字号和颜色(可选)。
如果图表尺寸 |
|
图表图例
图例参数:
chdl=<第一组数据图例>|<第 n 组数据图例>
参数 | 说明 | 示例 |
---|---|---|
chdl |
图例chdl 与颜色属性chco 联合使用。
示例中第一组数据使用红色,第二组使用绿色,第三组使用蓝色。 |
|
|
饼图标注
饼图标注参数:
chl=<标注一>|
...
<标注
n>
双竖线||
表示空值。
参数 | 说明 | 示例 |
---|---|---|
chdl |
三维饼图示例。 |
|
多轴标注
多轴标注可用于折线图、饼图和散点图:
坐标轴类型
可设置多个坐标轴:
chxt=
<坐标轴
1>...
<坐标轴 n>
可用坐标轴类型:
-
x
= 底部 x 坐标轴 -
t
= 顶部 x 坐标轴 -
y
= 左侧 y 坐标轴 -
r
= 右侧 y 坐标轴
chxt
参数中的坐标轴将拥有一个索引值,第一个坐标轴索引值为 0,第二个为
1,以此类推。所以您可以多次使用x
、t
、y
和r
。
创建坐标轴时仅chxt
参数是必须的,其它参数若未设定将使用默认值。
参数 | 说明 | 示例 |
---|---|---|
chxt |
图例中使用了两个底部 x 轴(两个x )一个左侧 y 轴y 、一个右侧 y轴 r 和一个顶部 x 轴t 。
注意:因为没有设置坐标值,所以 Chart API 默认使用 0 到 100。 |
|
坐标值
设置坐标值:
chxl=
<坐标轴索引值>:|<坐标值 1>|<坐标值
n>|...
<坐标轴索引值>:|<坐标值 1>|<坐标值
n>
坐标轴索引值
指定后续坐标值应用于哪个坐标轴。所有坐标值由竖线|
分割。
注意:坐标轴索引值必须正序排列。
第一个坐标值将作为坐标轴起点,最后一个坐标值作为终点,中间坐标值平均分布在坐标轴上。
参数 | 说明 | 示例 |
---|---|---|
chxt 和chxl
|
图例中使用了左右 y 轴(y 和r )和两个底部 x 轴(x )。
注意:最后一个坐标值后无需分隔符 |
|
与上例类似,但未设置 y 轴(y )。(未设置1: 值)。
注意:最后一个坐标值后无需分隔符 |
|
坐标值位置
可设置多个坐标轴:
chxp=
<坐标轴索引值>,<坐标值 1 位置>,<坐标值 n
位置>|...
<坐标轴索引值>,<坐标值 1
位置>,<坐标值 n 位置>
多组数据间使用竖线分隔符|
。若未设置chxt
值,则坐标值使用位置值标注。
参数 | 说明 | 示例 |
---|---|---|
chxp |
图例中使用了底部 x 轴,一个左侧 y 轴y 和一个右侧 y 轴r 。
x y 右侧 y |
|
坐标值范围
设置坐标值范围:
chxr=
<坐标轴索引值>,<坐标值起始值>,<坐标值终止值>|
...
<坐标轴索引值>,<坐标值起始值>,<坐标值终止值>
多组数据间使用竖线分隔符|
。
参数 | 说明 | 示例 |
---|---|---|
chxr |
图例中使用了左右 y 轴(y 和r )和底部 x轴( x )。
每个坐标轴均未设置坐标值和分布位置,所以坐标值和分布位置采用坐标值范围设置。 注意:右侧 y |
|
只使用了 x 轴(x ),坐标值、坐标值位置和坐标值范围均设置。 |
|
标注样式
设置坐标值标注样式:
chxs=
<坐标轴索引值>,<颜色>,<字号>,<对齐方式>|
...
<坐标轴索引值>,<颜色>,<字号>,<对齐方式>
其中:
-
坐标轴索引值
为chxt
参数中坐标索引。 -
<颜色>
为十六进制颜色值。 -
<字号>
设置字体大小(像素),可选。 -
<对齐方式>
设置坐标值对齐方式,可选。x 轴默认居中对齐,y 轴默认右对齐,右侧 y
轴默认左对齐。设置0
为居中,-1
为左对齐,1
为右对齐。
多组数据间使用竖线分隔符|
。
参数 | 说明 | 示例 |
---|---|---|
chxs |
为第二个 x 轴设置字号、颜色、对齐方式。 |
|
两个 x 轴均设置字号、颜色、对齐方式。 |
|
样式
可用样式设置:
折线样式
设定参数格式:
chls=
<数据线 1 粗细>,<数据线 1 线段长度>,<数据线 1
线段间隔长度>|...
<数据线 n 粗细>,<数据线 n
线段长度>,<数据线 n 线段间隔长度>
参数为浮点数,使用竖线|
作为数据组分隔符。
参数 | 说明 | 示例 |
---|---|---|
chls |
图例中粗虚线设置为3,6,3 ,细实线设置为1,1,0 。 |
|
网格线
为折线图设定网格线格式:
chg=
<x 轴步长>,
<y
轴步长>,<线段长度>,
<线段间隔长度>,
参数为整数或一位小数数值,例如 10.0 或 10.5 。
参数 | 说明 | 示例 |
---|---|---|
chg |
仅设置步长20,50 ,Chart API 默认显示虚线。 |
|
步长20,50 、线段长度1 、线段间隔均设置5 。 |
|
|
使用实线则设置线段间隔为零(0 )。 |
|
形状标记和区间填充
折线图和散点图有效,使用chm
参数:
形状标记
为折线图和散点图设置形状标记:
chm=
<形状类型>,<颜色>,<数据组索引>,<数据点>,<尺寸>|
...
<形状类型>,<颜色>,<数据组索引>,<数据点>,<尺寸>
其中:
-
<形状类型>
为以下字符:a
代表箭头(Arrow)。c
代表十字(Cross)。d
代表菱形(Diamond)。o
代表圆圈。s
代表正方形(Square)。v
代表
x
轴至该点的垂直线。V
代表穿过该点的垂直线。h
代表穿过该点的水平线。x
代表十叉。 -
<颜色>
为十六进制颜色值。 -
<数据组索引>
指定形状所在数据组,0
为第一组数据,1
为第二组数据,以此类推。 -
<数据点>
为浮点数,指定形状所在数据点,1
为第一个数据,2
为第二个数据,以此类推。小数代表数据点间位置。 -
<尺寸>
设定形状像素大小。
多组数据使用竖线|
作为分隔符。
参数 | 说明 | 示例 |
---|---|---|
chm |
示例中使用了全部形状标记。
最后一个参数 |
|
散点图示例,使用正方形s 。
数据点设置参看散点图。 |
|
|
示例中为两组数据分别使用圆圈与菱形标记。
如果两组数据中指定了相同的数据点,则以第一组数据点形状为准。示例中圆圈覆盖菱形设置。 |
|
区间填充
折线图和散点图有效,使用chm
参数:
chm=
<r 或
R>,<颜色>,<任意值>,<开始值>,<终止值>|...
<r
或 R>,<颜色>,<任意值>,<开始值>,<终止值>
其中:
-
<r 或 R>
中r
代表水平填充,R
代表垂直填充。 -
<颜色>
为十六进制颜色值。 -
<任意值>
未使用,请忽略该值。 -
<开始值>
:- 水平填充中,垂直方向最低端为
0.00
,最顶端为1.00
。 - 垂直填充中,水平方向最左侧为
0.00
,最右侧为1.00
。
- 水平填充中,垂直方向最低端为
-
<终止值>
:- 水平填充中,垂直方向最低端为
0.00
,最顶端为1.00
。 - 垂直填充中,水平方向最左侧为
0.00
,最右侧为1.00
。
- 水平填充中,垂直方向最低端为
多组数据使用竖线|
作为分隔符。
参数 | 说明 | 示例 |
---|---|---|
chm=r |
区域填充可以为颜色带或模拟直线,示例中浅蓝色(E5ECF9 )颜色带和黑色(000000 )直线。 |
|
chm |
垂直示例,红色(FF0000 )直线和蓝色(A0BAE9 )颜色带。 |
|
chm= R...|r...
|
可同时设置水平与垂直填充,后设置的填充将覆盖前边已设置的相同填充区域。示例中先设置的垂直填充,所以水平填充覆盖垂直填充。 |
|
数据区块填充
设定数据区块填充:
chm=
b,<颜色>,<开始折线索引值>,<终止折线索引值>,<任意值>|
...
b,<颜色>,<开始折线索引值>,<终止折线索引值>,<任意值>
其中:
-
<颜色>
为十六进制颜色值。 -
<开始折线索引值>
设定颜色填充起始折线。为chd
参数中数据组索引值,0
为第一组数据,1
为第二组数据,以此类推。 -
<终止折线索引值>
设置颜色填充终止折线。为chd
参数中数据组索引值,0
为第一组数据,1
为第二组数据,以此类推。 -
<任意值>
未使用,请忽略该值。
多组数据使用竖线|
作为分隔符。
参数 | 说明 | 示例 |
---|---|---|
chm=b |
首先指定数据最大值。
填充图表顶部至第一组数据,需指定数据最大值( 填充最后一组数据至图表底部,需指定数据最小值( 数据线颜色根据参数 |
|
删除了上例中第一组和最后一组数据(99 和AA )。
未设置 |
|
|
chm=B |
仅有一组数据时,使用chm=B 可填充数据线以下全部区域。 |
|