Class SpreadsheetApp

Cria uma nova planilha com o nome fornecido.

// The code below creates a new spreadsheet "Finances" and logs the URL for it
var ssNew = SpreadsheetApp.create("Finances");
Logger.log(ssNew.getUrl());

Parâmetros

Retornar

Spreadsheet: uma nova planilha.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

• https://www.googleapis.com/auth/spreadsheets

Cria uma nova planilha com o nome fornecido e o número especificado de linhas e colunas.

// The code below creates a new spreadsheet "Finances" with 50 rows and 5 columns and logs the
// URL for it
var ssNew = SpreadsheetApp.create("Finances", 50, 5);
Logger.log(ssNew.getUrl());

Parâmetros

Retornar

Spreadsheet: uma nova planilha.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

• https://www.googleapis.com/auth/spreadsheets

Ativa a execução de dados para todos os tipos de fontes de dados.

A execução de dados gera uma exceção se o tipo de fonte de dados não estiver ativado. Use esse método para ativar a execução de dados para todos os tipos de fonte de dados.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

• https://www.googleapis.com/auth/bigquery.readonly

Ativa a execução de dados para a fonte de dados do BigQuery.

A execução de dados da fonte de dados do BigQuery gera uma exceção se não for ativada.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

• https://www.googleapis.com/auth/bigquery.readonly

Aplica todas as alterações pendentes à planilha.

Às vezes, as operações da planilha são agrupadas para melhorar o desempenho, como ao fazer várias chamadas para Range.getValue(). No entanto, às vezes, é recomendável garantir que todas as alterações pendentes sejam feitas imediatamente, por exemplo, para mostrar os dados dos usuários durante a execução de um script.

// The code below changes the background color of cells A1 and B1 twenty times. You should be
// able to see the updates live in the spreadsheet. If flush() is not called, the updates may
// be applied live or may all be applied at once when the script completes.
function colors() {
  var sheet = SpreadsheetApp.getActiveSheet();
  for (var i = 0; i < 20; i++) {
    if ((i % 2) == 0) {
      sheet.getRange('A1').setBackground('green');
      sheet.getRange('B1').setBackground('red');
    } else {
      sheet.getRange('A1').setBackground('red');
      sheet.getRange('B1').setBackground('green');
    }
    SpreadsheetApp.flush();
  }
}

Retorna a planilha ativa no momento ou null se não houver nenhuma.

As funções que são executadas no contexto de uma planilha podem conseguir uma referência ao objeto da planilha correspondente chamando essa função.

// The code below logs the URL for the active spreadsheet.
Logger.log(SpreadsheetApp.getActive().getUrl());

Retornar

Spreadsheet: o objeto ativo da planilha.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

Retorna o intervalo selecionado na página ativa ou null se não houver um intervalo ativo. Se vários intervalos forem selecionados, esse método retornará apenas o último intervalo selecionado.

Isso geralmente significa o intervalo que um usuário selecionou na página ativa, mas em uma função personalizada ele se refere à célula sendo recalculada ativamente.

// The code below logs the background color for the active range.
var colorObject = SpreadsheetApp.getActiveRange().getBackgroundObject();
// Assume the color has ColorType.RGB.
Logger.log(colorObject.asRgbColor().asHexString());

Retornar

Range: o intervalo ativo.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

Retorna a lista de intervalos ativos na página ativa ou null se não houver intervalos selecionados. O intervalo ativo que contém a célula destacada está na última lista.

Se houver um único intervalo selecionado, ele se comportará como uma chamada getActiveRange().

// Returns the list of active ranges.
var rangeList = SpreadsheetApp.getActiveRangeList();

Retornar

RangeList: a lista de intervalos ativos

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

Recebe a planilha ativa em uma planilha.

A planilha ativa em uma planilha é a página que está sendo exibida na IU da planilha.

// The code below logs the name of the active sheet.
Logger.log(SpreadsheetApp.getActiveSheet().getName());

Retornar

Sheet: o objeto ativo da planilha.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

Retorna a planilha ativa no momento ou null se não houver nenhuma.

As funções que são executadas no contexto de uma planilha podem conseguir uma referência ao objeto Spreadsheet correspondente chamando essa função.

// The code below logs the URL for the active spreadsheet.
Logger.log(SpreadsheetApp.getActiveSpreadsheet().getUrl());

Retornar

Spreadsheet: o objeto ativo da planilha.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

Retorna a célula atual (em destaque) selecionada em um dos intervalos ativos na página ativa ou em null, se não houver uma célula atual.

// Returns the current highlighted cell in the one of the active ranges.
var currentCell = SpreadsheetApp.getCurrentCell();

Retornar

Range: a célula atual.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

Retorna o Selection atual na planilha.

var selection = SpreadsheetApp.getSelection();
var currentCell = selection.getCurrentCell();

Retornar

Selection: a seleção atual

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

Retorna uma instância do ambiente de interface do usuário da planilha que permite que o script adicione recursos como menus, caixas de diálogo e barras laterais. Um script só poderá interagir com a IU para a instância atual de uma planilha aberta e somente se o script estiver vinculado a ela. Para mais informações, consulte os guias de menus e caixas de diálogo e barras laterais.

// Add a custom menu to the active spreadsheet, including a separator and a sub-menu.
function onOpen(e) {
  SpreadsheetApp.getUi()
      .createMenu('My Menu')
      .addItem('My menu item', 'myFunction')
      .addSeparator()
      .addSubMenu(SpreadsheetApp.getUi().createMenu('My sub-menu')
          .addItem('One sub-menu item', 'mySecondFunction')
          .addItem('Another sub-menu item', 'myThirdFunction'))
      .addToUi();
}

Retornar

Ui: uma instância do ambiente de interface do usuário desta planilha

Crie um builder para um CellImage.

Retornar

CellImageBuilder: o novo builder.

Crie um builder para um Color.

var rgbColor = SpreadsheetApp.newColor().setRgbColor("#FF0000").build();

Retornar

ColorBuilder: o novo builder.

Cria um builder para uma regra de formatação condicional.

// Adds a conditional format rule to a sheet that causes all cells in range A1:B3 to turn red
// if they contain a number between 1 and 10.
var sheet = SpreadsheetApp.getActive().getActiveSheet();
var range = sheet.getRange('A1:B3');
var rule = SpreadsheetApp.newConditionalFormatRule()
    .whenNumberBetween(1, 10)
    .setBackground("#FF0000")
    .setRanges([range])
    .build()
var rules = sheet.getConditionalFormatRules();
rules.push(rule);
sheet.setConditionalFormatRules(rules);

Retornar

ConditionalFormatRuleBuilder: o novo builder.

Crie um builder para um DataSourceSpec.

Retornar

DataSourceSpecBuilder: o novo builder.

Cria um builder para uma regra de validação de dados.

var cell = SpreadsheetApp.getActive().getRange('A1');
var rule = SpreadsheetApp.newDataValidation()
    .requireNumberBetween(1, 100)
    .setAllowInvalid(false)
    .setHelpText('Number must be between 1 and 100.')
    .build();
cell.setDataValidation(rule);

Retornar

DataValidationBuilder: o novo builder.

Crie um builder para um FilterCriteria.

Retornar

FilterCriteriaBuilder: o novo builder

Cria um builder para um valor de rich text.

// Sets cell A1 to have the text "Hello world", with "Hello" bolded.
var cell = SpreadsheetApp.getActive().getRange('A1');
var bold = SpreadsheetApp.newTextStyle().setBold(true).build();
var value = SpreadsheetApp.newRichTextValue()
    .setText("Hello world")
    .setTextStyle(0, 5, bold)
    .build();
cell.setRichTextValue(value);

Retornar

RichTextValueBuilder: o novo builder.

Crie um builder para um estilo de texto.

// Sets range A1:B3 to have red, size 22, bolded, underlined text.
var range = SpreadsheetApp.getActive().getRange('A1:B3');
var style = SpreadsheetApp.newTextStyle()
    .setForegroundColor("red")
    .setFontSize(22)
    .setBold(true)
    .setUnderline(true)
    .build();
range.setTextStyle(style);

Retornar

TextStyleBuilder: o novo builder.

Abre a planilha que corresponde ao objeto "Arquivo" especificado.

// Get any starred spreadsheets from Google Drive, then open the spreadsheets and log the name
// of the first sheet within each spreadsheet.
var files = DriveApp.searchFiles(
    'starred = true and mimeType = "' + MimeType.GOOGLE_SHEETS + '"');
while (files.hasNext()) {
  var spreadsheet = SpreadsheetApp.open(files.next());
  var sheet = spreadsheet.getSheets()[0];
  Logger.log(sheet.getName());
}

Parâmetros

Retornar

Spreadsheet: a planilha.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

• https://www.googleapis.com/auth/spreadsheets

Abre a planilha com o ID fornecido. Um ID de planilha pode ser extraído do URL. Por exemplo, o ID da planilha no URL https://docs.google.com/spreadsheets/d/abc1234567/edit#gid=0 é "abc1234567"

// The code below opens a spreadsheet using its ID and logs the name for it.
// Note that the spreadsheet is NOT physically opened on the client side.
// It is opened on the server only (for modification by the script).
var ss = SpreadsheetApp.openById("abc1234567");
Logger.log(ss.getName());

Parâmetros

Retornar

Spreadsheet: o objeto da planilha com o ID fornecido.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

• https://www.googleapis.com/auth/spreadsheets

Abre a planilha com o URL fornecido. Uma exceção de script será gerada se o URL não existir ou o usuário não tiver permissão para acessá-lo.

// The code below opens a spreadsheet using its id and logs the name for it.
// Note that the spreadsheet is NOT physically opened on the client side.
// It is opened on the server only (for modification by the script).
var ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc1234567/edit');
Logger.log(ss.getName());

Parâmetros

Retornar

Spreadsheet: o objeto da planilha com o ID fornecido.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

• https://www.googleapis.com/auth/spreadsheets

Define o intervalo especificado como o active range, com a célula superior esquerda no intervalo como o current cell.

A IU da planilha exibe a página que contém o intervalo escolhido e seleciona as células definidas nesse intervalo.

// The code below sets range C1:D4 in the first sheet as the active range.
var range = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0].getRange('C1:D4');
SpreadsheetApp.setActiveRange(range);

var selection = SpreadsheetApp.getSelection();
// Current cell: C1
var currentCell = selection.getCurrentCell();
// Active Range: C1:D4
var activeRange = selection.getActiveRange();

Parâmetros

Retornar

Range: o novo intervalo ativo.

Define a lista de intervalos especificada como active ranges. O último intervalo da lista é definido como o active range.

// The code below sets ranges [D4, B2:C4] in the active sheet as the active ranges.
var rangeList = SpreadsheetApp.getActiveSheet().getRanges(['D4', 'B2:C4']);
SpreadsheetApp.setActiveRangeList(rangeList);

var selection = SpreadsheetApp.getSelection();
// Current cell: B2
var currentCell = selection.getCurrentCell();
// Active range: B2:C4
var activeRange = selection.getActiveRange();
// Active range list: [D4, B2:C4]
var activeRangeList = selection.getActiveRangeList();

Parâmetros

Retornar

RangeList: a lista de intervalos recém-selecionada

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

Define a planilha ativa em uma planilha. A IU do Planilhas Google exibe a planilha escolhida, a menos que ela pertence a outra planilha.

// The code below makes the 2nd sheet active in the active spreadsheet.
var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
SpreadsheetApp.setActiveSheet(spreadsheet.getSheets()[1]);

Parâmetros

Retornar

Sheet: a página que foi transformada na nova página ativa.

Define a página ativa em uma planilha, com a opção de restaurar a seleção mais recente nessa página. A IU do Planilhas Google exibe a planilha escolhida, a menos que a planilha pertença a outra planilha.

var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
var firstSheet = spreadsheet.getSheets()[0];
var secondSheet = spreadsheet.getSheets()[1];
// Set the first sheet as the active sheet and select the range D4:F4.
spreadsheet.setActiveSheet(firstSheet).getRange('D4:F4').activate();

// Switch to the second sheet to do some work.
spreadsheet.setActiveSheet(secondSheet);
// Switch back to first sheet, and restore its selection.
spreadsheet.setActiveSheet(firstSheet, true);

// The selection of first sheet is restored, and it logs D4:F4
var range = spreadsheet.getActiveSheet().getSelection().getActiveRange();
Logger.log(range.getA1Notation());

Parâmetros

Retornar

Sheet: a nova página ativa.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

Define a planilha ativa.

// The code below makes the spreadsheet with key "1234567890" the active spreadsheet
var ss = SpreadsheetApp.openById("1234567890");
SpreadsheetApp.setActiveSpreadsheet(ss);

Parâmetros

Define a célula especificada como o current cell.

Se a célula especificada estiver presente em um intervalo já selecionado, esse intervalo se tornará o intervalo ativo com a célula como a célula atual.

Se a célula especificada não estiver presente em nenhum intervalo selecionado, a seleção existente será removida e a célula se tornará a célula atual e o intervalo ativo.

Observação: o Range especificado precisa ter uma célula. Caso contrário, esse método gerará uma exceção.

// The code below sets the cell B5 in the first sheet as the current cell.
var cell = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0].getRange('B5');
SpreadsheetApp.setCurrentCell(cell);

var selection = SpreadsheetApp.getSelection();
// Current cell: B5
var currentCell = selection.getCurrentCell();

Parâmetros

Retornar

Range: a célula atual recém-definida.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets