此页面由 Cloud Translation API 翻译。

Class EmbeddedChartBuilder

用于修改 EmbeddedChart 的构建器。在对重新构建的图表调用 Sheet.updateChart(chart) 之前，系统不会保存对图表所做的更改。

var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("A1:B8");
var chart = sheet.getCharts()[0];
chart = chart.modify()
    .addRange(range)
    .setOption('title', 'Updated!')
    .setOption('animation.duration', 500)
    .setPosition(2,2,0,0)
    .build();
sheet.updateChart(chart);

方法

方法	返回类型	简介
`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`	将图表类型设置为折线图并返回 `EmbeddedLineChartBuilder`。
`asPieChart()`	`EmbeddedPieChartBuilder`	将图表类型设置为 PieChart 并返回 `EmbeddedPieChartBuilder`。
`asScatterChart()`	`EmbeddedScatterChartBuilder`	将图表类型设置为 ScatterChart 并返回 `EmbeddedScatterChartBuilder`。
`asTableChart()`	`EmbeddedTableChartBuilder`	将图表类型设置为 TableChart 并返回 `EmbeddedTableChartBuilder`。
`build()`	`EmbeddedChart`	构建图表以反映对其所做的所有更改。
`clearRanges()`	`EmbeddedChartBuilder`	从此构建器修改的图表中移除所有范围。
`getChartType()`	`ChartType`	返回当前图表类型。
`getContainer()`	`ContainerInfo`	返回图表 `ContainerInfo`，用于封装图表在工作表中的显示位置。
`getRanges()`	`Range[]`	返回当前为此图表提供数据的范围列表的副本。
`removeRange(range)`	`EmbeddedChartBuilder`	从此构建器修改的图表中移除指定范围。
`setChartType(type)`	`EmbeddedChartBuilder`	更改图表类型。
`setHiddenDimensionStrategy(strategy)`	`EmbeddedChartBuilder`	设置要隐藏的行和列的策略。
`setMergeStrategy(mergeStrategy)`	`EmbeddedChartBuilder`	设置当存在多个范围时使用的合并策略。
`setNumHeaders(headers)`	`EmbeddedChartBuilder`	设置应被视为标题的范围的行数或列数。
`setOption(option, value)`	`EmbeddedChartBuilder`	设置此图表的高级选项。
`setPosition(anchorRowPos, anchorColPos, offsetX, offsetY)`	`EmbeddedChartBuilder`	设置位置，更改图表在工作表中的显示位置。
`setTransposeRowsAndColumns(transpose)`	`EmbeddedChartBuilder`	设置图表的行和列是否处于转置状态。

详细文档

`addRange(range)`

向此构建器修改的图表添加范围。如果已向图表添加范围，则不会添加此范围。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var chart = sheet.newChart()
    .setChartType(Charts.ChartType.BAR)
    .addRange(sheet.getRange("A1:B8"))
    .setPosition(5, 5, 0, 0)
    .build();

sheet.insertChart(chart);

参数

名称	类型	说明
`range`	`Range`	要添加的范围。

EmbeddedChartBuilder - 此构建器，用于链接

`asAreaChart()`

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

EmbeddedAreaChartBuilder - 面积图的构建器

`asBarChart()`

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

EmbeddedBarChartBuilder - 条形图的构建器

`asColumnChart()`

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

EmbeddedColumnChartBuilder - 柱形图的构建器

`asComboChart()`

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

EmbeddedComboChartBuilder - 组合图表的构建器

`asHistogramChart()`

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

EmbeddedHistogramChartBuilder - 直方图图表的构建器

`asLineChart()`

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

EmbeddedLineChartBuilder - 折线图的构建器

`asPieChart()`

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

EmbeddedPieChartBuilder - 饼图的构建器

`asScatterChart()`

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

EmbeddedScatterChartBuilder - 散点图的构建器

`asTableChart()`

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

EmbeddedTableChartBuilder - 表图表的构建器

`build()`

构建图表以反映对其所做的所有更改。

此方法不会自动在电子表格顶部绘制图表。必须通过 sheet.insertChart(chart) 插入新图表，并且应通过 sheet.updateChart(chart) 更新现有图表。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var range = sheet.getRange("A1:B5");
var chart = sheet.newChart()
    .setChartType(Charts.ChartType.BAR)
    .addRange(range)
    .setPosition(5, 5, 0, 0)
    .build();

sheet.insertChart(chart);

EmbeddedChart - 已创建的图表，仍必须添加到电子表格中

`clearRanges()`

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

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

// This code updates the chart to use only the new ranges while preserving the existing
// formatting of the chart.
var chart = sheet.getCharts()[0];
var newChart = chart
    .modify()
    .clearRanges()
    .addRange(sheet.getRange("A1:A5"))
    .addRange(sheet.getRange("B1:B5"))
    .build();
sheet.updateChart(newChart);

EmbeddedChartBuilder - 此构建器，用于链接

`getChartType()`

返回当前图表类型。

ChartType - 图表类型

`getContainer()`

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

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var 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()
var containerInfo = chartBuilder.getContainer();

// Logs the values we 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) 可修改此列表。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var chartBuilder = sheet.newChart()
    .setChartType(Charts.ChartType.BAR)
    .addRange(sheet.getRange("A1:B8"))
    .setPosition(5, 5, 0, 0);

var ranges = chartBuilder.getRanges();

// There's only one range as a data source for this chart,
// so this logs "A1:B8"
for (var i in ranges) {
  var range = ranges[i];
  Logger.log(range.getA1Notation());
}

Range[] - 一系列范围，用作要构建的数据源的图表

`removeRange(range)`

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

移除的范围必须与通过 addRange(range) 添加的范围匹配；否则不会更改图表。此方法不能用于部分移除范围中的值。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var firstRange = sheet.getRange("A1:B5");
var secondRange = sheet.getRange("A6:B8");

var chartBuilder = sheet.newChart()
    .setChartType(Charts.ChartType.BAR)
    .addRange(firstRange)
    // This range will render 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
// will not be removed, and will not throw an exception
chartBuilder.removeRange(firstRange);
chartBuilder.removeRange(sheet.getRange("A6:B8"));

var chart = chartBuilder.build();

sheet.insertChart(chart);

参数

名称	类型	说明
`range`	`Range`	要移除的范围。

EmbeddedChartBuilder - 此构建器，用于链接

`setChartType(type)`

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

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var range = sheet.getRange("A1:B5");
var chart = sheet.newChart()
    .setChartType(Charts.ChartType.BAR)
    .addRange(range)
    .setPosition(5, 5, 0, 0)
    .build();

sheet.insertChart(chart);

参数

名称	类型	说明
`type`	`ChartType`	要更改此图表的类型。

EmbeddedChartBuilder - 此构建器，用于链接

`setHiddenDimensionStrategy(strategy)`

设置要隐藏的行和列的策略。默认值为 IGNORE_ROWS。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var range = sheet.getRange("A1:B5");
var chart = sheet.newChart()
    .setChartType(Charts.ChartType.BAR)
    .addRange(range)
    .setHiddenDimensionStrategy(Charts.ChartHiddenDimensionStrategy.IGNORE_COLUMNS)
    .setPosition(5, 5, 0, 0)
    .build();

sheet.insertChart(chart);

参数

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

EmbeddedChartBuilder - 此构建器，用于链接

`setMergeStrategy(mergeStrategy)`

设置当存在多个范围时使用的合并策略。如果为 MERGE_ROWS，则会合并行；如果为 MERGE_COLUMNS，则会合并列。默认值为 MERGE_COLUMNS。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var range = sheet.getRange("A1:B10");
var range2 = sheet.getRange("C:C10");
var 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);

参数

名称	类型	说明
`mergeStrategy`	`ChartMergeStrategy`	要使用的合并策略。

EmbeddedChartBuilder - 此构建器，用于链接

`setNumHeaders(headers)`

设置相应范围中应被视为标题的行数或列数。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var range = sheet.getRange("A1:B5");
var chart = sheet.newChart()
    .setChartType(Charts.ChartType.BAR)
    .addRange(range)
    .setNumHeaders(1)
    .setPosition(5, 5, 0, 0)
    .build();

sheet.insertChart(chart);

参数

名称	类型	说明
`headers`	`Integer`	要被视为标题的行数或列数。若使用负值，则可自动检测标头。

EmbeddedChartBuilder - 此构建器，用于链接

`setOption(option, value)`

设置此图表的高级选项。如需查看可用选项的列表，请参阅图表配置选项。

此方法既不会验证您指定的选项是否适用于此图表类型，也不会验证值的格式是否正确/结构。

以下示例展示了如何更改标题和设置图例。

builder.setOption('title', 'Earnings projections');
builder.setOption('legend', {position: 'top', textStyle: {color: 'blue', fontSize: 16}});

参数

名称	类型	说明
`option`	`String`	选项的名称。
`value`	`Object`	选项的值。

EmbeddedChartBuilder - 此构建器，用于链接。

`setPosition(anchorRowPos, anchorColPos, offsetX, offsetY)`

设置位置，更改图表在工作表中的显示位置。anchorRowPos 和 anchorColPos 按 1 编入索引。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var range = sheet.getRange("A1:B5");
var chart = sheet.newChart()
    .setChartType(Charts.ChartType.BAR)
    .addRange(range)
    .setPosition(5, 5, 0, 0)
    .build();

sheet.insertChart(chart);

参数

名称	类型	说明
`anchorRowPos`	`Integer`	图表的顶部锚定在这一行中。
`anchorColPos`	`Integer`	图表的左侧锚定在该列。
`offsetX`	`Integer`	图表的右上角会偏移这么多像素。
`offsetY`	`Integer`	图表的左下角偏移了这么多像素。

EmbeddedChartBuilder - 此构建器，用于链接

`setTransposeRowsAndColumns(transpose)`

设置图表的行和列是否处于转置状态。如果设置为 true，则行和列会切换。默认值为 false。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var range = sheet.getRange("A1:B5");
var chart = sheet.newChart()
    .setChartType(Charts.ChartType.BAR)
    .addRange(range)
    .setTransposeRowsAndColumns(true)
    .setPosition(5, 5, 0, 0)
    .build();

sheet.insertChart(chart);

参数

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

EmbeddedChartBuilder - 此构建器，用于链接