表格图表的构建器。如需了解详情,请参阅 Gviz 文档。
方法
详细文档
add Range(range)
向此构建器修改的图表中添加范围。如果范围已添加到图表中,则不会再添加。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const chart = sheet.newChart() .setChartType(Charts.ChartType.BAR) .addRange(sheet.getRange('A1:B8')) .setPosition(5, 5, 0, 0) .build(); sheet.insertChart(chart);
参数
名称 | 类型 | 说明 |
---|---|---|
range | Range | 要添加的范围。 |
返回
Embedded
- 此构建器,用于链式调用。
as Area Chart()
as Bar Chart()
as Column Chart()
as Combo Chart()
as Histogram Chart()
将图表类型设置为 HistogramChart 并返回 Embedded
。
返回
Embedded
- 直方图的构建器。
as Line Chart()
as Pie Chart()
as Scatter Chart()
as Table Chart()
build()
构建图表以反映对其所做的所有更改。
此方法不会自动在电子表格顶部绘制图表。必须通过 sheet.insertChart(chart)
插入新图表,并通过 sheet.updateChart(chart)
更新现有图表。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('A1:B5'); const chart = sheet.newChart() .setChartType(Charts.ChartType.BAR) .addRange(range) .setPosition(5, 5, 0, 0) .build(); sheet.insertChart(chart);
返回
Embedded
- 已创建的图表,但仍需添加到电子表格中。
clear Ranges()
从此构建器修改的图表中移除所有范围。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; // This code updates the chart to use only the new ranges while preserving the // existing formatting of the chart. const chart = sheet.getCharts()[0]; const newChart = chart.modify() .clearRanges() .addRange(sheet.getRange('A1:A5')) .addRange(sheet.getRange('B1:B5')) .build(); sheet.updateChart(newChart);
返回
Embedded
- 此构建器,用于链式调用。
enable Paging(enablePaging)
设置是否启用数据分页。
默认行为是停用分页。如果启用了分页,则默认页面大小为 10。
参数
名称 | 类型 | 说明 |
---|---|---|
enable | Boolean | 如果应启用分页,则为 true ;否则为 false 。 |
返回
Embedded
- 此构建器,适用于链式调用。
enable Paging(pageSize)
启用分页并设置每页的行数。
默认页面大小为 10。
// Creates a table chart builder and enables paging with page size of 5. const builder = Charts.newTableChart(); builder.enablePaging(5);
参数
名称 | 类型 | 说明 |
---|---|---|
page | Integer | 表格中每页的行数。 |
返回
Embedded
- 此构建器,适用于链式调用。
enable Paging(pageSize, startPage)
启用分页,设置每页的行数和要显示的第一页表格(页码从零开始)。
默认页面大小为 10,默认起始页为 0。
// Creates a table chart builder and enables paging with page size of 5 and // displays page 2 first. const builder = Charts.newTableChart(); builder.enablePaging(5, 2);
参数
名称 | 类型 | 说明 |
---|---|---|
page | Integer | 表格中每页的行数。 |
start | Integer | 要显示的第一页表格(页码从 0 开始)。 |
返回
Embedded
- 此构建器,适用于链式调用。
enable Rtl Table(rtlEnabled)
通过反转表格的列顺序,添加对从右到左书写的语言(例如阿拉伯语或希伯来语)的基本支持,使第 0 列成为最右侧的列,最后一列成为最左侧的列。
这不会影响底层数据中的列索引,只会影响显示顺序。 即使使用此选项,表格可视化图表也不支持完整的双向 (BiDi) 语言显示。如果您启用了分页功能(使用 page 选项),或者由于您指定的 height 和 width 选项小于所需的表格大小而导致表格具有滚动条,则系统会忽略此选项。默认行为是停用 RTL 支持。
参数
名称 | 类型 | 说明 |
---|---|---|
rtl | Boolean | 如果应启用从右到左的支持,则为 true ;否则为 false 。 |
返回
Embedded
- 此构建器,适用于链式调用。
enable Sorting(enableSorting)
设置用户点击列标题时是否对列进行排序。
如果启用了排序功能,当用户点击列标题时,系统会自动对行进行排序。默认行为是启用排序。
参数
名称 | 类型 | 说明 |
---|---|---|
enable | Boolean | true 可通过点击列标题启用排序,否则为 false 。 |
返回
Embedded
- 此构建器,适用于链式调用。
get Chart Type()
get Container()
返回图表 Container
,其中封装了图表在工作表中的显示位置。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const chartBuilder = sheet.newChart() .setChartType(Charts.ChartType.BAR) .addRange(sheet.getRange('A1:B8')) .setPosition(5, 5, 0, 0); // This method returns the exact same data as Chart#getContainerInfo() const containerInfo = chartBuilder.getContainer(); // Logs the values used in setPosition() Logger.log( 'Anchor Column: %s\r\nAnchor Row %s\r\nOffset X %s\r\nOffset Y %s', containerInfo.getAnchorColumn(), containerInfo.getAnchorRow(), containerInfo.getOffsetX(), containerInfo.getOffsetY(), );
返回
Container
- 包含图表容器位置的对象。
get Ranges()
返回当前为此图表提供数据的范围列表的副本。使用 add
和 remove
修改此列表。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const chartBuilder = sheet.newChart() .setChartType(Charts.ChartType.BAR) .addRange(sheet.getRange('A1:B8')) .setPosition(5, 5, 0, 0); const ranges = chartBuilder.getRanges(); // There's only one range as a data source for this chart, // so this logs "A1:B8" for (const i in ranges) { const range = ranges[i]; Logger.log(range.getA1Notation()); }
返回
Range[]
- 用作要构建的图表的数据源的范围数组。
remove Range(range)
从相应图表中移除此构建器修改的指定范围。如果范围不在相应图表中,则不会抛出错误。
移除的范围必须与通过 add
添加的范围相匹配;否则,图表不会发生任何变化。此方法不能用于从范围中部分移除值。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const firstRange = sheet.getRange('A1:B5'); const secondRange = sheet.getRange('A6:B8'); const chartBuilder = sheet.newChart() .setChartType(Charts.ChartType.BAR) .addRange(firstRange) // This range renders in a different color .addRange(secondRange) .setPosition(5, 5, 0, 0); // Note that you can use either of these two formats, but the range // MUST match up with a range that was added via addRange(), or it // is not removed, and does not throw an exception chartBuilder.removeRange(firstRange); chartBuilder.removeRange(sheet.getRange('A6:B8')); const chart = chartBuilder.build(); sheet.insertChart(chart);
参数
名称 | 类型 | 说明 |
---|---|---|
range | Range | 要移除的范围。 |
返回
Embedded
- 此构建器,用于链式调用。
set Chart Type(type)
更改图表类型。目前并非所有嵌入式图表类型都受支持。请参阅 Chart
。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('A1:B5'); const chart = sheet.newChart() .setChartType(Charts.ChartType.BAR) .addRange(range) .setPosition(5, 5, 0, 0) .build(); sheet.insertChart(chart);
参数
名称 | 类型 | 说明 |
---|---|---|
type | Chart | 要将此图表更改为的类型。 |
返回
Embedded
- 此构建器,用于链式调用。
set First Row Number(number)
设置数据表格中第一行的行号。
第一行的默认行号为 1。
// Creates a table chart builder and sets the first row to be 2. const builder = Charts.newTableChart(); builder.setFirstRowNumber(2);
参数
名称 | 类型 | 说明 |
---|---|---|
number | Integer | 数据表中第一行的行号。 |
返回
Embedded
- 此构建器,适用于链式调用。
set Hidden Dimension Strategy(strategy)
设置用于隐藏行和列的策略。默认值为 IGNORE_ROWS
。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('A1:B5'); const chart = sheet.newChart() .setChartType(Charts.ChartType.BAR) .addRange(range) .setHiddenDimensionStrategy( Charts.ChartHiddenDimensionStrategy.IGNORE_COLUMNS, ) .setPosition(5, 5, 0, 0) .build(); sheet.insertChart(chart);
参数
名称 | 类型 | 说明 |
---|---|---|
strategy | Chart | 用于隐藏行和列的策略。 |
返回
Embedded
- 此构建器,用于链式调用。
set Initial Sorting Ascending(column)
设置应根据哪个列(升序)对表格进行初始排序的列的索引。
相应列按升序排序,并带有小箭头标记,表示这一点。
// Creates a table chart builder and sorts it by the second column (ascending). const builder = Charts.newTableChart(); builder.setInitialSortingAscending(2);
参数
名称 | 类型 | 说明 |
---|---|---|
column | Integer | 应根据哪个列号对表格进行初始排序。 |
返回
Embedded
- 此构建器,适用于链式调用。
set Initial Sorting Descending(column)
设置应根据哪个列(降序)对表格进行初始排序的列的索引。
相应列按降序排序,并带有小箭头标记,表示这一点。
// Creates a table chart builder and sorts it by the second column (descending). const builder = Charts.newTableChart(); builder.setInitialSortingDescending(2);
参数
名称 | 类型 | 说明 |
---|---|---|
column | Integer | 应根据哪个列号对表格进行初始排序。 |
返回
Embedded
- 此构建器,适用于链式调用。
set Merge Strategy(mergeStrategy)
设置存在多个范围时要使用的合并策略。如果值为 MERGE_ROWS
,则合并行;如果值为 MERGE_COLUMNS
,则合并列。默认值为 MERGE_COLUMNS
。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('A1:B10'); const range2 = sheet.getRange('C:C10'); const chart = sheet.newChart() .setChartType(Charts.ChartType.BAR) .addRange(range) .addRange(range2) .setMergeStrategy(Charts.ChartMergeStrategy.MERGE_ROWS) .setPosition(5, 5, 0, 0) .build(); sheet.insertChart(chart);
参数
名称 | 类型 | 说明 |
---|---|---|
merge | Chart | 要使用的合并策略。 |
返回
Embedded
- 此构建器,用于链式调用。
set Num Headers(headers)
设置应被视为标题的范围的行数或列数。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('A1:B5'); const chart = sheet.newChart() .setChartType(Charts.ChartType.BAR) .addRange(range) .setNumHeaders(1) .setPosition(5, 5, 0, 0) .build(); sheet.insertChart(chart);
参数
名称 | 类型 | 说明 |
---|---|---|
headers | Integer | 要视为标题的行数或列数。负值会导致系统自动检测标头。 |
返回
Embedded
- 此构建器,用于链式调用。
set Option(option, value)
设置相应图表的高级选项。如需查看可用选项的列表,请参阅图表配置选项。
此方法不会验证您指定的选项是否对此图表类型有效,也不会验证值是否采用正确的格式/结构。
此示例展示了如何更改图表标题和设置图例。
const spreadsheet = SpreadsheetApp.getActiveSpreadsheet(); const sheet = spreadsheet.getSheets()[0]; const chart = sheet.newChart() .setOption('title', 'Earnings projections') .setOption('legend', { position: 'top', textStyle: { color: 'blue', fontSize: 16 }, }).build();
参数
名称 | 类型 | 说明 |
---|---|---|
option | String | 选项的名称。 |
value | Object | 选项的值。 |
返回
Embedded
- 此构建器,用于链式调用。
set Position(anchorRowPos, anchorColPos, offsetX, offsetY)
设置位置,更改图表在工作表中的显示位置。anchor
和 anchor
是从 1 开始的索引。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('A1:B5'); const chart = sheet.newChart() .setChartType(Charts.ChartType.BAR) .addRange(range) .setPosition(5, 5, 0, 0) .build(); sheet.insertChart(chart);
参数
名称 | 类型 | 说明 |
---|---|---|
anchor | Integer | 图表的顶部固定在此行中。 |
anchor | Integer | 图表的左侧固定在此列中。 |
offsetX | Integer | 图表的右上角偏移的像素数。 |
offsetY | Integer | 图表的左下角偏移的像素数。 |
返回
Embedded
- 此构建器,用于链式调用。
set Transpose Rows And Columns(transpose)
设置图表的行和列是否转置。如果设置为 true
,则会切换行和列。默认值为 false
。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('A1:B5'); const chart = sheet.newChart() .setChartType(Charts.ChartType.BAR) .addRange(range) .setTransposeRowsAndColumns(true) .setPosition(5, 5, 0, 0) .build(); sheet.insertChart(chart);
参数
名称 | 类型 | 说明 |
---|---|---|
transpose | Boolean | 如果值为 true ,则用于构建图表的行和列会进行转置。 |
返回
Embedded
- 此构建器,用于链式调用。
show Row Number Column(showRowNumber)
设置是否将行号显示为表格的第一列。
默认行为是不显示行号。
参数
名称 | 类型 | 说明 |
---|---|---|
show | Boolean | 如果表格的第一列应显示行号,则为 true ;否则为 false 。 |
返回
Embedded
- 此构建器,适用于链式调用。
use Alternating Row Style(alternate)
设置是否为表格图表的奇数行和偶数行分配交替颜色样式。
默认行为是行具有交替颜色样式。
参数
名称 | 类型 | 说明 |
---|---|---|
alternate | Boolean | 如果颜色样式应交替显示,则为 true ,否则为 false 。 |
返回
Embedded
- 此构建器,适用于链式调用。