Class EmbeddedTableChartBuilder

嵌入式表格图表构建器

表格图表的构建器。如需了解详情，请参阅 Gviz 文档。

方法

方法返回类型简介
addRange(range)EmbeddedChartBuilder向此构建器修改的图表中添加范围。
asAreaChart()EmbeddedAreaChartBuilder将图表类型设置为 AreaChart 并返回 EmbeddedAreaChartBuilder。
asBarChart()EmbeddedBarChartBuilder将图表类型设置为 BarChart 并返回 EmbeddedBarChartBuilder。
asColumnChart()EmbeddedColumnChartBuilder将图表类型设置为 ColumnChart 并返回 EmbeddedColumnChartBuilder。
asComboChart()EmbeddedComboChartBuilder将图表类型设置为 ComboChart 并返回 EmbeddedComboChartBuilder。
asHistogramChart()EmbeddedHistogramChartBuilder将图表类型设置为 HistogramChart 并返回 EmbeddedHistogramChartBuilder。
asLineChart()EmbeddedLineChartBuilder将图表类型设置为 LineChart 并返回 EmbeddedLineChartBuilder。
asPieChart()EmbeddedPieChartBuilder将图表类型设置为 PieChart 并返回 EmbeddedPieChartBuilder。
asScatterChart()EmbeddedScatterChartBuilder将图表类型设置为 ScatterChart 并返回 EmbeddedScatterChartBuilder。
asTableChart()EmbeddedTableChartBuilder将图表类型设置为 TableChart 并返回 EmbeddedTableChartBuilder。
build()EmbeddedChart构建图表以反映对其所做的所有更改。
clearRanges()EmbeddedChartBuilder从此构建器修改的图表中移除所有范围。
enablePaging(enablePaging)EmbeddedTableChartBuilder设置是否启用数据分页。
enablePaging(pageSize)EmbeddedTableChartBuilder启用分页并设置每页的行数。
enablePaging(pageSize, startPage)EmbeddedTableChartBuilder启用分页，设置每页的行数和要显示的第一页表格（页码从零开始）。
enableRtlTable(rtlEnabled)EmbeddedTableChartBuilder通过反转表格的列顺序，添加对从右到左书写的语言（例如阿拉伯语或希伯来语）的基本支持，使第 0 列成为最右侧的列，最后一列成为最左侧的列。
enableSorting(enableSorting)EmbeddedTableChartBuilder设置是否在用户点击列标题时对列进行排序。
getChartType()ChartType返回当前图表类型。
getContainer()ContainerInfo返回图表 ContainerInfo，其中封装了图表在工作表中的显示位置。
getRanges()Range[]返回当前为此图表提供数据的范围列表的副本。
removeRange(range)EmbeddedChartBuilder从相应构建器修改的图表中移除指定范围。
setChartType(type)EmbeddedChartBuilder更改图表类型。
setFirstRowNumber(number)EmbeddedTableChartBuilder设置数据表格中第一行的行号。
setHiddenDimensionStrategy(strategy)EmbeddedChartBuilder设置用于隐藏行和列的策略。
setInitialSortingAscending(column)EmbeddedTableChartBuilder设置应根据哪个列（升序）对表格进行初始排序。
setInitialSortingDescending(column)EmbeddedTableChartBuilder设置应根据哪个列（降序）对表格进行初始排序。
setMergeStrategy(mergeStrategy)EmbeddedChartBuilder设置存在多个范围时要使用的合并策略。
setNumHeaders(headers)EmbeddedChartBuilder设置应被视为标题的范围的行数或列数。
setOption(option, value)EmbeddedChartBuilder设置相应图表的高级选项。
setPosition(anchorRowPos, anchorColPos, offsetX, offsetY)EmbeddedChartBuilder设置位置，更改图表在工作表中的显示位置。
setTransposeRowsAndColumns(transpose)EmbeddedChartBuilder设置图表的行和列是否转置。
showRowNumberColumn(showRowNumber)EmbeddedTableChartBuilder设置是否将行号显示为表格的第一列。
useAlternatingRowStyle(alternate)EmbeddedTableChartBuilder设置是否为表格图表的奇数行和偶数行分配交替颜色样式。

详细文档

addRange(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);

参数

名称类型说明
rangeRange要添加的范围。

返回

EmbeddedChartBuilder - 此构建器，用于链式调用。

asAreaChart()

将图表类型设置为 AreaChart 并返回 EmbeddedAreaChartBuilder。

返回

EmbeddedAreaChartBuilder - 面积图的构建器。

asBarChart()

将图表类型设置为 BarChart 并返回 EmbeddedBarChartBuilder。

返回

EmbeddedBarChartBuilder - 条形图的构建器。

asColumnChart()

将图表类型设置为 ColumnChart 并返回 EmbeddedColumnChartBuilder。

返回

EmbeddedColumnChartBuilder - 柱形图的构建器。

asComboChart()

将图表类型设置为 ComboChart 并返回 EmbeddedComboChartBuilder。

返回

EmbeddedComboChartBuilder - 组合图表的构建器。

asHistogramChart()

将图表类型设置为 HistogramChart 并返回 EmbeddedHistogramChartBuilder。

返回

EmbeddedHistogramChartBuilder - 直方图的构建器。

asLineChart()

将图表类型设置为 LineChart 并返回 EmbeddedLineChartBuilder。

返回

EmbeddedLineChartBuilder - 折线图的构建器。

asPieChart()

将图表类型设置为 PieChart 并返回 EmbeddedPieChartBuilder。

返回

EmbeddedPieChartBuilder - 饼图的构建器。

asScatterChart()

将图表类型设置为 ScatterChart 并返回 EmbeddedScatterChartBuilder。

返回

EmbeddedScatterChartBuilder - 散点图的构建器。

asTableChart()

将图表类型设置为 TableChart 并返回 EmbeddedTableChartBuilder。

返回

EmbeddedTableChartBuilder - 表格图表的构建器。

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);

返回

EmbeddedChart - 已创建的图表，但仍需添加到电子表格中。

clearRanges()

从此构建器修改的图表中移除所有范围。 

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);

返回

EmbeddedChartBuilder - 此构建器，用于链式调用。

enablePaging(enablePaging)

设置是否启用数据分页。

默认行为是停用分页。如果启用了分页，则默认页面大小为 10。

参数

名称类型说明
enablePagingBoolean如果应启用分页，则为 true；否则为 false。

返回

EmbeddedTableChartBuilder - 此构建器，适用于链式调用。

enablePaging(pageSize)

启用分页并设置每页的行数。

默认页面大小为 10。 

// Creates a table chart builder and enables paging with page size of 5.
const builder = Charts.newTableChart();
builder.enablePaging(5);

参数

名称类型说明
pageSizeInteger表格中每页的行数。

返回

EmbeddedTableChartBuilder - 此构建器，适用于链式调用。

enablePaging(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);

参数

名称类型说明
pageSizeInteger表格中每页的行数。
startPageInteger要显示的第一页表格（页码从 0 开始）。

返回

EmbeddedTableChartBuilder - 此构建器，适用于链式调用。

enableRtlTable(rtlEnabled)

通过反转表格的列顺序，添加对从右到左书写的语言（例如阿拉伯语或希伯来语）的基本支持，使第 0 列成为最右侧的列，最后一列成为最左侧的列。

这不会影响底层数据中的列索引，只会影响显示顺序。 即使使用此选项，表格可视化图表也不支持完整的双向 (BiDi) 语言显示。如果您启用了分页功能（使用 page 选项），或者由于您指定的 height 和 width 选项小于所需的表格大小而导致表格具有滚动条，则系统会忽略此选项。默认行为是停用 RTL 支持。

参数

名称类型说明
rtlEnabledBoolean如果应启用从右到左的支持，则为 true；否则为 false。

返回

EmbeddedTableChartBuilder - 此构建器，适用于链式调用。

enableSorting(enableSorting)

设置用户点击列标题时是否对列进行排序。

如果启用了排序功能，当用户点击列标题时，系统会自动对行进行排序。默认行为是启用排序。

参数

名称类型说明
enableSortingBooleantrue 可通过点击列标题启用排序，否则为 false。

返回

EmbeddedTableChartBuilder - 此构建器，适用于链式调用。

getChartType()

返回当前图表类型。

返回

ChartType - 图表类型。

getContainer()

返回图表 ContainerInfo，其中封装了图表在工作表中的显示位置。 

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(),
);

返回

ContainerInfo - 包含图表容器位置的对象。

getRanges()

返回当前为此图表提供数据的范围列表的副本。使用 addRange(range) 和 removeRange(range) 修改此列表。 

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[] - 用作要构建的图表的数据源的范围数组。

removeRange(range)

从相应图表中移除此构建器修改的指定范围。如果范围不在相应图表中，则不会抛出错误。

移除的范围必须与通过 addRange(range) 添加的范围相匹配；否则，图表不会发生任何变化。此方法不能用于从范围中部分移除值。 

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);

参数

名称类型说明
rangeRange要移除的范围。

返回

EmbeddedChartBuilder - 此构建器，用于链式调用。

setChartType(type)

更改图表类型。目前并非所有嵌入式图表类型都受支持。请参阅 ChartType。 

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);

参数

名称类型说明
typeChartType要将此图表更改为的类型。

返回

EmbeddedChartBuilder - 此构建器，用于链式调用。

setFirstRowNumber(number)

设置数据表格中第一行的行号。

第一行的默认行号为 1。 

// Creates a table chart builder and sets the first row to be 2.
const builder = Charts.newTableChart();
builder.setFirstRowNumber(2);

参数

名称类型说明
numberInteger数据表中第一行的行号。

返回

EmbeddedTableChartBuilder - 此构建器，适用于链式调用。

setHiddenDimensionStrategy(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);

参数

名称类型说明
strategyChartHiddenDimensionStrategy用于隐藏行和列的策略。

返回

EmbeddedChartBuilder - 此构建器，用于链式调用。

setInitialSortingAscending(column)

设置应根据哪个列（升序）对表格进行初始排序的列的索引。

相应列按升序排序，并带有小箭头标记，表示这一点。 

// Creates a table chart builder and sorts it by the second column (ascending).
const builder = Charts.newTableChart();
builder.setInitialSortingAscending(2);

参数

名称类型说明
columnInteger应根据哪个列号对表格进行初始排序。

返回

EmbeddedTableChartBuilder - 此构建器，适用于链式调用。

setInitialSortingDescending(column)

设置应根据哪个列（降序）对表格进行初始排序的列的索引。

相应列按降序排序，并带有小箭头标记，表示这一点。 

// Creates a table chart builder and sorts it by the second column (descending).
const builder = Charts.newTableChart();
builder.setInitialSortingDescending(2);

参数

名称类型说明
columnInteger应根据哪个列号对表格进行初始排序。

返回

EmbeddedTableChartBuilder - 此构建器，适用于链式调用。

setMergeStrategy(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);

参数

名称类型说明
mergeStrategyChartMergeStrategy要使用的合并策略。

返回

EmbeddedChartBuilder - 此构建器，用于链式调用。

setNumHeaders(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);

参数

名称类型说明
headersInteger要视为标题的行数或列数。负值会导致系统自动检测标头。

返回

EmbeddedChartBuilder - 此构建器，用于链式调用。

setOption(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();

参数

名称类型说明
optionString选项的名称。
valueObject选项的值。

返回

EmbeddedChartBuilder - 此构建器，用于链式调用。

setPosition(anchorRowPos, anchorColPos, offsetX, offsetY)

设置位置，更改图表在工作表中的显示位置。anchorRowPos 和 anchorColPos 是从 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);

参数

名称类型说明
anchorRowPosInteger图表的顶部固定在此行中。
anchorColPosInteger图表的左侧固定在此列中。
offsetXInteger图表的右上角偏移的像素数。
offsetYInteger图表的左下角偏移的像素数。

返回

EmbeddedChartBuilder - 此构建器，用于链式调用。

setTransposeRowsAndColumns(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);

参数

名称类型说明
transposeBoolean如果值为 true，则用于构建图表的行和列会进行转置。

返回

EmbeddedChartBuilder - 此构建器，用于链式调用。

showRowNumberColumn(showRowNumber)

设置是否将行号显示为表格的第一列。

默认行为是不显示行号。

参数

名称类型说明
showRowNumberBoolean如果表格的第一列应显示行号，则为 true；否则为 false。

返回

EmbeddedTableChartBuilder - 此构建器，适用于链式调用。

useAlternatingRowStyle(alternate)

设置是否为表格图表的奇数行和偶数行分配交替颜色样式。

默认行为是行具有交替颜色样式。

参数

名称类型说明
alternateBoolean如果颜色样式应交替显示，则为 true，否则为 false。

返回

EmbeddedTableChartBuilder - 此构建器，适用于链式调用。