Class EmbeddedChartBuilder

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将图表类型设置为区域图表并返回 EmbeddedAreaChartBuilder。
asBarChart()EmbeddedBarChartBuilder将图表类型设置为条形图，并返回 EmbeddedBarChartBuilder。
asColumnChart()EmbeddedColumnChartBuilder将图表类型设置为 ColumnChart 并返回 EmbeddedColumnChartBuilder。
asComboChart()EmbeddedComboChartBuilder将图表类型设置为 ComboChart 并返回 EmbeddedComboChartBuilder。
asHistogramChart()EmbeddedHistogramChartBuilder将图表类型设置为直方图并返回 EmbeddedHistogramChartBuilder。
asLineChart()EmbeddedLineChartBuilder将图表类型设置为“折线图”并返回 EmbeddedLineChartBuilder。
asPieChart()EmbeddedPieChartBuilder将图表类型设置为 PieChart 并返回 EmbeddedPieChartBuilder。
asScatterChart()EmbeddedScatterChartBuilder将图表类型设置为散点图并返回 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);

参数

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

返回

EmbeddedChartBuilder - 此构建器，用于链接

asAreaChart()

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

返回

EmbeddedAreaChartBuilder - 面积图的构建器

asBarChart()

将图表类型设置为条形图，并返回 EmbeddedBarChartBuilder。

返回

EmbeddedBarChartBuilder - 用于条形图的构建器

asColumnChart()

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

返回

EmbeddedColumnChartBuilder - 用于柱形图的构建器

asComboChart()

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

返回

EmbeddedComboChartBuilder - 组合图表的构建器

asHistogramChart()

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

返回

EmbeddedHistogramChartBuilder - 用于直方图的构建器

asLineChart()

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

返回

EmbeddedLineChartBuilder - 折线图构建器

asPieChart()

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

返回

EmbeddedPieChartBuilder - 饼图构建器

asScatterChart()

将图表类型设置为散点图并返回 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);

参数

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

返回

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

参数

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

返回

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

参数

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

返回

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

参数

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

返回

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

参数

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

返回

EmbeddedChartBuilder - 此构建器，用于链接

setOption(option, value)

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

此方法不会验证您指定的选项对此图表类型有效，也不会验证 值的格式/结构正确。

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

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

参数

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

返回

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

参数

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

返回

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

参数

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

返回

EmbeddedChartBuilder - 此构建器，用于链接