Class EmbeddedChartBuilder

EmbeddedChartBuilder

Builder usado para editar um EmbeddedChart. As mudanças feitas no gráfico não são salvas até que Sheet.updateChart(chart) seja chamado no gráfico reconstruído. 

const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('A1:B8');
let 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);

Métodos

MétodoTipo de retornoBreve descrição
addRange(range)EmbeddedChartBuilderAdiciona um intervalo ao gráfico que este builder modifica.
asAreaChart()EmbeddedAreaChartBuilderDefine o tipo de gráfico como AreaChart e retorna um EmbeddedAreaChartBuilder.
asBarChart()EmbeddedBarChartBuilderDefine o tipo de gráfico como BarChart e retorna um EmbeddedBarChartBuilder.
asColumnChart()EmbeddedColumnChartBuilderDefine o tipo de gráfico como "ColumnChart" e retorna um EmbeddedColumnChartBuilder.
asComboChart()EmbeddedComboChartBuilderDefine o tipo de gráfico como "ComboChart" e retorna um EmbeddedComboChartBuilder.
asHistogramChart()EmbeddedHistogramChartBuilderDefine o tipo de gráfico como HistogramChart e retorna um EmbeddedHistogramChartBuilder.
asLineChart()EmbeddedLineChartBuilderDefine o tipo de gráfico como LineChart e retorna um EmbeddedLineChartBuilder.
asPieChart()EmbeddedPieChartBuilderDefine o tipo de gráfico como PieChart e retorna um EmbeddedPieChartBuilder.
asScatterChart()EmbeddedScatterChartBuilderDefine o tipo de gráfico como "ScatterChart" e retorna um EmbeddedScatterChartBuilder.
asTableChart()EmbeddedTableChartBuilderDefine o tipo de gráfico como TableChart e retorna um EmbeddedTableChartBuilder.
build()EmbeddedChartCria o gráfico para refletir todas as mudanças feitas nele.
clearRanges()EmbeddedChartBuilderRemove todos os intervalos do gráfico que este builder modifica.
getChartType()ChartTypeRetorna o tipo de gráfico atual.
getContainer()ContainerInfoRetorna o gráfico ContainerInfo, que encapsula onde ele aparece na planilha.
getRanges()Range[]Retorna uma cópia da lista de intervalos que fornecem dados para este gráfico.
removeRange(range)EmbeddedChartBuilderRemove o intervalo especificado do gráfico que este builder modifica.
setChartType(type)EmbeddedChartBuilderMuda o tipo de gráfico.
setHiddenDimensionStrategy(strategy)EmbeddedChartBuilderDefine a estratégia a ser usada para linhas e colunas ocultas.
setMergeStrategy(mergeStrategy)EmbeddedChartBuilderDefine a estratégia de mesclagem a ser usada quando há mais de um intervalo.
setNumHeaders(headers)EmbeddedChartBuilderDefine o número de linhas ou colunas do intervalo que devem ser tratados como cabeçalhos.
setOption(option, value)EmbeddedChartBuilderDefine opções avançadas para este gráfico.
setPosition(anchorRowPos, anchorColPos, offsetX, offsetY)EmbeddedChartBuilderDefine a posição, mudando onde o gráfico aparece na planilha.
setTransposeRowsAndColumns(transpose)EmbeddedChartBuilderDefine se as linhas e colunas do gráfico são transpostas.

Documentação detalhada

addRange(range)

Adiciona um intervalo ao gráfico que este builder modifica. Não adiciona o intervalo se ele já tiver sido adicionado ao gráfico. 

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

Parâmetros

NomeTipoDescrição
rangeRangeO intervalo a ser adicionado.

Retornar

EmbeddedChartBuilder: este builder, para encadeamento.

asAreaChart()

Define o tipo de gráfico como AreaChart e retorna um EmbeddedAreaChartBuilder.

Retornar

EmbeddedAreaChartBuilder: um builder para um gráfico de área.

asBarChart()

Define o tipo de gráfico como BarChart e retorna um EmbeddedBarChartBuilder.

Retornar

EmbeddedBarChartBuilder: um criador de gráficos de barras.

asColumnChart()

Define o tipo de gráfico como "ColumnChart" e retorna um EmbeddedColumnChartBuilder.

Retornar

EmbeddedColumnChartBuilder: um builder para um gráfico de colunas.

asComboChart()

Define o tipo de gráfico como "ComboChart" e retorna um EmbeddedComboChartBuilder.

Retornar

EmbeddedComboChartBuilder: um builder para um gráfico de combinação.

asHistogramChart()

Define o tipo de gráfico como HistogramChart e retorna um EmbeddedHistogramChartBuilder.

Retornar

EmbeddedHistogramChartBuilder: um criador de gráfico de histograma.

asLineChart()

Define o tipo de gráfico como LineChart e retorna um EmbeddedLineChartBuilder.

Retornar

EmbeddedLineChartBuilder: um criador de gráficos de linhas.

asPieChart()

Define o tipo de gráfico como PieChart e retorna um EmbeddedPieChartBuilder.

Retornar

EmbeddedPieChartBuilder: um builder para um gráfico de pizza.

asScatterChart()

Define o tipo de gráfico como "ScatterChart" e retorna um EmbeddedScatterChartBuilder.

Retornar

EmbeddedScatterChartBuilder: um builder para um gráfico de dispersão.

asTableChart()

Define o tipo de gráfico como TableChart e retorna um EmbeddedTableChartBuilder.

Retornar

EmbeddedTableChartBuilder: um criador de gráficos de tabela.

build()

Cria o gráfico para refletir todas as mudanças feitas nele.

Esse método não desenha automaticamente o gráfico na parte de cima da planilha. Um novo gráfico precisa ser inserido usando sheet.insertChart(chart), e um gráfico existente precisa ser atualizado usando 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);

Retornar

EmbeddedChart: o gráfico criado, que ainda precisa ser adicionado à planilha.

clearRanges()

Remove todos os intervalos do gráfico que este builder modifica. 

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

Retornar

EmbeddedChartBuilder: este builder, para encadeamento.

getChartType()

Retorna o tipo de gráfico atual.

Retornar

ChartType: o tipo de gráfico.

getContainer()

Retorna o gráfico ContainerInfo, que encapsula onde ele aparece na planilha. 

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

Retornar

ContainerInfo: um objeto que contém a posição do contêiner do gráfico.

getRanges()

Retorna uma cópia da lista de intervalos que fornecem dados para este gráfico. Use addRange(range) e removeRange(range) para modificar essa lista. 

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

Retornar

Range[]: uma matriz de intervalos que servem como fonte de dados do gráfico a ser criado.

removeRange(range)

Remove o intervalo especificado do gráfico que este builder modifica. Não gera um erro se o intervalo não estiver no gráfico.

O intervalo removido precisa corresponder a um intervalo adicionado via addRange(range). Caso contrário, nenhuma mudança será feita no gráfico. Esse método não pode ser usado para remover parcialmente valores de um intervalo. 

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

Parâmetros

NomeTipoDescrição
rangeRangeO intervalo a ser removido.

Retornar

EmbeddedChartBuilder: este builder, para encadeamento.

setChartType(type)

Muda o tipo de gráfico. No momento, nem todos os tipos de gráficos incorporados são compatíveis. Consulte 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);

Parâmetros

NomeTipoDescrição
typeChartTypeO tipo para mudar este gráfico.

Retornar

EmbeddedChartBuilder: este builder, para encadeamento.

setHiddenDimensionStrategy(strategy)

Define a estratégia a ser usada para linhas e colunas ocultas. O valor padrão é 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);

Parâmetros

NomeTipoDescrição
strategyChartHiddenDimensionStrategyA estratégia a ser usada para linhas e colunas ocultas.

Retornar

EmbeddedChartBuilder: este builder, para encadeamento.

setMergeStrategy(mergeStrategy)

Define a estratégia de mesclagem a ser usada quando há mais de um intervalo. Se MERGE_ROWS, as linhas serão mescladas. Se MERGE_COLUMNS, as colunas serão mescladas. O valor padrão é 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);

Parâmetros

NomeTipoDescrição
mergeStrategyChartMergeStrategyA estratégia de fusão a ser usada.

Retornar

EmbeddedChartBuilder: este builder, para encadeamento.

setNumHeaders(headers)

Define o número de linhas ou colunas do intervalo que devem ser tratados como cabeçalhos. 

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

Parâmetros

NomeTipoDescrição
headersIntegerO número de linhas ou colunas a serem tratadas como cabeçalhos. Valores negativos fazem com que os cabeçalhos sejam detectados automaticamente.

Retornar

EmbeddedChartBuilder: este builder, para encadeamento.

setOption(option, value)

Define opções avançadas para este gráfico. Para conferir uma lista das opções disponíveis, consulte Opções de configuração de gráficos.

Esse método não valida se a opção especificada é válida para esse tipo de gráfico nem se o valor está no formato/estrutura correto.

Este exemplo mostra como mudar o título e definir uma legenda. 

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

Parâmetros

NomeTipoDescrição
optionStringO nome da opção.
valueObjectO valor da opção.

Retornar

EmbeddedChartBuilder: este builder, para encadeamento.

setPosition(anchorRowPos, anchorColPos, offsetX, offsetY)

Define a posição, mudando onde o gráfico aparece na planilha. anchorRowPos e anchorColPos são indexados em 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);

Parâmetros

NomeTipoDescrição
anchorRowPosIntegerA parte superior do gráfico fica ancorada nessa linha.
anchorColPosIntegerO lado esquerdo do gráfico está fixado nessa coluna.
offsetXIntegerO canto superior direito do gráfico é deslocado por essa quantidade de pixels.
offsetYIntegerO canto inferior esquerdo do gráfico é deslocado por esse número de pixels.

Retornar

EmbeddedChartBuilder: este builder, para encadeamento.

setTransposeRowsAndColumns(transpose)

Define se as linhas e colunas do gráfico são transpostas. Se definido como true, as linhas e colunas serão trocadas. O padrão é 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);

Parâmetros

NomeTipoDescrição
transposeBooleanSe true, as linhas e colunas usadas para construir o gráfico serão transpostas.

Retornar

EmbeddedChartBuilder: este builder, para encadeamento.