Class Range

Intervalo

Acessar e modificar intervalos de planilhas. Um intervalo pode ser uma única célula ou um grupo de células adjacentes em uma página.

Métodos

MétodoTipo de retornoBreve descrição
activate()RangeDefine o intervalo especificado como active range, com a célula superior esquerda no intervalo como current cell.
activateAsCurrentCell()RangeDefine a célula especificada como current cell.
addDeveloperMetadata(key)RangeAdiciona metadados de desenvolvedor com a chave especificada ao intervalo.
addDeveloperMetadata(key, visibility)RangeAdiciona metadados do desenvolvedor com a chave e a visibilidade especificadas ao intervalo.
addDeveloperMetadata(key, value)RangeAdiciona metadados do desenvolvedor com a chave e o valor especificados ao intervalo.
addDeveloperMetadata(key, value, visibility)RangeAdiciona metadados do desenvolvedor com a chave, o valor e a visibilidade especificados ao intervalo.
applyColumnBanding()BandingAplica um tema de banda de coluna padrão ao intervalo.
applyColumnBanding(bandingTheme)BandingAplica um tema de faixa de coluna especificado ao intervalo.
applyColumnBanding(bandingTheme, showHeader, showFooter)BandingAplica um tema de faixa de coluna especificado ao intervalo com configurações específicas de cabeçalho e rodapé.
applyRowBanding()BandingAplica um tema de faixa de linhas padrão ao intervalo.
applyRowBanding(bandingTheme)BandingAplica um tema de faixa de linhas especificado ao intervalo.
applyRowBanding(bandingTheme, showHeader, showFooter)BandingAplica um tema de faixa de linhas especificado ao intervalo com configurações de cabeçalho e rodapé especificadas.
autoFill(destination, series)voidPreenche o destinationRange com dados baseados nos dados desse intervalo.
autoFillToNeighbor(series)voidCalcula um intervalo a ser preenchido com novos dados com base em células vizinhas e preenche automaticamente esse intervalo com novos valores com base nos dados contidos nesse intervalo.
breakApart()RangeDivida todas as células de várias colunas no intervalo em células individuais novamente.
canEdit()BooleanDetermina se o usuário tem permissão para editar cada célula no intervalo.
check()RangeAltera o estado das caixas de seleção no intervalo para "marcada".
clear()RangeLimpa o intervalo de conteúdo e formatos.
clear(options)RangeLimpa o intervalo de conteúdo, formato, regras de validação de dados e/ou comentários, conforme especificado com as opções avançadas fornecidas.
clearContent()RangeLimpa o conteúdo do intervalo, deixando a formatação intacta.
clearDataValidations()RangeLimpa as regras de validação de dados para o intervalo.
clearFormat()RangeLimpa a formatação deste intervalo.
clearNote()RangeLimpa a nota em uma ou mais células específicas.
collapseGroups()RangeRecolhe todos os grupos contidos totalmente no intervalo.
copyFormatToRange(gridId, column, columnEnd, row, rowEnd)voidCopie a formatação do intervalo para o local especificado.
copyFormatToRange(sheet, column, columnEnd, row, rowEnd)voidCopie a formatação do intervalo para o local especificado.
copyTo(destination)voidCopia os dados de um intervalo de células para outro intervalo de células.
copyTo(destination, copyPasteType, transposed)voidCopia os dados de um intervalo de células para outro intervalo de células.
copyTo(destination, options)voidCopia os dados de um intervalo de células para outro intervalo de células.
copyValuesToRange(gridId, column, columnEnd, row, rowEnd)voidCopie o conteúdo do intervalo para o local especificado.
copyValuesToRange(sheet, column, columnEnd, row, rowEnd)voidCopie o conteúdo do intervalo para o local especificado.
createDataSourcePivotTable(dataSource)DataSourcePivotTableCria uma tabela dinâmica de fonte de dados vazia a partir da fonte de dados, ancorada na primeira célula desse intervalo.
createDataSourceTable(dataSource)DataSourceTableCria uma tabela de fonte de dados vazia a partir da fonte de dados, ancorada na primeira célula desse intervalo.
createDeveloperMetadataFinder()DeveloperMetadataFinderRetorna uma DeveloperMetadataFinderApi para encontrar metadados do desenvolvedor no escopo desse intervalo.
createFilter()FilterCria um filtro e o aplica ao intervalo especificado na página.
createPivotTable(sourceData)PivotTableCria uma tabela dinâmica vazia do sourceData especificado ancorado na primeira célula desse intervalo.
createTextFinder(findText)TextFinderCria um localizador de texto para o intervalo, que pode localizar e substituir texto nesse intervalo.
deleteCells(shiftDimension)voidExclui este intervalo de células.
expandGroups()RangeExpande os grupos recolhidos cujo intervalo ou controle de alternância cruza esse intervalo.
getA1Notation()StringRetorna uma descrição de string do intervalo, em notação A1.
getBackground()StringRetorna a cor de fundo da célula superior esquerda do intervalo (por exemplo, '#ffffff').
getBackgroundObject()ColorRetorna a cor de fundo da célula superior esquerda no intervalo.
getBackgroundObjects()Color[][]Retorna as cores de fundo das células no intervalo.
getBackgrounds()String[][]Retorna as cores de fundo das células no intervalo (por exemplo, '#ffffff').
getBandings()Banding[]Retorna todas as faixas aplicadas a qualquer célula neste intervalo.
getCell(row, column)RangeRetorna uma determinada célula dentro de um intervalo.
getColumn()IntegerRetorna a posição inicial da coluna para esse intervalo.
getDataRegion()RangeRetorna uma cópia do intervalo expandido nos quatro Directions cardeais para cobrir todas as células adjacentes com dados.
getDataRegion(dimension)RangeRetorna uma cópia do intervalo expandido Direction.UP e Direction.DOWN se a dimensão especificada for Dimension.ROWS ou Direction.NEXT e Direction.PREVIOUS se a dimensão for Dimension.COLUMNS.
getDataSourceFormula()DataSourceFormulaRetornará DataSourceFormula para a primeira célula no intervalo ou null se a célula não contiver uma fórmula de fonte de dados.
getDataSourceFormulas()DataSourceFormula[]Retorna os DataSourceFormulas das células no intervalo.
getDataSourcePivotTables()DataSourcePivotTable[]Recebe todas as tabelas dinâmicas da fonte de dados que cruzam com o intervalo.
getDataSourceTables()DataSourceTable[]Extrai todas as tabelas de fonte de dados que cruzam com o intervalo.
getDataSourceUrl()StringRetorna um URL dos dados neste intervalo, que pode ser usado para criar gráficos e consultas.
getDataTable()DataTableRetorne os dados dentro desse objeto como uma DataTable.
getDataTable(firstRowIsHeader)DataTableRetorne os dados dentro desse intervalo como uma DataTable.
getDataValidation()DataValidationRetorna a regra de validação de dados para a célula superior esquerda do intervalo.
getDataValidations()DataValidation[][]Retorna as regras de validação de dados para todas as células no intervalo.
getDeveloperMetadata()DeveloperMetadata[]Recebe os metadados do desenvolvedor associados a esse intervalo.
getDisplayValue()StringRetorna o valor exibido da célula superior esquerda do intervalo.
getDisplayValues()String[][]Retorna a grade retangular de valores para este intervalo.
getFilter()FilterRetorna o filtro na página a que o intervalo pertence ou null se não houver filtro na página.
getFontColorObject()ColorRetorna a cor da fonte da célula no canto superior esquerdo do intervalo.
getFontColorObjects()Color[][]Retorna as cores da fonte das células no intervalo.
getFontFamilies()String[][]Retorna as famílias de fontes das células no intervalo.
getFontFamily()StringRetorna a família de fontes da célula no canto superior esquerdo do intervalo.
getFontLine()StringRecebe o estilo de linha da célula no canto superior esquerdo do intervalo ('underline', 'line-through' ou 'none').
getFontLines()String[][]Recebe o estilo da linha das células no intervalo ('underline', 'line-through' ou 'none').
getFontSize()IntegerRetorna o tamanho da fonte em tamanho de ponto da célula no canto superior esquerdo do intervalo.
getFontSizes()Integer[][]Retorna os tamanhos das fontes das células no intervalo.
getFontStyle()StringRetorna o estilo da fonte ('italic' ou 'normal') da célula no canto superior esquerdo do intervalo.
getFontStyles()String[][]Retorna os estilos de fonte das células no intervalo.
getFontWeight()StringRetorna a espessura da fonte (normal/negrito) da célula no canto superior esquerdo do intervalo.
getFontWeights()String[][]Retorna as espessuras de fonte das células no intervalo.
getFormula()StringRetorna a fórmula (notação A1) para a célula superior esquerda do intervalo ou uma string vazia se a célula estiver vazia ou não contiver uma fórmula.
getFormulaR1C1()StringRetorna a fórmula (notação R1C1) de uma determinada célula ou null se nenhuma.
getFormulas()String[][]Retorna as fórmulas (notação A1) das células no intervalo.
getFormulasR1C1()String[][]Retorna as fórmulas (notação R1C1) das células no intervalo.
getGridId()IntegerRetorna o ID da grade da página pai do intervalo.
getHeight()IntegerRetorna a altura do intervalo.
getHorizontalAlignment()StringRetorna o alinhamento horizontal do texto (esquerda/centrado/direita) da célula no canto superior esquerdo do intervalo.
getHorizontalAlignments()String[][]Retorna os alinhamentos horizontais das células no intervalo.
getLastColumn()IntegerRetorna a posição da coluna final.
getLastRow()IntegerRetorna a posição da linha final.
getMergedRanges()Range[]Retorna uma matriz de objetos Range que representam células mescladas que estão totalmente dentro do intervalo atual ou contêm pelo menos uma célula no intervalo atual.
getNextDataCell(direction)RangeComeçando na célula na primeira coluna e linha do intervalo, retorna a próxima célula na direção determinada, que é a borda de um intervalo contíguo de células com dados ou a célula na borda da planilha naquela direção.
getNote()StringRetorna a nota associada ao intervalo especificado.
getNotes()String[][]Retorna as notas associadas às células no intervalo.
getNumColumns()IntegerRetorna o número de colunas nesse intervalo.
getNumRows()IntegerRetorna o número de linhas neste intervalo.
getNumberFormat()StringDefine a formatação de número ou data da célula superior esquerda de determinado intervalo.
getNumberFormats()String[][]Retorna os formatos de número ou data das células no intervalo.
getRichTextValue()RichTextValueRetorna o valor de rich text da célula superior esquerda do intervalo ou null se o valor da célula não for texto.
getRichTextValues()RichTextValue[][]Retorna os valores de rich text das células no intervalo.
getRow()IntegerRetorna a posição da linha para esse intervalo.
getRowIndex()IntegerRetorna a posição da linha para esse intervalo.
getSheet()SheetRetorna a página a que o intervalo pertence.
getTextDirection()TextDirectionRetorna a direção do texto para a célula superior esquerda do intervalo.
getTextDirections()TextDirection[][]Retorna as direções do texto das células no intervalo.
getTextRotation()TextRotationRetorna as configurações de rotação de texto para a célula superior esquerda do intervalo.
getTextRotations()TextRotation[][]Retorna as configurações de rotação do texto para as células no intervalo.
getTextStyle()TextStyleRetorna o estilo de texto da célula superior esquerda do intervalo.
getTextStyles()TextStyle[][]Retorna os estilos de texto das células no intervalo.
getValue()ObjectRetorna o valor da célula superior esquerda do intervalo.
getValues()Object[][]Retorna a grade retangular de valores para este intervalo.
getVerticalAlignment()StringRetorna o alinhamento vertical (superior/meio/inferior) da célula no canto superior esquerdo do intervalo.
getVerticalAlignments()String[][]Retorna os alinhamentos verticais das células no intervalo.
getWidth()IntegerRetorna a largura do intervalo em colunas.
getWrap()BooleanRetorna se o texto na célula é agrupado.
getWrapStrategies()WrapStrategy[][]Retorna as estratégias de ajuste de texto para as células no intervalo.
getWrapStrategy()WrapStrategyRetorna a estratégia de ajuste de texto da célula superior esquerda do intervalo.
getWraps()Boolean[][]Retorna se o texto nas células é ajustado.
insertCells(shiftDimension)RangeInsere células vazias neste intervalo.
insertCheckboxes()RangeInsere caixas de seleção em cada célula do intervalo, configuradas com true para marcada e false para desmarcada.
insertCheckboxes(checkedValue)RangeInsere caixas de seleção em cada célula do intervalo, configuradas com um valor personalizado para marcado e a string vazia para desmarcada.
insertCheckboxes(checkedValue, uncheckedValue)RangeInsere caixas de seleção em cada célula do intervalo, configuradas com valores personalizados para os estados marcado e desmarcado.
isBlank()BooleanRetorna true se o intervalo estiver totalmente em branco.
isChecked()BooleanRetorna se todas as células no intervalo têm seu estado de caixa de seleção como "marcada".
isEndColumnBounded()BooleanDetermina se o fim do intervalo está vinculado a uma coluna específica.
isEndRowBounded()BooleanDetermina se o fim do intervalo está vinculado a uma linha específica.
isPartOfMerge()BooleanRetornará true se as células no intervalo atual se sobrepuserem a qualquer célula mesclada.
isStartColumnBounded()BooleanDetermina se o início do intervalo está vinculado a uma coluna específica.
isStartRowBounded()BooleanDetermina se o início do intervalo está vinculado a uma linha específica.
merge()RangeMescla as células do intervalo em um único bloco.
mergeAcross()RangeMescle as células do intervalo de acordo com as colunas dele.
mergeVertically()RangeMescla as células no intervalo.
moveTo(target)voidRecorte e cole (formatar e valores) deste intervalo para o intervalo de destino.
offset(rowOffset, columnOffset)RangeRetorna um novo intervalo que é deslocado desse intervalo pelo número fornecido de linhas e colunas (que pode ser negativo).
offset(rowOffset, columnOffset, numRows)RangeRetorna um novo intervalo relativo ao intervalo atual, cujo ponto superior esquerdo é deslocado do intervalo atual pelas linhas e colunas fornecidas e com a altura especificada nas células.
offset(rowOffset, columnOffset, numRows, numColumns)RangeRetorna um novo intervalo relativo ao intervalo atual, cujo ponto superior esquerdo é deslocado do intervalo atual pelas linhas e colunas fornecidas e com a altura e largura indicadas nas células.
protect()ProtectionCria um objeto que pode proteger o intervalo de ser editado, exceto por usuários que tenham permissão.
randomize()RangeRandomiza a ordem das linhas no intervalo fornecido.
removeCheckboxes()RangeRemove todas as caixas de seleção do intervalo.
removeDuplicates()RangeRemove as linhas dentro desse intervalo que contêm valores duplicados de valores em qualquer linha anterior.
removeDuplicates(columnsToCompare)RangeRemove as linhas dentro desse intervalo que contêm valores nas colunas especificadas que são cópias de valores de qualquer linha anterior.
setBackground(color)RangeDefine a cor do plano de fundo de todas as células no intervalo na notação CSS (como '#ffffff' ou 'white').
setBackgroundObject(color)RangeDefine a cor de fundo de todas as células no intervalo.
setBackgroundObjects(color)RangeDefine uma grade retangular de cores de fundo (deve corresponder às dimensões deste intervalo).
setBackgroundRGB(red, green, blue)RangeDefine o plano de fundo com a cor especificada usando valores RGB (números inteiros entre 0 e 255).
setBackgrounds(color)RangeDefine uma grade retangular de cores de fundo (deve corresponder às dimensões deste intervalo).
setBorder(top, left, bottom, right, vertical, horizontal)RangeDefine a propriedade da borda.
setBorder(top, left, bottom, right, vertical, horizontal, color, style)RangeDefine a propriedade da borda com cor e/ou estilo.
setDataValidation(rule)RangeDefine uma regra de validação de dados para todas as células no intervalo.
setDataValidations(rules)RangeDefine as regras de validação de dados para todas as células no intervalo.
setFontColor(color)RangeDefine a cor da fonte na notação CSS (como '#ffffff' ou 'white').
setFontColorObject(color)RangeDefine a cor da fonte do intervalo especificado.
setFontColorObjects(colors)RangeDefine uma grade retangular de cores de fonte (deve corresponder às dimensões deste intervalo).
setFontColors(colors)RangeDefine uma grade retangular de cores de fonte (deve corresponder às dimensões deste intervalo).
setFontFamilies(fontFamilies)RangeDefine uma grade retangular de famílias de fontes (deve corresponder às dimensões desse intervalo).
setFontFamily(fontFamily)RangeDefine a família de fontes, como "Arial" ou "Helvetica".
setFontLine(fontLine)RangeDefine o estilo da linha de fonte do intervalo especificado ('underline', 'line-through' ou 'none').
setFontLines(fontLines)RangeDefine uma grade retangular de estilos de linha (deve corresponder às dimensões deste intervalo).
setFontSize(size)RangeDefine o tamanho da fonte, sendo o tamanho o tamanho do ponto a ser usado.
setFontSizes(sizes)RangeDefine uma grade retangular de tamanhos de fonte (deve corresponder às dimensões desse intervalo).
setFontStyle(fontStyle)RangeDefine o estilo da fonte do intervalo especificado ('italic' ou 'normal').
setFontStyles(fontStyles)RangeDefine uma grade retangular de estilos de fonte (deve corresponder às dimensões desse intervalo).
setFontWeight(fontWeight)RangeDefine a espessura da fonte para o intervalo fornecido (normal/negrito).
setFontWeights(fontWeights)RangeDefine uma grade retangular de espessuras de fonte (deve corresponder às dimensões deste intervalo).
setFormula(formula)RangeAtualiza a fórmula para esse intervalo.
setFormulaR1C1(formula)RangeAtualiza a fórmula para esse intervalo.
setFormulas(formulas)RangeDefine uma grade retangular de fórmulas (precisa corresponder às dimensões deste intervalo).
setFormulasR1C1(formulas)RangeDefine uma grade retangular de fórmulas (precisa corresponder às dimensões deste intervalo).
setHorizontalAlignment(alignment)RangeDefine o alinhamento horizontal (da esquerda para a direita) para o intervalo especificado (esquerda/central/direita).
setHorizontalAlignments(alignments)RangeDefine uma grade retangular de alinhamentos horizontais.
setNote(note)RangeDefine a nota para o valor fornecido.
setNotes(notes)RangeDefine uma grade retangular de notas (deve corresponder às dimensões deste intervalo).
setNumberFormat(numberFormat)RangeDefine o formato de número ou data para a string de formatação especificada.
setNumberFormats(numberFormats)RangeDefine uma grade retangular de formatos de número ou data (deve corresponder às dimensões desse intervalo).
setRichTextValue(value)RangeDefine o valor de rich text para as células no intervalo.
setRichTextValues(values)RangeDefine uma grade retangular de valores de Rich Text.
setShowHyperlink(showHyperlink)RangeDefine se o intervalo deve ou não exibir hiperlinks.
setTextDirection(direction)RangeDefine a direção do texto das células no intervalo.
setTextDirections(directions)RangeDefine uma grade retangular de direções de texto.
setTextRotation(degrees)RangeDefine as configurações de rotação do texto para as células no intervalo.
setTextRotation(rotation)RangeDefine as configurações de rotação do texto para as células no intervalo.
setTextRotations(rotations)RangeDefine uma grade retangular de rotações do texto.
setTextStyle(style)RangeDefine o estilo de texto das células no intervalo.
setTextStyles(styles)RangeDefine uma grade retangular de estilos de texto.
setValue(value)RangeDefine o valor do intervalo.
setValues(values)RangeDefine uma grade retangular de valores (precisa corresponder às dimensões deste intervalo).
setVerticalAlignment(alignment)RangeDefine o alinhamento vertical (de cima para baixo) no intervalo especificado (superior/meio/inferior).
setVerticalAlignments(alignments)RangeDefine uma grade retangular de alinhamentos verticais (deve corresponder às dimensões deste intervalo).
setVerticalText(isVertical)RangeDefine se o texto será empilhado para as células no intervalo.
setWrap(isWrapEnabled)RangeDefine a quebra de célula do intervalo especificado.
setWrapStrategies(strategies)RangeDefine uma grade retangular de estratégias de agrupamento.
setWrapStrategy(strategy)RangeDefine a estratégia de ajuste de texto para as células no intervalo.
setWraps(isWrapEnabled)RangeDefine uma grade retangular de políticas de quebra de palavra (deve corresponder às dimensões desse intervalo).
shiftColumnGroupDepth(delta)RangeAltera a profundidade do agrupamento de colunas do intervalo pelo valor especificado.
shiftRowGroupDepth(delta)RangeAltera a profundidade do agrupamento de linhas do intervalo pelo valor especificado.
sort(sortSpecObj)RangeClassifica as células de um intervalo específico, por coluna e ordem especificada.
splitTextToColumns()voidDivide uma coluna de texto em várias colunas com base em um delimitador detectado automaticamente.
splitTextToColumns(delimiter)voidDivide uma coluna de texto em várias colunas usando a string especificada como um delimitador personalizado.
splitTextToColumns(delimiter)voidDivide uma coluna de texto em várias colunas com base no delimitador especificado.
trimWhitespace()RangeCorta o espaço em branco (como espaços, tabulações ou novas linhas) em todas as células neste intervalo.
uncheck()RangeAltera o estado das caixas de seleção no intervalo para "desmarcada".

Documentação detalhada

activate()

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

var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
var range = sheet.getRange('A1:D10');
range.activate();

var selection = sheet.getSelection();
// Current cell: A1
var currentCell = selection.getCurrentCell();
// Active Range: A1:D10
var activeRange = selection.getActiveRange();

Retorno

Range: esse intervalo para encadeamento.


activateAsCurrentCell()

Define a célula especificada como current cell.

Se a célula especificada estiver presente em um intervalo existente, 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 atual, a seleção atual será removida e a célula se tornará a célula atual e o intervalo ativo.

Observação:o Range especificado precisa consistir em uma célula. Caso contrário, uma exceção será gerada.

// Gets the first sheet of the spreadsheet.
var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];

// Gets the cell B5 and sets it as the active cell.
var range = sheet.getRange('B5');
var currentCell = range.activateAsCurrentCell();

// Logs the activated cell.
console.log(currentCell.getA1Notation());

Retorno

Range: esse intervalo para encadeamento.

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

addDeveloperMetadata(key)

Adiciona metadados de desenvolvedor com a chave especificada ao intervalo.

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 on the sheet.
const range = sheet.getRange('2:2');

// Adds the key 'NAME' to the developer metadata for row 2.
range.addDeveloperMetadata('NAME');

// Gets the metadata and logs it to the console.
const developerMetaData = range.getDeveloperMetadata()[0];
console.log(developerMetaData.getKey());

Parâmetros

NomeTipoDescrição
keyStringA chave para os novos metadados do desenvolvedor.

Retorno

Range: esse intervalo para encadeamento.

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

addDeveloperMetadata(key, visibility)

Adiciona metadados do desenvolvedor com a chave e a visibilidade especificadas ao intervalo.

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 on Sheet1.
const range = sheet.getRange('2:2');

// Adds the key 'NAME' and sets the developer metadata visibility to 'DOCUMENT'
// for row 2 on Sheet1.
range.addDeveloperMetadata('NAME', SpreadsheetApp.DeveloperMetadataVisibility.DOCUMENT);

// Gets the updated metadata info and logs it to the console.
const developerMetaData = range.getDeveloperMetadata()[0];
console.log(developerMetaData.getKey());
console.log(developerMetaData.getVisibility().toString());

Parâmetros

NomeTipoDescrição
keyStringA chave para os novos metadados do desenvolvedor.
visibilityDeveloperMetadataVisibilityA visibilidade dos novos metadados do desenvolvedor.

Retorno

Range: esse intervalo para encadeamento.

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

addDeveloperMetadata(key, value)

Adiciona metadados do desenvolvedor com a chave e o valor especificados ao intervalo.

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 of Sheet1.
const range = sheet.getRange('2:2');

// Adds the key 'NAME' and sets the value to 'GOOGLE' for the metadata of row 2.
range.addDeveloperMetadata('NAME', 'GOOGLE');

// Gets the metadata and logs it to the console.
const developerMetaData = range.getDeveloperMetadata()[0];
console.log(developerMetaData.getKey());
console.log(developerMetaData.getValue());

Parâmetros

NomeTipoDescrição
keyStringA chave para os novos metadados do desenvolvedor.
valueStringO valor dos novos metadados do desenvolvedor.

Retorno

Range: esse intervalo para encadeamento.

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

addDeveloperMetadata(key, value, visibility)

Adiciona metadados do desenvolvedor com a chave, o valor e a visibilidade especificados ao intervalo.

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 on the sheet.
const range = sheet.getRange('2:2');

// Adds the key 'NAME', sets the value to 'GOOGLE', and sets the visibility
// to PROJECT for row 2 on the sheet.
range.addDeveloperMetadata(
  'NAME',
  'GOOGLE',
  SpreadsheetApp.DeveloperMetadataVisibility.PROJECT);

// Gets the updated metadata info and logs it to the console.
const developerMetaData = range.getDeveloperMetadata()[0];
console.log(developerMetaData.getKey());
console.log(developerMetaData.getValue());
console.log(developerMetaData.getVisibility().toString());

Parâmetros

NomeTipoDescrição
keyStringA chave para os novos metadados do desenvolvedor.
valueStringO valor dos novos metadados do desenvolvedor.
visibilityDeveloperMetadataVisibilityA visibilidade dos novos metadados do desenvolvedor.

Retorno

Range: esse intervalo para encadeamento.

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

applyColumnBanding()

Aplica um tema de banda de coluna padrão ao intervalo. Por padrão, a faixa tem cor de cabeçalho e nenhuma cor do rodapé.

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 on the sheet.
const range = sheet.getRange('2:2');

// Applies column banding to row 2.
const colBanding = range.applyColumnBanding();

// Gets the first banding on the sheet and logs the color of the header column.
console.log(sheet.getBandings()[0].getHeaderColumnColorObject().asRgbColor().asHexString());

// Gets the first banding on the sheet and logs the color of the second column.
console.log(sheet.getBandings()[0].getSecondColumnColorObject().asRgbColor().asHexString());

Retorno

Banding – A nova banda.

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

applyColumnBanding(bandingTheme)

Aplica um tema de faixa de coluna especificado ao intervalo. Por padrão, a faixa tem cor de cabeçalho e não de rodapé.

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 on the sheet.
const range = sheet.getRange('2:2');

// Applies the INDIGO color banding theme to the columns in row 2.
const colBanding = range.applyColumnBanding(SpreadsheetApp.BandingTheme.INDIGO);

// Gets the first banding on the sheet and logs the color of the second column.
console.log(sheet.getBandings()[0].getSecondColumnColorObject().asRgbColor().asHexString());

Parâmetros

NomeTipoDescrição
bandingThemeBandingThemeUm tema de cores para aplicar às colunas do intervalo.

Retorno

Banding – A nova banda.

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

applyColumnBanding(bandingTheme, showHeader, showFooter)

Aplica um tema de faixa de coluna especificado ao intervalo com configurações específicas de cabeçalho e rodapé.

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets rows 12-22 on the sheet.
const range = sheet.getRange('12:22');

// Applies the BLUE color banding theme to rows 12-22.
// Sets the header visibility to false and the footer visibility to true.
const colBanding = range.applyColumnBanding(SpreadsheetApp.BandingTheme.BLUE, false, true);

// Gets the banding color and logs it to the console.
console.log(sheet.getBandings()[0].getSecondColumnColorObject().asRgbColor().asHexString());

// Gets the header color object and logs it to the console. Returns null because the header
// visibility is set to false.
console.log(sheet.getBandings()[0].getHeaderColumnColorObject());

// Gets the footer color and logs it to the console.
console.log(sheet.getBandings()[0].getFooterColumnColorObject().asRgbColor().asHexString());

Parâmetros

NomeTipoDescrição
bandingThemeBandingThemeUm tema de cores para aplicar às colunas do intervalo.
showHeaderBooleanSe for true, a cor do cabeçalho do tema de faixas será aplicada à primeira coluna.
showFooterBooleanSe for true, a cor do rodapé do tema de faixas será aplicada à última coluna.

Retorno

Banding – A nova banda.

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

applyRowBanding()

Aplica um tema de faixa de linhas padrão ao intervalo. Por padrão, a faixa tem cor de cabeçalho e nenhuma cor do rodapé.

// Opens the spreadsheet by its URL. If you created your script from within a Google Sheets
// spreadsheet, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets rows 1-30 on Sheet1.
const range = sheet.getRange('1:30');

// Applies row banding to rows 1-30.
range.applyRowBanding();

// Gets the hex color of the second banded row.
const secondRowColor = range.getBandings()[0]
                            .getSecondRowColorObject()
                            .asRgbColor()
                            .asHexString();

// Logs the hex color to console.
console.log(secondRowColor);

Retorno

Banding — A faixa.

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

applyRowBanding(bandingTheme)

Aplica um tema de faixa de linhas especificado ao intervalo. Por padrão, a faixa tem cor de cabeçalho e nenhuma cor do rodapé.

// Opens the spreadsheet by its URL. If you created your script from within a Google Sheets
// spreadsheet, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets rows 1-30 on Sheet1.
const range = sheet.getRange('1:30');

// Applies the INDIGO row banding theme to rows 1-30.
range.applyRowBanding(SpreadsheetApp.BandingTheme.INDIGO);

// Gets the hex color of the second banded row.
const secondRowColor = range.getBandings()[0]
                            .getSecondRowColorObject()
                            .asRgbColor()
                            .asHexString();

// Logs the hex color to console.
console.log(secondRowColor);

Parâmetros

NomeTipoDescrição
bandingThemeBandingThemeUm tema de cores para aplicar às linhas do intervalo.

Retorno

Banding – A nova banda.

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

applyRowBanding(bandingTheme, showHeader, showFooter)

Aplica um tema de faixa de linhas especificado ao intervalo com configurações de cabeçalho e rodapé especificadas.

// Opens the spreadsheet by its URL. If you created your script from within a Google Sheets
// spreadsheet, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets rows 1-30 on Sheet1.
const range = sheet.getRange('1:30');

// Applies the INDIGO row banding to rows 1-30 and
// specifies to hide the header and show the footer.
range.applyRowBanding(SpreadsheetApp.BandingTheme.INDIGO, false, true);

Parâmetros

NomeTipoDescrição
bandingThemeBandingThemeUm tema de cores para aplicar às linhas do intervalo.
showHeaderBooleanSe for true, a cor do cabeçalho do tema de faixas será aplicada à primeira linha.
showFooterBooleanSe for true, a cor do rodapé do tema de faixas será aplicada à última linha.

Retorno

Banding – A nova banda.

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

autoFill(destination, series)

Preenche o destinationRange com dados baseados nos dados desse intervalo. Os novos valores também são determinados pelo tipo series especificado. O intervalo de destino precisa conter esse intervalo e estendê-lo em apenas uma direção. Por exemplo, o código a seguir preenche A1:A20 com uma série de números crescentes com base nos valores atuais em A1:A4:

var sheet = SpreadsheetApp.getActiveSheet();

// Has values [1, 2, 3, 4].
var sourceRange = sheet.getRange("A1:A4");
// The range to fill with values.
var destination = sheet.getRange("A1:A20");

// Inserts new values in A5:A20, continuing the pattern expressed in A1:A4
sourceRange.autoFill(destination, SpreadsheetApp.AutoFillSeries.DEFAULT_SERIES);

Parâmetros

NomeTipoDescrição
destinationRangeO intervalo a ser preenchido automaticamente com valores. O intervalo de destino precisa conter esse intervalo e o estender em apenas uma direção (para cima, para baixo, para a esquerda ou para a direita).
seriesAutoFillSeriesO tipo de série de preenchimento automático que deve ser usado para calcular novos valores. O efeito dessa série varia de acordo com o tipo e a quantidade de dados de origem.

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

autoFillToNeighbor(series)

Calcula um intervalo a ser preenchido com novos dados com base em células vizinhas e preenche automaticamente esse intervalo com novos valores com base nos dados contidos nesse intervalo. Esses novos valores também são determinados pelo tipo de series especificado.

O intervalo de destino calculado considera os dados ao redor para determinar onde os novos valores precisam ser inseridos: se houver dados à esquerda ou à direita imediatas de uma coluna que está sendo preenchida automaticamente, os novos valores só se estendem até esses dados adjacentes.

Por exemplo, se A1:A20 for preenchido com uma série de números crescentes e esse método for chamado no intervalo B1:B4 que contém uma série de datas, os novos valores serão inseridos apenas em B5:B20. Dessa forma, esses novos valores "se fixam" nas células que contêm valores na coluna A.

var sheet = SpreadsheetApp.getActiveSheet();

// A1:A20 has values [1, 2, 3, ... 20].
// B1:B4 has values [1/1/2017, 1/2/2017, ...]
var sourceRange = sheet.getRange("B1:B4");

// Results in B5:B20 having values [1/5/2017, ... 1/20/2017]
sourceRange.autoFillToNeighbor(SpreadsheetApp.AutoFillSeries.DEFAULT_SERIES);

Parâmetros

NomeTipoDescrição
seriesAutoFillSeriesO tipo de série de preenchimento automático que deve ser usado para calcular novos valores. O efeito dessa série varia de acordo com o tipo e a quantidade de dados de origem.

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

breakApart()

Divida todas as células de várias colunas no intervalo em células individuais novamente.

Chamar essa função em um intervalo é equivalente a selecionar um intervalo e clicar em Formatar > Mesclar células > Desfazer mesclagem.

// Opens the spreadsheet by its URL. If you created your script from within a Google Sheets
// spreadsheet, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:C6 on Sheet1.
const range = sheet.getRange('A1:C6');

// Unmerges the range A1:C6 into individual cells.
range.breakApart();

Retorno

Range: esse intervalo para encadeamento.

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

canEdit()

Determina se o usuário tem permissão para editar cada célula no intervalo. O proprietário da planilha sempre pode editar páginas e intervalos protegidos.

// Opens the spreadsheet by its URL. If you created your script from within a Google Sheets
// spreadsheet, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:C6 on Sheet1.
const range = sheet.getRange('A1:C6');

// Logs whether the user has permission to edit every cell in the range.
console.log(range.canEdit());

Retorno

Boolean: true se o usuário tiver permissão para editar todas as células do intervalo. Caso contrário, false.

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

check()

Muda o estado das caixas de seleção no intervalo para "marcada". Ignora as células no intervalo que atualmente não contêm o valor marcado ou desmarcado configurado.

// Changes the state of cells which currently contain either the checked or unchecked value
// configured in the range A1:B10 to 'checked'.
var range = SpreadsheetApp.getActive().getRange('A1:B10');
range.check();

Retorno

Range: esse intervalo para encadeamento.

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

clear()

Limpa o intervalo de conteúdo e formatos.

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

var range = sheet.getRange("A1:D10");
range.clear();

Retorno

Range: esse intervalo para encadeamento.

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

clear(options)

Limpa o intervalo de conteúdo, formato, regras de validação de dados e/ou comentários, conforme especificado com as opções avançadas fornecidas. Por padrão, todos os dados são apagados.

// The code below clears range C2:G7 in the active sheet, but preserves the format,
// data validation rules, and comments.
SpreadsheetApp.getActiveSheet().getRange(2, 3, 6, 5).clear({contentsOnly: true});

Parâmetros

NomeTipoDescrição
optionsObjectUm objeto JavaScript que especifica parâmetros avançados, conforme listado abaixo.

Parâmetros avançados

NomeTipoDescrição
commentsOnlyBooleanDefine se somente os comentários devem ser apagados.
contentsOnlyBooleanDefine se apenas o conteúdo deve ser apagado.
formatOnlyBooleanDefine se apenas o formato será limpo. Observe que limpar o formato também limpa as regras de validação de dados.
validationsOnlyBooleanDefine se apenas as regras de validação de dados devem ser apagadas.
skipFilteredRowsBooleanDefine se as linhas filtradas devem ser evitadas.

Retorno

Range: esse intervalo para encadeamento.

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

clearContent()

Limpa o conteúdo do intervalo, deixando a formatação intacta.

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

var range = sheet.getRange("A1:D10");
range.clearContent();

Retorno

Range: esse intervalo para encadeamento.

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

clearDataValidations()

Limpa as regras de validação de dados para o intervalo.

// Clear the data validation rules for cells A1:B5.
var range = SpreadsheetApp.getActive().getRange('A1:B5');
range.clearDataValidations();

Retorno

Range: esse intervalo para encadeamento.

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

clearFormat()

Limpa a formatação deste intervalo.

Isso limpa a formatação do texto das células no intervalo, mas não redefine nenhuma regra de formatação de números.

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

var range = sheet.getRange("A1:D10");
range.clearFormat();

Retorno

Range: esse intervalo para encadeamento.

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

clearNote()

Limpa a nota em uma ou mais células específicas.

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

var range = sheet.getRange("A1:D10");
range.clearNote();

Retorno

Range: esse intervalo para encadeamento.

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

collapseGroups()

Recolhe todos os grupos contidos totalmente no intervalo. Se nenhum grupo estiver totalmente dentro do intervalo, o grupo expandido mais profundo que estiver parcialmente dentro do intervalo será recolhido.

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

// All row and column groups within the range are collapsed.
range.collapseGroups();

Retorno

Range: esse intervalo para encadeamento.

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

copyFormatToRange(gridId, column, columnEnd, row, rowEnd)

Copie a formatação do intervalo para o local especificado. Se o destino for maior ou menor que o intervalo de origem, a origem será repetida ou truncada conforme necessário. Observe que esse método apenas copia a formatação.

Para uma descrição detalhada do parâmetro gridId, consulte getGridId().

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

var range = source.getRange("B2:D4");

// This copies the formatting in B2:D4 in the source sheet to
// D4:F6 in the sheet with gridId 1555299895. Note that you can get the gridId
// of a sheet by calling sheet.getSheetId() or range.getGridId().
range.copyFormatToRange(1555299895, 4, 6, 4, 6);

Parâmetros

NomeTipoDescrição
gridIdIntegerO ID exclusivo da página na planilha, independentemente da posição.
columnIntegerA primeira coluna do intervalo de destino.
columnEndIntegerA coluna final do intervalo de destino.
rowIntegerA linha inicial do intervalo de destino.
rowEndIntegerA linha final do intervalo de destino.

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

Veja também


copyFormatToRange(sheet, column, columnEnd, row, rowEnd)

Copie a formatação do intervalo para o local especificado. Se o destino for maior ou menor que o intervalo de origem, a origem será repetida ou truncada conforme necessário. Observe que esse método apenas copia a formatação.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var source = ss.getSheets()[0];
var destination = ss.getSheets()[1];

var range = source.getRange("B2:D4");

// This copies the formatting in B2:D4 in the source sheet to
// D4:F6 in the second sheet
range.copyFormatToRange(destination, 4, 6, 4, 6);

Parâmetros

NomeTipoDescrição
sheetSheetA página de destino.
columnIntegerA primeira coluna do intervalo de destino.
columnEndIntegerA coluna final do intervalo de destino.
rowIntegerA linha inicial do intervalo de destino.
rowEndIntegerA linha final do intervalo de destino.

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

copyTo(destination)

Copia os dados de um intervalo de células para outro intervalo de células. Os valores e a formatação são copiados.

// The code below copies the first 5 columns over to the 6th column.
var sheet = SpreadsheetApp.getActiveSheet();
var rangeToCopy = sheet.getRange(1, 1, sheet.getMaxRows(), 5);
rangeToCopy.copyTo(sheet.getRange(1, 6));

Parâmetros

NomeTipoDescrição
destinationRangeUm intervalo de destino para onde copiar. Apenas a posição da célula superior esquerda é relevante.

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

copyTo(destination, copyPasteType, transposed)

Copia os dados de um intervalo de células para outro intervalo de células.

// The code below copies only the values of the first 5 columns over to the 6th column.
var sheet = SpreadsheetApp.getActiveSheet();
sheet.getRange("A:E").copyTo(sheet.getRange("F1"), SpreadsheetApp.CopyPasteType.PASTE_VALUES,
false);

Parâmetros

NomeTipoDescrição
destinationRangeUm intervalo de destino para onde copiar. Apenas a posição da célula superior esquerda é relevante.
copyPasteTypeCopyPasteTypeUm tipo que especifica como o conteúdo do intervalo é colado no destino.
transposedBooleanSe o intervalo deve ser colado na orientação transposta.

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

copyTo(destination, options)

Copia os dados de um intervalo de células para outro intervalo de células. Por padrão, os valores e a formatação são copiados, mas isso pode ser substituído usando argumentos avançados.

// The code below copies only the values of the first 5 columns over to the 6th column.
var sheet = SpreadsheetApp.getActiveSheet();
sheet.getRange("A:E").copyTo(sheet.getRange("F1"), {contentsOnly:true});

Parâmetros

NomeTipoDescrição
destinationRangeUm intervalo de destino para onde copiar. Apenas a posição da célula superior esquerda é relevante.
optionsObjectUm objeto JavaScript que especifica parâmetros avançados, conforme listado abaixo.

Parâmetros avançados

NomeTipoDescrição
formatOnlyBooleandetermina que só o formato deve ser copiado
contentsOnlyBooleandetermina que só o conteúdo deve ser copiado

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

copyValuesToRange(gridId, column, columnEnd, row, rowEnd)

Copie o conteúdo do intervalo para o local especificado. Se o destino for maior ou menor que o intervalo de origem, a origem será repetida ou truncada conforme necessário.

Para uma descrição detalhada do parâmetro gridId, consulte getGridId().

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

var range = source.getRange("B2:D4");

// This copies the data in B2:D4 in the source sheet to
// D4:F6 in the sheet with gridId 0
range.copyValuesToRange(0, 4, 6, 4, 6);

Parâmetros

NomeTipoDescrição
gridIdIntegerO ID exclusivo da página na planilha, independentemente da posição.
columnIntegerA primeira coluna do intervalo de destino.
columnEndIntegerA coluna final do intervalo de destino.
rowIntegerA linha inicial do intervalo de destino.
rowEndIntegerA linha final do intervalo de destino.

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

Veja também


copyValuesToRange(sheet, column, columnEnd, row, rowEnd)

Copie o conteúdo do intervalo para o local especificado. Se o destino for maior ou menor que o intervalo de origem, a origem será repetida ou truncada conforme necessário.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var source = ss.getSheets()[0];
var destination = ss.getSheets()[1];

var range = source.getRange("B2:D4");

// This copies the data in B2:D4 in the source sheet to
// D4:F6 in the second sheet
range.copyValuesToRange(destination, 4, 6, 4, 6);

Parâmetros

NomeTipoDescrição
sheetSheetA página de destino.
columnIntegerA primeira coluna do intervalo de destino.
columnEndIntegerA coluna final do intervalo de destino.
rowIntegerA linha inicial do intervalo de destino.
rowEndIntegerA linha final do intervalo de destino.

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

createDataSourcePivotTable(dataSource)

Cria uma tabela dinâmica de fonte de dados vazia a partir da fonte de dados, ancorada na primeira célula desse intervalo.

Neste exemplo, mostramos como criar e configurar uma nova tabela dinâmica de fonte de dados.

var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
var anchorCell = spreadsheet.getSheets()[0].getRange('A1');
var dataSource = spreadsheet.getDataSources()[0];

var pivotTable = anchorCell.createDataSourcePivotTable(dataSource);
pivotTable.addRowGroup('dataColumnA');
pivotTable.addColumnGroup('dataColumnB');
pivotTable.addPivotValue('dataColumnC', SpreadsheetApp.PivotTableSummarizeFunction.SUM);
pivotTable.addFilter('dataColumnA',
                     SpreadsheetApp.newFilterCriteria().whenTextStartsWith('A').build());

Parâmetros

NomeTipoDescrição
dataSourceDataSourceA fonte de dados a partir da qual a tabela dinâmica será criada.

Retorno

DataSourcePivotTable: a tabela dinâmica de fonte de dados recém-criada.

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

createDataSourceTable(dataSource)

Cria uma tabela de fonte de dados vazia a partir da fonte de dados, ancorada na primeira célula desse intervalo.

Neste exemplo, mostramos como criar e configurar uma nova tabela de fonte de dados.

var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
var anchorCell = spreadsheet.getSheets()[0].getRange('A1');
var dataSource = spreadsheet.getDataSources()[0];

var dataSourceTable = anchorCell.createDataSourceTable(dataSource);
    .addColumns('dataColumnA', 'dataColumnB', 'dataColumnC')
    .addSortSpec('dataColumnA', /* ascending= *\/ true)
    .addSortSpec('dataColumnB', /* ascending= *\/ false);

Parâmetros

NomeTipoDescrição
dataSourceDataSourceA fonte de dados a partir da qual a tabela dinâmica será criada.

Retorno

DataSourceTable: a tabela de fonte de dados recém-criada.

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

createDeveloperMetadataFinder()

Retorna uma DeveloperMetadataFinderApi para encontrar metadados do desenvolvedor no escopo desse intervalo. Os metadados só estarão dentro do escopo do intervalo se estiverem totalmente contidos nesse intervalo. Por exemplo, os metadados associados à linha "3:3" não estão no escopo de um intervalo "A1:D5", mas estão dentro do escopo de um intervalo "1:5".

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:C6.
const range = sheet.getRange('A1:C6');

// Creates a developer metadata finder to search for metadata in the scope of this range.
const developerMetaDataFinder = range.createDeveloperMetadataFinder();

// Logs information about the developer metadata finder to the console.
const developerMetaData = developerMetaDataFinder.find()[0];
console.log(developerMetaData.getKey());
console.log(developerMetaData.getValue());
console.log(developerMetaData.getVisibility().toString());

Retorno

DeveloperMetadataFinder: um localizador de metadados do desenvolvedor para pesquisar metadados no escopo desse intervalo.


createFilter()

Cria um filtro e o aplica ao intervalo especificado na página. Não é possível criar mais de um filtro em uma planilha. Para acessar e modificar seu filtro depois de criá-lo, use getFilter() ou Sheet.getFilter().

let ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");

// Creates a new filter and applies it to the range A1:C20 on the active sheet.
function createFilter() {
  range.createFilter();
}
// Gets the filter and applies criteria that only shows cells that aren't empty.
function getFilterAddCriteria() {
  let filter = range.getFilter();
  let criteria = SpreadsheetApp.newFilterCriteria()
    .whenCellNotEmpty()
    .build();
  filter.setColumnFilterCriteria(2, criteria);
}
Use este método para criar filtros para Grid planilhas, o tipo padrão. As planilhas de grade não estão conectadas a um banco de dados. Para criar outros tipos de filtros, consulte o seguinte:

Retorno

Filter: o novo filtro.

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

createPivotTable(sourceData)

Cria uma tabela dinâmica vazia do sourceData especificado ancorado na primeira célula desse intervalo.

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets cell A1 as a range in order to place the pivot table.
const range = sheet.getRange('A1');

// Gets the range of the source data for the pivot table.
const dataRange = sheet.getRange('E12:G20');

// Creates an empty pivot table from the specified source data.
const pivotTable = range.createPivotTable(dataRange);

// Logs the values from the pivot table's source data to the console.
console.log(pivotTable.getSourceDataRange().getValues());

Parâmetros

NomeTipoDescrição
sourceDataRangeOs dados a partir dos quais a tabela dinâmica será criada.

Retorno

PivotTable: a PivotTable recém-criada.

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

createTextFinder(findText)

Cria um localizador de texto para o intervalo, que pode localizar e substituir texto nesse intervalo.

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

// Creates  a text finder for the range.
var textFinder = range.createTextFinder('dog');

// Returns the first occurrence of 'dog'.
var firstOccurrence = textFinder.findNext();

// Replaces the last found occurrence of 'dog' with 'cat' and returns the number
// of occurrences replaced.
var numOccurrencesReplaced = textFinder.replaceWith('cat');

Parâmetros

NomeTipoDescrição
findTextStringO texto a ser pesquisado.

Retorno

TextFinder: o TextFinder do intervalo.


deleteCells(shiftDimension)

Exclui este intervalo de células. Os dados existentes na planilha ao longo da dimensão fornecida são deslocados para o intervalo excluído.

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

var range = sheet.getRange("A1:D10");
range.deleteCells(SpreadsheetApp.Dimension.COLUMNS);

Parâmetros

NomeTipoDescrição
shiftDimensionDimensionA dimensão na qual os dados existentes serão transferidos.

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

expandGroups()

Expande os grupos recolhidos cujo intervalo ou controle de alternância cruza esse intervalo. O local de alternância do controle é o índice em que o botão de alternância é mostrado, logo antes ou depois do grupo, dependendo das configurações. Se houver mais de um grupo no mesmo local, o grupo mais distante será expandido.

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

// All row and column groups within the range are expanded.
range.expandGroups();

Retorno

Range: esse intervalo para encadeamento.

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

getA1Notation()

Retorna uma descrição de string do intervalo, em notação A1.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange(1, 1, 2, 5);

// Logs "A1:E2"
Logger.log(range.getA1Notation());

Retorno

String: a descrição da string do intervalo na notação A1.

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

getBackground()

Retorna a cor de fundo da célula superior esquerda do intervalo (por exemplo, '#ffffff').

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

var cell = sheet.getRange("B5");
Logger.log(cell.getBackground());

Retorno

String: o código de cor do plano de fundo.

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

getBackgroundObject()

Retorna a cor de fundo da célula superior esquerda no intervalo.

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

var cell = sheet.getRange("B5");
Logger.log(cell.getBackgroundObject().asRgbColor().asHexString());

Retorno

Color: a cor de plano de fundo da célula superior esquerda do intervalo.

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

getBackgroundObjects()

Retorna as cores de fundo das células no intervalo.

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

var range = sheet.getRange("B5:C6");
var bgColors = range.getBackgroundObjects();
for (var i in bgColors) {
  for (var j in bgColors[i]) {
    Logger.log(bgColors[i][j].asRgbColor().asHexString());
  }
}

Retorno

Color[][]: uma matriz bidimensional de cores de plano de fundo.

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

getBackgrounds()

Retorna as cores de fundo das células no intervalo (por exemplo, '#ffffff').

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

var range = sheet.getRange("B5:C6");
var bgColors = range.getBackgrounds();
for (var i in bgColors) {
  for (var j in bgColors[i]) {
    Logger.log(bgColors[i][j]);
  }
}

Retorno

String[][]: uma matriz bidimensional de códigos de cores dos planos de fundo.

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

getBandings()

Retorna todas as faixas aplicadas a qualquer célula neste intervalo.

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Sets a range.
const range = sheet.getRange('A1:K50');

// Gets the banding info for the range.
const bandings = range.getBandings();

// Logs the second row color for each banding to the console.
for (let banding of bandings) {
  console.log(banding.getSecondRowColor());
}

Retorno

Banding[]: todas as faixas aplicadas a qualquer célula nesse intervalo.

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

getCell(row, column)

Retorna uma determinada célula dentro de um intervalo.

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

var range = sheet.getRange("B2:D4");

// The row and column here are relative to the range
// getCell(1,1) in this code returns the cell at B2
var cell = range.getCell(1, 1);
Logger.log(cell.getValue());

Parâmetros

NomeTipoDescrição
rowIntegerA linha da célula em relação ao intervalo.
columnIntegerA coluna da célula em relação ao intervalo.

Retorno

Range: um intervalo que contém uma única célula nas coordenadas especificadas.

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

getColumn()

Retorna a posição inicial da coluna para esse intervalo.

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

var range = sheet.getRange("B2:D4");
// Logs "2.0"
Logger.log(range.getColumn());

Retorno

Integer: a posição inicial da coluna do intervalo na 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

getDataRegion()

Retorna uma cópia do intervalo expandido nos quatro Directions cardeais para cobrir todas as células adjacentes com dados. Se o intervalo estiver cercado por células vazias que não incluam células nas diagonais, o intervalo em si será retornado. Isso é semelhante a selecionar o intervalo e digitar Ctrl+A no editor.

// Assume the active spreadsheet is blank.
var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
sheet.getRange("C2").setValue(100);
sheet.getRange("B3").setValue(100);
sheet.getRange("D3").setValue(100);
sheet.getRange("C4").setValue(100);
// Logs "B2:D4"
Logger.log(sheet.getRange("C3").getDataRegion().getA1Notation());

Retorno

Range: a região de dados do intervalo ou um intervalo da planilha inteira.

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

getDataRegion(dimension)

Retorna uma cópia do intervalo expandido Direction.UP e Direction.DOWN se a dimensão especificada for Dimension.ROWS ou Direction.NEXT e Direction.PREVIOUS se a dimensão for Dimension.COLUMNS. A expansão do intervalo é baseada na detecção de dados ao lado do intervalo, que está organizado como uma tabela. O intervalo expandido cobre todas as células adjacentes com dados na dimensão especificada, incluindo os limites da tabela. Se o intervalo original estiver cercado por células vazias ao longo da dimensão especificada, o intervalo em si será retornado. Esse método é semelhante a selecionar o intervalo e digitar Ctrl+Space para colunas ou Shift+Space para linhas no editor.

// Assume the active spreadsheet is blank.
var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
sheet.getRange("C2").setValue(100);
sheet.getRange("B3").setValue(100);
sheet.getRange("D3").setValue(100);
sheet.getRange("C4").setValue(100);
// Logs "C2:C4"
Logger.log(sheet.getRange("C3").getDataRegion(SpreadsheetApp.Dimension.ROWS).getA1Notation());
// Logs "B3:D3"
Logger.log(
    sheet.getRange("C3").getDataRegion(SpreadsheetApp.Dimension.COLUMNS).getA1Notation());

Parâmetros

NomeTipoDescrição
dimensionDimensionA dimensão com a qual expandir o intervalo.

Retorno

Range: a região de dados do intervalo ou um intervalo que cubra cada coluna ou linha estendida pelo intervalo original.

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

getDataSourceFormula()

Retornará DataSourceFormula para a primeira célula no intervalo ou null se a célula não contiver uma fórmula de fonte de dados.

// Opens the spreadsheet file by its ID. If you created your script from a Google Sheets file,
// use SpreadsheetApp.getActiveSpreadsheet().
// TODO(developer): Replace the ID with your own.
const ss = SpreadsheetApp.openById('abc123456');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1 on Sheet1.
const range = sheet.getRange('A1');

// Gets the data source formula from cell A1.
const dataSourceFormula = range.getDataSourceFormula();

// Gets the formula.
const formula = dataSourceFormula.getFormula();

// Logs the formula.
console.log(formula);

Retorno

DataSourceFormula: o DataSourceFormula da célula.

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

getDataSourceFormulas()

Retorna os DataSourceFormulas das células no intervalo.

// Opens the spreadsheet file by its ID. If you created your script from a Google Sheets file,
// use SpreadsheetApp.getActiveSpreadsheet().
// TODO(developer): Replace the ID with your own.
const ss = SpreadsheetApp.openById('abc123456');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:B5 on Sheet1.
const range = sheet.getRange('A1:B5');

// Gets an array of the data source formulas in the range A1:B5.
const dataSourceFormulas = range.getDataSourceFormulas();

// Logs the first formula in the array.
console.log(dataSourceFormulas[0].getFormula());

Retorno

DataSourceFormula[]: uma matriz de DataSourceFormulas.

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

getDataSourcePivotTables()

Recebe todas as tabelas dinâmicas da fonte de dados que cruzam com o intervalo.

// Opens the spreadsheet file by its ID. If you created your script from a Google Sheets file,
// use SpreadsheetApp.getActiveSpreadsheet().
// TODO(developer): Replace the ID with your own.
const ss = SpreadsheetApp.openById('abc123456');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:G50 on Sheet1.
const range = sheet.getRange('A1:G50');

// Gets an array of the data source pivot tables in the range A1:G50.
const dataSourcePivotTables = range.getDataSourcePivotTables();

// Logs the last time that the first pivot table in the array was refreshed.
console.log(dataSourcePivotTables[0].getStatus().getLastRefreshedTime());

Retorno

DataSourcePivotTable[]: uma lista de tabelas dinâmicas 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/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getDataSourceTables()

Extrai todas as tabelas de fonte de dados que cruzam com o intervalo.

// Opens the spreadsheet file by its ID. If you created your script from a Google Sheets file,
// use SpreadsheetApp.getActiveSpreadsheet().
// TODO(developer): Replace the ID with your own.
const ss = SpreadsheetApp.openById('abc123456');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:G50 on Sheet1.
const range = sheet.getRange('A1:G50');

// Gets the first data source table in the range A1:G50.
const dataSourceTable = range.getDataSourceTables()[0];

// Logs the time of the last completed data execution on the data source table.
console.log(dataSourceTable.getStatus().getLastExecutionTime());

Retorno

DataSourceTable[]: uma lista de tabelas 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/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getDataSourceUrl()

Retorna um URL dos dados neste intervalo, que pode ser usado para criar gráficos e consultas.

Code.gs

function doGet() {
  var ss = SpreadsheetApp.openById('1khO6hBWTNNyvyyxvob7aoZTI9ZvlqqASNeq0e29Tw2c');
  var sheet = ss.getSheetByName('ContinentData');
  var range = sheet.getRange('A1:B8');

  var template = HtmlService.createTemplateFromFile('piechart');
  template.dataSourceUrl = range.getDataSourceUrl();
  return template.evaluate();
}

piechart.html

<!DOCTYPE html>
<html>
  <head>
    <!--Load the AJAX API-->
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type="text/javascript">
      // Load the Visualization API and the corechart package.
      google.charts.load('current', {'packages': ['corechart']});

      // Set a callback to run when the Google Visualization API is loaded.
      google.charts.setOnLoadCallback(queryData);

      function queryData() {
        var query = new google.visualization.Query('<?= dataSourceUrl ?>');
        query.send(drawChart);
      }

      // Callback that creates and populates a data table,
      // instantiates the pie chart, passes in the data and
      // draws it.
      function drawChart(response) {
        if (response.isError()) {
          alert('Error: ' + response.getMessage() + ' ' + response.getDetailedMessage());
          return;
        }
        var data = response.getDataTable();

        // Set chart options.
        var options = {
          title: 'Population by Continent',
          width: 400,
          height: 300
        };

        // Instantiate and draw the chart, passing in some options.
        var chart = new google.visualization.PieChart(document.getElementById('chart_div'));
        chart.draw(data, options);
      }
    </script>
  </head>
  <body>
    <!-- Div that holds the pie chart. -->
    <div id="chart_div"></div>
  </body>
</html>

Retorno

String: um URL para esse intervalo como uma fonte de dados que pode ser transmitida para outras APIs, como gráficos.

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

getDataTable()

Retorne os dados dentro desse objeto como uma DataTable.

// Opens the spreadsheet file by its ID. If you created your script from a Google Sheets file,
// use SpreadsheetApp.getActiveSpreadsheet().
// TODO(developer): Replace the ID with your own.
const ss = SpreadsheetApp.openById('abc123456');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:B7 on Sheet1.
const range = sheet.getRange('A1:B7');

// Gets the range A1:B7 as a data table. The values in each column must be of the same type.
const datatable = range.getDataTable();

// Uses the Charts service to build a bar chart from the data table.
// This doesn't build an embedded chart. To do that, use sheet.newChart().addRange() instead.
const chart = Charts.newBarChart()
                  .setDataTable(datatable)
                  .setOption('title', 'Your Chart Title Here')
                  .build();

Retorno

DataTable: os dados como uma tabela de dados.


getDataTable(firstRowIsHeader)

Retorne os dados dentro desse intervalo como uma DataTable.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("A1:B7");

// Calling this method with "true" sets the first line to be the title of the axes
var datatable = range.getDataTable(true);

// Note that this doesn't build an EmbeddedChart, so you can't just use
// Sheet#insertChart(). To do that, use sheet.newChart().addRange() instead.
var chart = Charts.newBarChart()
    .setDataTable(datatable)
    .setOption("title", "Your Title Here")
    .build();

Parâmetros

NomeTipoDescrição
firstRowIsHeaderBooleanDefine se a primeira linha será tratada como cabeçalho.

Retorno

DataTable: os dados como uma tabela 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/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getDataValidation()

Retorna a regra de validação de dados para a célula superior esquerda do intervalo. Se a validação de dados não tiver sido definida na célula, esse método retornará null.

// Log information about the data validation rule for cell A1.
var cell = SpreadsheetApp.getActive().getRange('A1');
var rule = cell.getDataValidation();
if (rule != null) {
  var criteria = rule.getCriteriaType();
  var args = rule.getCriteriaValues();
  Logger.log('The data validation rule is %s %s', criteria, args);
} else {
  Logger.log('The cell does not have a data validation rule.')
}

Retorno

DataValidation: a regra de validação de dados para a célula superior esquerda do intervalo.

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

getDataValidations()

Retorna as regras de validação de dados para todas as células no intervalo. Se a validação de dados não tiver sido definida em uma determinada célula, esse método retornará null para a posição dessa célula na matriz.

// Change existing data validation rules that require a date in 2013 to require a date in 2014.
var oldDates = [new Date('1/1/2013'), new Date('12/31/2013')];
var newDates = [new Date('1/1/2014'), new Date('12/31/2014')];
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange(1, 1, sheet.getMaxRows(), sheet.getMaxColumns());
var rules = range.getDataValidations();

for (var i = 0; i < rules.length; i++) {
  for (var j = 0; j < rules[i].length; j++) {
    var rule = rules[i][j];

    if (rule != null) {
      var criteria = rule.getCriteriaType();
      var args = rule.getCriteriaValues();

      if (criteria == SpreadsheetApp.DataValidationCriteria.DATE_BETWEEN
          && args[0].getTime() == oldDates[0].getTime()
          && args[1].getTime() == oldDates[1].getTime()) {
        // Create a builder from the existing rule, then change the dates.
        rules[i][j] = rule.copy().withCriteria(criteria, newDates).build();
      }
    }
  }
}
range.setDataValidations(rules);

Retorno

DataValidation[][]: uma matriz bidimensional de regras de validação de dados associadas às células no intervalo.

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

getDeveloperMetadata()

Recebe os metadados do desenvolvedor associados a esse intervalo.

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 on Sheet1.
const range = sheet.getRange('2:2');

// Adds metadata to row 2.
range.addDeveloperMetadata('NAME', 'GOOGLE');

// Logs the metadata to console.
for (const metadata of range.getDeveloperMetadata()) {
  console.log(`${metadata.getKey()}: ${metadata.getValue()}`);
}

Retorno

DeveloperMetadata[]: os metadados do desenvolvedor associados a esse intervalo.

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

getDisplayValue()

Retorna o valor exibido da célula superior esquerda do intervalo. O valor é um String. O valor exibido considera a formatação de data, hora e moeda, incluindo formatos aplicados automaticamente pela configuração de localidade da planilha. Células vazias retornam uma string vazia.

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets cell A30 and sets its value to 'Test code.'
const cell = sheet.getRange('A30');
cell.setValue('Test code');

// Gets the value and logs it to the console.
console.log(cell.getDisplayValue());

Retorno

String: o valor exibido nesta célula.

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

getDisplayValues()

Retorna a grade retangular de valores para este intervalo.

Retorna uma matriz bidimensional de valores exibidos, indexados por linha e depois por coluna. Os valores são objetos String. O valor exibido considera a formatação de data, hora e moeda, incluindo formatos aplicados automaticamente pela configuração de localidade da planilha. As células vazias são representadas por uma string vazia na matriz. Lembre-se de que, enquanto um índice de intervalo começa em 1, 1, a matriz JavaScript é indexada em [0][0].

// The code below gets the displayed values for the range C2:G8
// in the active spreadsheet.  Note that this is a JavaScript array.
var values = SpreadsheetApp.getActiveSheet().getRange(2, 3, 6, 4).getDisplayValues();
Logger.log(values[0][0]);

Retorno

String[][]: uma matriz bidimensional de valores.

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

getFilter()

Retorna o filtro na página a que o intervalo pertence ou null se não houver filtro na página.

let ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
// Gets the existing filter on the sheet that the given range belongs to.
let filter = range.getFilter();

Retorno

Filter: o filtro.

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

getFontColorObject()

Retorna a cor da fonte da célula no canto superior esquerdo do intervalo.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getFontColorObject().asRgbColor().asHexString());

Retorno

Color: a cor da fonte da célula superior esquerda do intervalo.

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

getFontColorObjects()

Retorna as cores da fonte das células no intervalo.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getFontColorObjects();

for (var i in results) {
  for (var j in results[i]) {
    Logger.log(results[i][j].asRgbColor().asHexString());
  }
}

Retorno

Color[][]: uma matriz bidimensional de cores de fonte associada às células no intervalo.

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

getFontFamilies()

Retorna as famílias de fontes das células no intervalo.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getFontFamilies();

for (var i in results) {
  for (var j in results[i]) {
    Logger.log(results[i][j]);
  }
}

Retorno

String[][]: uma matriz bidimensional de famílias de fontes associadas às células no intervalo.

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

getFontFamily()

Retorna a família de fontes da célula no canto superior esquerdo do intervalo.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getFontFamily());

Retorno

String: a família de fontes da célula.

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

getFontLine()

Recebe o estilo de linha da célula no canto superior esquerdo do intervalo ('underline', 'line-through' ou 'none').

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getFontLine());

Retorno

String: a linha da fonte.

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

getFontLines()

Recebe o estilo da linha das células no intervalo ('underline', 'line-through' ou 'none').

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getFontLines();

for (var i in results) {
  for (var j in results[i]) {
    Logger.log(results[i][j]);
  }
}

Retorno

String[][]: uma matriz bidimensional de linhas de fonte associadas às células no intervalo.

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

getFontSize()

Retorna o tamanho da fonte em tamanho de ponto da célula no canto superior esquerdo do intervalo.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getFontSize());

Retorno

Integer: o tamanho da fonte em ponto.

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

getFontSizes()

Retorna os tamanhos das fontes das células no intervalo.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getFontSizes();

for (var i in results) {
  for (var j in results[i]) {
    Logger.log(results[i][j]);
  }
}

Retorno

Integer[][]: uma matriz bidimensional de tamanhos de fonte do texto associados às células no intervalo.

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

getFontStyle()

Retorna o estilo da fonte ('italic' ou 'normal') da célula no canto superior esquerdo do intervalo.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getFontStyle());

Retorno

String: o estilo da fonte do texto na célula.

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

getFontStyles()

Retorna os estilos de fonte das células no intervalo.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getFontStyles();

for (var i in results) {
  for (var j in results[i]) {
    Logger.log(results[i][j]);
  }
}

Retorno

String[][]: uma matriz bidimensional de estilos de fonte de texto associados às células no intervalo.

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

getFontWeight()

Retorna a espessura da fonte (normal/negrito) da célula no canto superior esquerdo do intervalo.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getFontWeight());

Retorno

String: a espessura da fonte do texto na célula.

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

getFontWeights()

Retorna as espessuras de fonte das células no intervalo.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getFontWeights();

for (var i in results) {
  for (var j in results[i]) {
    Logger.log(results[i][j]);
  }
}

Retorno

String[][]: uma matriz bidimensional de espessuras de fonte de texto associadas às células no intervalo.

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

getFormula()

Retorna a fórmula (notação A1) para a célula superior esquerda do intervalo ou uma string vazia se a célula estiver vazia ou não contiver uma fórmula.

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

// This assumes you have a function in B5 that sums up
// B2:B4
var range = sheet.getRange("B5");

// Logs the calculated value and the formula
Logger.log("Calculated value: %s Formula: %s",
           range.getValue(),
           range.getFormula());

Retorno

String: a fórmula da célula.

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

getFormulaR1C1()

Retorna a fórmula (notação R1C1) de uma determinada célula ou null se nenhuma.

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

var range = sheet.getRange("B5");
var formula = range.getFormulaR1C1();
Logger.log(formula);

Retorno

String — A fórmula na notação R1C1.

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

getFormulas()

Retorna as fórmulas (notação A1) das células no intervalo. As entradas na matriz 2D são strings vazias para células sem fórmula.

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

var range = sheet.getRange("B5:C6");
var formulas = range.getFormulas();
for (var i in formulas) {
  for (var j in formulas[i]) {
    Logger.log(formulas[i][j]);
  }
}

Retorno

String[][]: uma matriz bidimensional de fórmulas no formato de string.

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

getFormulasR1C1()

Retorna as fórmulas (notação R1C1) das células no intervalo. As entradas na matriz 2D são null para células sem fórmula.

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

var range = sheet.getRange("B5:C6");
var formulas = range.getFormulasR1C1();
for (var i in formulas) {
  for (var j in formulas[i]) {
    Logger.log(formulas[i][j]);
  }
}

Retorno

String[][]: uma matriz bidimensional de fórmulas na notação R1C1.

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

getGridId()

Retorna o ID da grade da página pai do intervalo. Os IDs são valores int aleatórios e não negativos.

// Log the grid ID of the first sheet (by tab position) in the spreadsheet.
var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getGridId());

Retorno

Integer: o ID da grade da página mãe.

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

getHeight()

Retorna a altura do intervalo.

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

var range = sheet.getRange("B2:D4");
// logs 3.0
Logger.log(range.getHeight());

Retorno

Integer: a altura do intervalo.

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

getHorizontalAlignment()

Retorna o alinhamento horizontal do texto (esquerda/centrado/direita) da célula no canto superior esquerdo do intervalo.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getHorizontalAlignment());

Retorno

String: o alinhamento horizontal do texto na célula.

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

getHorizontalAlignments()

Retorna os alinhamentos horizontais das células no intervalo.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getHorizontalAlignments();

for (var i in results) {
  for (var j in results[i]) {
    Logger.log(results[i][j]);
  }
}

Retorno

String[][]: uma matriz bidimensional de alinhamentos horizontais de texto associados às células no intervalo.

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

getLastColumn()

Retorna a posição da coluna final.

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

var range = sheet.getRange("B2:D4");
// Logs "4.0"
Logger.log(range.getLastColumn());

Retorno

Integer: a posição da coluna final do intervalo na 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

getLastRow()

Retorna a posição da linha final.

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

var range = sheet.getRange("B2:D4");
// Logs "4.0"
Logger.log(range.getLastRow());

Retorno

Integer: a posição da linha final do intervalo na 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

getMergedRanges()

Retorna uma matriz de objetos Range que representam células mescladas que estão totalmente dentro do intervalo atual ou contêm pelo menos uma célula no intervalo atual.

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

var range = sheet.getRange("A1:B3");

var mergedRanges = range.getMergedRanges();
for (var i = 0; i < mergedRanges.length; i++) {
  Logger.log(mergedRanges[i].getA1Notation());
  Logger.log(mergedRanges[i].getDisplayValue());
}

Retorno

Range[]: uma matriz de objetos Range, representando células mescladas em sobreposição ao intervalo.


getNextDataCell(direction)

Começando na célula na primeira coluna e linha do intervalo, retorna a próxima célula na direção determinada, que é a borda de um intervalo contíguo de células com dados ou a célula na borda da planilha naquela direção. Isso equivale a digitar Ctrl+[arrow key] no editor.

// Assume the active spreadsheet is blank.
var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var range = sheet.getRange("C3:E5");
// Logs "C1"
Logger.log(range.getNextDataCell(SpreadsheetApp.Direction.UP).getA1Notation());

Parâmetros

NomeTipoDescrição
directionDirectionA direção em que encontrar a próxima célula de borda da região de dados.

Retorno

Range: a célula de borda da região de dados ou a célula na borda 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

getNote()

Retorna a nota associada ao intervalo especificado.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getNote());

Retorno

String: a nota associada à célula especificada.

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

getNotes()

Retorna as notas associadas às células no intervalo.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getNotes();

for (var i in results) {
  for (var j in results[i]) {
    Logger.log(results[i][j]);
  }
}

Retorno

String[][]: uma matriz bidimensional de anotações associadas a células no intervalo.

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

getNumColumns()

Retorna o número de colunas nesse intervalo.

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

var range = sheet.getRange("B2:D5");
Logger.log(range.getNumColumns());

Retorno

Integer: o número de colunas no intervalo.

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

getNumRows()

Retorna o número de linhas neste intervalo.

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

var range = sheet.getRange("B2:D5");
Logger.log(range.getNumRows());

Retorno

Integer: o número de linhas no intervalo.

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

getNumberFormat()

Define a formatação de número ou data da célula superior esquerda de determinado intervalo. Os padrões de formato retornados estão descritos na documentação da API Sheets.

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

var cell = sheet.getRange("C4");
Logger.log(cell.getNumberFormat());

Retorno

String: o formato de número da célula superior esquerda do intervalo.

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

getNumberFormats()

Retorna os formatos de número ou data das células no intervalo. Os padrões de formato retornados estão descritos na documentação da API Sheets.

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

var range = sheet.getRange("B5:C6");
var formats = range.getNumberFormats();
for (var i in formats) {
  for (var j in formats[i]) {
    Logger.log(formats[i][j]);
  }
}

Retorno

String[][]: uma matriz bidimensional de formatos numéricos.

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

getRichTextValue()

Retorna o valor de rich text da célula superior esquerda do intervalo ou null se o valor da célula não for texto.

// Gets the Rich Text value of cell D4.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("D4:F6");
var richText = range.getRichTextValue();
console.log(richText.getText());

Retorno

RichTextValue: o valor de rich text da célula superior esquerda do intervalo ou null se o valor da célula não for texto.

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

getRichTextValues()

Retorna os valores de rich text das células no intervalo.

// Gets the Rich Text values for all cells in range B5:C6
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B5:C6");
var values = range.getRichTextValues();

for (var i = 0; i < values.length; i++) {
  for (var j = 0; j < values[i].length; j++) {
    console.log(values[i][j].getText());
  }
}

Retorno

RichTextValue[][]: uma matriz bidimensional de valores rich text.

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

getRow()

Retorna a posição da linha para esse intervalo. Idêntico a getRowIndex().

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

var range = sheet.getRange("B2");
Logger.log(range.getRow());

Retorno

Integer: a posição da linha do intervalo.

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

getRowIndex()

Retorna a posição da linha para esse intervalo. Idêntico a getRow().

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

var range = sheet.getRange("B2");
Logger.log(range.getRowIndex());

Retorno

Integer: a posição da linha do intervalo.

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

Veja também


getSheet()

Retorna a página a que o intervalo pertence.

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');

// Gets the sheet that the range belongs to.
const rangeSheet = range.getSheet();

// Gets the sheet name and logs it to the console.
console.log(rangeSheet.getName());

Retorno

Sheet: a página a que o intervalo pertence.

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

getTextDirection()

Retorna a direção do texto para a célula superior esquerda do intervalo. Retornará null se a direção do texto da célula for determinada com detecção automática.

// Get the text direction of cell B1.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B1:D4");
Logger.log(range.getTextDirection());

Retorno

TextDirection: a direção do texto da célula superior esquerda no intervalo.

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

getTextDirections()

Retorna as direções do texto das células no intervalo. As entradas na matriz 2D são null para células que usam a detecção automática.

// Get the text directions for all cells in range B5:C6
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B5:C6");
var directions = range.getTextDirections();

for (var i = 0; i < directions.length; i++) {
  for (var j = 0; j < directions[i].length; j++) {
    Logger.log(directions[i][j]);
  }
}

Retorno

TextDirection[][]: uma matriz bidimensional de direções de texto.

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

getTextRotation()

Retorna as configurações de rotação de texto para a célula superior esquerda do intervalo.

// Log the text rotation settings for a cell.
var sheet = SpreadsheetApp.getActiveSheet();

var cell = sheet.getRange("A1");
Logger.log(cell.getTextRotation());

Retorno

TextRotation: as configurações de rotação do texto.

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

getTextRotations()

Retorna as configurações de rotação do texto para as células no intervalo.

var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B2:D4");

var results = range.getTextRotations();

for (var i in results) {
  for (var j in results[i]) {
    var rotation = results[i][j];
    Logger.log("Cell [%s, %s] has text rotation: %v", i, j, rotation);
  }
}

Retorno

TextRotation[][]: uma matriz bidimensional de rotações de texto associadas às células no intervalo.

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

getTextStyle()

Retorna o estilo de texto da célula superior esquerda do intervalo.

// Get the text style of cell D4.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("D4:F6");
var style = range.getTextStyle();
Logger.log(style);

Retorno

TextStyle: o estilo de texto da célula superior esquerda no intervalo.

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

getTextStyles()

Retorna os estilos de texto das células no intervalo.

// Get the text styles for all cells in range B5:C6
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B5:C6");
var styles = range.getTextStyles();

for (var i = 0; i < styles.length; i++) {
  for (var j = 0; j < styles[i].length; j++) {
    Logger.log(styles[i][j]);
  }
}

Retorno

TextStyle[][]: uma matriz bidimensional de estilos de texto.

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

getValue()

Retorna o valor da célula superior esquerda do intervalo. O valor pode ser do tipo Number, Boolean, Date ou String, dependendo do valor da célula. Células vazias retornam uma string vazia.

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');

// Gets the value of the top-left cell in the range and logs it to the console.
console.log(range.getValue());

Retorno

Object: o valor nesta célula.

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

getValues()

Retorna a grade retangular de valores para este intervalo.

Retorna uma matriz bidimensional de valores, indexados por linha e depois por coluna. Os valores podem ser do tipo Number, Boolean, Date ou String, dependendo do valor da célula. As células vazias são representadas por uma string vazia na matriz. Lembre-se de que, embora um índice de intervalo comece em 1, 1, a matriz JavaScript é indexada em [0][0].

// The code below gets the values for the range C2:G8
// in the active spreadsheet.  Note that this is a JavaScript array.
var values = SpreadsheetApp.getActiveSheet().getRange(2, 3, 6, 4).getValues();
Logger.log(values[0][0]);
Em apps da Web, o valor Date não é um parâmetro legal. getValues() não vai retornar dados para um app da Web se o intervalo tiver uma célula com um valor Date. Em vez disso, transforme todos os valores recuperados da página em um primitivo de JavaScript compatível, como Number, Boolean ou String.

Retorno

Object[][]: uma matriz bidimensional de valores.

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

getVerticalAlignment()

Retorna o alinhamento vertical (superior/meio/inferior) da célula no canto superior esquerdo do intervalo.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getVerticalAlignment());

Retorno

String: o alinhamento vertical do texto na célula.

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

getVerticalAlignments()

Retorna os alinhamentos verticais das células no intervalo.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getVerticalAlignments();

for (var i in results) {
  for (var j in results[i]) {
    Logger.log(results[i][j]);
  }
}

Retorno

String[][]: uma matriz bidimensional de alinhamentos verticais de texto associado a células no intervalo.

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

getWidth()

Retorna a largura do intervalo em colunas.

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');

// Gets the width of the range in number of columns and logs it to the console.
console.log(range.getWidth());

Retorno

Integer: o número de colunas no intervalo.

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

getWrap()

Retorna se o texto na célula é agrupado. Para ter uma estratégia de encapsulamento mais granular, use getWrapStrategy().

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getWrap());

Retorno

Boolean: se o texto da célula é agrupado ou não.

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

getWrapStrategies()

Retorna as estratégias de ajuste de texto para as células no intervalo.

// Get the text wrapping strategies for all cells in range B5:C6
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B5:C6");
var strategies = range.getWrapStrategies();

for (var i = 0; i < strategies.length; i++) {
  for (var j = 0; j < strategies[i].length; j++) {
    Logger.log(strategies[i][j]);
  }
}

Retorno

WrapStrategy[][]: uma matriz bidimensional de estratégias de ajuste de texto.

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

getWrapStrategy()

Retorna a estratégia de ajuste de texto da célula superior esquerda do intervalo.

// Get the text wrapping strategy of cell B1.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B1:D4");
Logger.log(range.getWrapStrategy());

Retorno

WrapStrategy: a estratégia de ajuste de texto da célula superior esquerda no intervalo.

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

getWraps()

Retorna se o texto nas células é ajustado. Para ter uma estratégia de encapsulamento mais granular, use getWrapStrategies().

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getVerticalAlignments();

for (var i in results) {
  for (var j in results[i]) {
    var isWrapped = results[i][j];
    if (isWrapped) {
       Logger.log("Cell [%s, %s] has wrapped text", i, j);
    }
  }
}

Retorno

Boolean[][]: uma matriz bidimensional de alinhamentos verticais de texto associado a células no intervalo.

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

insertCells(shiftDimension)

Insere células vazias neste intervalo. As novas células mantêm qualquer formatação presente nas células que anteriormente ocupavam esse intervalo. Os dados existentes na página ao longo da dimensão fornecida são deslocados do intervalo inserido.

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

var range = sheet.getRange("A1:D10");
range.insertCells(SpreadsheetApp.Dimension.COLUMNS);

Parâmetros

NomeTipoDescrição
shiftDimensionDimensionA dimensão na qual os dados existentes serão transferidos.

Retorno

Range: esse intervalo para encadeamento.

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

insertCheckboxes()

Insere caixas de seleção em cada célula do intervalo, configuradas com true para marcada e false para desmarcada. Define o valor de todas as células no intervalo como false.

var range = SpreadsheetApp.getActive().getRange('A1:B10');

// Inserts checkboxes into each cell in the range A1:B10 configured with 'true' for checked
// and 'false' for unchecked. Also, sets the value of each cell in the range A1:B10 to 'false'.
range.insertCheckboxes();

Retorno

Range: esse intervalo para encadeamento.

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

insertCheckboxes(checkedValue)

Insere caixas de seleção em cada célula do intervalo, configuradas com um valor personalizado para marcado e a string vazia para desmarcada. Define o valor de cada célula no intervalo como a string vazia.

var range = SpreadsheetApp.getActive().getRange('A1:B10');

// Inserts checkboxes into each cell in the range A1:B10 configured with 'yes' for checked
// and the empty string for unchecked. Also, sets the value of each cell in the range A1:B10 to
//  the empty string.
range.insertCheckboxes('yes');

Parâmetros

NomeTipoDescrição
checkedValueObjectO valor marcado para a validação de dados da caixa de seleção.

Retorno

Range: esse intervalo para encadeamento.

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

insertCheckboxes(checkedValue, uncheckedValue)

Insere caixas de seleção em cada célula do intervalo, configuradas com valores personalizados para os estados marcado e desmarcado. Define o valor de cada célula no intervalo como o valor personalizado não selecionado.

var range = SpreadsheetApp.getActive().getRange('A1:B10');

// Inserts checkboxes into each cell in the range A1:B10 configured with 'yes' for checked
// and 'no' for unchecked. Also, sets the value of each cell in the range A1:B10 to 'no'.
range.insertCheckboxes('yes', 'no');

Parâmetros

NomeTipoDescrição
checkedValueObjectO valor marcado para a validação de dados da caixa de seleção.
uncheckedValueObjectO valor não marcado para a validação de dados da caixa de seleção.

Retorno

Range: esse intervalo para encadeamento.

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

isBlank()

Retorna true se o intervalo estiver totalmente em branco.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.isBlank());

Retorno

Boolean: true se o intervalo estiver em branco. Caso contrário, false.

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

isChecked()

Retorna se todas as células no intervalo têm seu estado de caixa de seleção como "marcada". Retornará null se algumas células estiverem marcadas e as outras desmarcadas, ou se algumas células não tiverem validação de dados de caixas de seleção.

var range = SpreadsheetApp.getActive().getRange('A1:A3');

// Inserts checkboxes and sets each cell value to 'no' in the range A1:A3.
range.insertCheckboxes('yes', 'no');

var range1 = SpreadsheetApp.getActive().getRange('A1');
range1.setValue('yes');
// Sets the value of isRange1Checked as true as it contains the checked value.
var isRange1Checked = range1.isChecked();

var range2 = SpreadsheetApp.getActive().getRange('A2');
range2.setValue('no');
// Sets the value of isRange2Checked as false as it contains the unchecked value.
var isRange2Checked = range2.isChecked();

var range3 = SpreadsheetApp.getActive().getRange('A3');
range3.setValue('random');
// Sets the value of isRange3Checked as null, as it contains an invalid checkbox value.
var isRange3Checked = range3.isChecked();

Retorno

Boolean: true, se todas as células no intervalo estiverem marcadas, false se todas as células no intervalo estiverem desmarcadas ou null se alguma das células estiver desmarcada ou não tiver validação de dados da caixa de seleção.

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

isEndColumnBounded()

Determina se o fim do intervalo está vinculado a uma coluna específica. Por exemplo, para os intervalos A1:B10 ou B:B, que estão vinculados a colunas no final do intervalo, esse método retorna true. Para os intervalos 3:7 ou A1:5, que estão vinculados apenas a linhas específicas no final, esse método retorna false.

 // Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');

// Determines if the end of the range is bound to a particular column and logs it to the
// console.
console.log(range.isEndColumnBounded());

Retorno

Boolean: true se o fim do intervalo estiver vinculado a uma coluna específica. Caso contrário, false.

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

isEndRowBounded()

Determina se o fim do intervalo está vinculado a uma linha específica. Por exemplo, para os intervalos A1:B10 ou 3:7, que estão vinculados a linhas no final do intervalo, esse método retorna true. Para os intervalos B:B ou A1:C, que estão vinculados apenas a colunas específicas no final do intervalo, esse método retorna false.

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');

// Determines if the end of the range is bound to a particular row and logs it to the console.
console.log(range.isEndRowBounded());

Retorno

Boolean: true se o fim do intervalo estiver vinculado a uma linha específica. Caso contrário, false.

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

isPartOfMerge()

Retornará true se as células no intervalo atual se sobrepuserem a qualquer célula mesclada.

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

var range = sheet.getRange("A1:B3");

// True if any of the cells in A1:B3 is included in a merge.
var isPartOfMerge = range.isPartOfMerge();

Retorno

Boolean: true se o intervalo se sobrepuser a células mescladas. Caso contrário, retorna false.


isStartColumnBounded()

Determina se o início do intervalo está vinculado a uma coluna específica. Por exemplo, para os intervalos A1:B10 ou B:B, que estão vinculados a colunas no início do intervalo, esse método retorna true. Para o intervalo 3:7, que está vinculado apenas a uma linha no início do intervalo, esse método retorna false.

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');

// Determines if the start of the range is bound to a particular column and logs it to the
// console.
console.log(range.isStartColumnBounded());

Retorno

Boolean: true se o início do intervalo estiver vinculado a uma coluna específica. Caso contrário, false.

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

isStartRowBounded()

Determina se o início do intervalo está vinculado a uma linha específica. Por exemplo, para os intervalos A1:B10 ou 3:7, que estão vinculados a linhas no início do intervalo, esse método retorna true. Para o intervalo B:B, que está vinculado apenas a uma coluna específica no início do intervalo, esse método retorna false.

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');

// Determines if the start of the range is bound to a particular row and logs it to the
// console.
console.log(range.isStartRowBounded());

Retorno

Boolean: true se o início do intervalo estiver vinculado a uma linha específica. Caso contrário, false.

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

merge()

Mescla as células do intervalo em um único bloco.

var sheet = SpreadsheetApp.getActiveSheet();

// The code below 2-dimensionally merges the cells in A1 to B3
sheet.getRange('A1:B3').merge();

Retorno

Range: esse intervalo para encadeamento.

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

mergeAcross()

Mescle as células do intervalo de acordo com as colunas dele.

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

// The code below merges cells C5:E5 into one cell
var range1 = sheet.getRange("C5:E5");
range1.mergeAcross();

// The code below creates 2 horizontal cells, F5:H5 and F6:H6
var range2 = sheet.getRange("F5:H6");
range2.mergeAcross();

Retorno

Range: esse intervalo para encadeamento.

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

mergeVertically()

Mescla as células no intervalo.

var sheet = SpreadsheetApp.getActiveSheet();

// The code below vertically merges the cells in A1 to A10
sheet.getRange('A1:A10').mergeVertically();

// The code below creates 3 merged columns: B1 to B10, C1 to C10, and D1 to D10
sheet.getRange('B1:D10').mergeVertically();

Retorno

Range: esse intervalo para encadeamento.

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

moveTo(target)

Recorte e cole (formatar e valores) deste intervalo para o intervalo de destino.

// The code below moves the first 5 columns over to the 6th column
var sheet = SpreadsheetApp.getActiveSheet()
sheet.getRange("A1:E").moveTo(sheet.getRange("F1"));

Parâmetros

NomeTipoDescrição
targetRangeUm intervalo de destino para onde copiar esse intervalo. Apenas a posição da célula superior esquerda é relevante.

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

offset(rowOffset, columnOffset)

Retorna um novo intervalo que é deslocado desse intervalo pelo número fornecido de linhas e colunas (que pode ser negativo). O novo intervalo tem o mesmo tamanho do original.

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

var cell = sheet.getRange("A1");

// newCell references B2
var newCell = cell.offset(1, 1);

Parâmetros

NomeTipoDescrição
rowOffsetIntegerO número de linhas a partir da célula superior esquerda do intervalo. Valores negativos representam as linhas acima da célula superior esquerda do intervalo.
columnOffsetIntegerO número de colunas à direita da célula superior esquerda do intervalo. Valores negativos representam as colunas à esquerda da célula superior esquerda do intervalo.

Retorno

Range: esse intervalo para encadeamento.


offset(rowOffset, columnOffset, numRows)

Retorna um novo intervalo relativo ao intervalo atual, cujo ponto superior esquerdo é deslocado do intervalo atual pelas linhas e colunas fornecidas e com a altura especificada nas células.

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

var cell = sheet.getRange("A1");

// newCell references B2:B3
var newRange = cell.offset(1, 1, 2);

Parâmetros

NomeTipoDescrição
rowOffsetIntegerO número de linhas a partir da célula superior esquerda do intervalo. Valores negativos representam as linhas acima da célula superior esquerda do intervalo.
columnOffsetIntegerO número de colunas à direita da célula superior esquerda do intervalo. Valores negativos representam as colunas à esquerda da célula superior esquerda do intervalo.
numRowsIntegerA altura em linhas do novo intervalo.

Retorno

Range: esse intervalo para encadeamento.


offset(rowOffset, columnOffset, numRows, numColumns)

Retorna um novo intervalo relativo ao intervalo atual, cujo ponto superior esquerdo é deslocado do intervalo atual pelas linhas e colunas fornecidas e com a altura e largura indicadas nas células.

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

var cell = sheet.getRange("A1");

// newCell references B2:C3
var newRange = cell.offset(1, 1, 2, 2);

Parâmetros

NomeTipoDescrição
rowOffsetIntegerO número de linhas a partir da célula superior esquerda do intervalo. Valores negativos representam as linhas acima da célula superior esquerda do intervalo.
columnOffsetIntegerO número de colunas à direita da célula superior esquerda do intervalo. Valores negativos representam as colunas à esquerda da célula superior esquerda do intervalo.
numRowsIntegerA altura em linhas do novo intervalo.
numColumnsIntegerA largura em colunas do novo intervalo.

Retorno

Range: esse intervalo para encadeamento.


protect()

Cria um objeto que pode proteger o intervalo de ser editado, exceto por usuários que tenham permissão. Até que o script mude a lista de editores do intervalo (chamando Protection.removeEditor(emailAddress), Protection.removeEditor(user), Protection.removeEditors(emailAddresses), Protection.addEditor(emailAddress), Protection.addEditor(user), Protection.addEditors(emailAddresses) ou definindo um novo valor para Protection.setDomainEdit(editable)), as permissões espelham as da própria planilha, o que significa que o intervalo permanece desprotegido. Se o intervalo já estiver protegido, esse método criará um novo intervalo protegido que se sobrepõe ao existente. Se uma célula for protegida por vários intervalos protegidos e um deles impedir que um determinado usuário a edite, esse usuário não terá permissão para editá-la.

// Protect range A1:B10, then remove all other users from the list of editors.
var ss = SpreadsheetApp.getActive();
var range = ss.getRange('A1:B10');
var protection = range.protect().setDescription('Sample protected range');

// Ensure the current user is an editor before removing others. Otherwise, if the user's edit
// permission comes from a group, the script throws an exception upon removing the group.
var me = Session.getEffectiveUser();
protection.addEditor(me);
protection.removeEditors(protection.getEditors());
if (protection.canDomainEdit()) {
  protection.setDomainEdit(false);
}

Retorno

Protection: um objeto que representa as configurações de proteção.

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

randomize()

Randomiza a ordem das linhas no intervalo fornecido.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("A1:C7");

// Randomizes the range
range.randomize();

Retorno

Range: esse intervalo para encadeamento.

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

removeCheckboxes()

Remove todas as caixas de seleção do intervalo. Limpa a validação de dados de cada célula e também limpa o valor dela se a célula contiver o valor marcado ou desmarcado.

var range = SpreadsheetApp.getActive().getRange('A1:B10');

// Inserts checkboxes and sets each cell value to 'no' in the range A1:B10.
range.insertCheckboxes('yes', 'no');

var range1 = SpreadsheetApp.getActive().getRange('A1');
range1.setValue('yes');
// Removes the checkbox data validation in cell A1 and clears its value.
range1.removeCheckboxes();

var range2 = SpreadsheetApp.getActive().getRange('A2');
range2.setValue('random');
// Removes the checkbox data validation in cell A2 but does not clear its value.
range2.removeCheckboxes();

Retorno

Range: esse intervalo para encadeamento.

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

removeDuplicates()

Remove as linhas dentro desse intervalo que contêm valores duplicados de valores em qualquer linha anterior. Linhas com valores idênticos, mas letras maiúsculas, formatação ou fórmulas diferentes, são consideradas duplicadas. Esse método também remove linhas duplicadas ocultas da visualização (por exemplo, devido a um filtro). O conteúdo fora desse intervalo não é removido.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B1:D7");

// Remove duplicate rows in the range.
range.removeDuplicates();

Retorno

Range: o intervalo resultante após a remoção de duplicatas. O tamanho do intervalo é reduzido em uma linha para cada linha removida.

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

removeDuplicates(columnsToCompare)

Remove as linhas dentro desse intervalo que contêm valores nas colunas especificadas que são cópias de valores de qualquer linha anterior. Linhas com valores idênticos, mas letras maiúsculas/minúsculas, formatação ou fórmulas diferentes, são consideradas duplicadas. Esse método também remove linhas duplicadas ocultas da visualização (por exemplo, devido a um filtro). O conteúdo fora desse intervalo não é removido.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B1:D7");

// Remove rows which have duplicate values in column B.
range.removeDuplicates([2]);

// Remove rows which have duplicate values in both columns B and D.
range.removeDuplicates([2,4]);

Parâmetros

NomeTipoDescrição
columnsToCompareInteger[]As colunas a serem analisadas em busca de valores duplicados. Se nenhuma coluna for fornecida, todas as colunas serão analisadas em busca de duplicatas.

Retorno

Range: o intervalo resultante após a remoção de duplicatas. O tamanho do intervalo é reduzido em uma linha para cada linha removida.

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

setBackground(color)

Define a cor do plano de fundo de todas as células no intervalo na notação CSS (como '#ffffff' ou 'white').

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

var range = sheet.getRange("B2:D5");
range.setBackground("red");

Parâmetros

NomeTipoDescrição
colorStringUm código de cor na notação CSS (como '#ffffff' ou 'white'). Um valor null redefine a cor.

Retorno

Range: esse intervalo para encadeamento.

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

setBackgroundObject(color)

Define a cor de fundo de todas as células no intervalo.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var bgColor = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.BACKGROUND)
    .build();

var range = sheet.getRange("B2:D5");
range.setBackgroundObject(bgColor);

Parâmetros

NomeTipoDescrição
colorColorA cor do plano de fundo a ser definida. O valor null redefine a cor do plano de fundo.

Retorno

Range: esse intervalo para encadeamento.

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

setBackgroundObjects(color)

Define uma grade retangular de cores de fundo (deve corresponder às dimensões deste intervalo).

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

var colorAccent1 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1)
    .build();
var colorAccent2 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT2)
    .build();
var colorAccent3 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT3)
    .build();
var colorAccent4 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT4)
    .build();

var colors = [
  [colorAccent1, colorAccent2],
  [colorAccent3, colorAccent4]
];

var cell = sheet.getRange("B5:C6");
cell.setBackgroundObjects(colors);

Parâmetros

NomeTipoDescrição
colorColor[][]Uma matriz bidimensional de cores. Os valores null redefinem a cor.

Retorno

Range: esse intervalo para encadeamento.

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

setBackgroundRGB(red, green, blue)

Define o plano de fundo com a cor especificada usando valores RGB (números inteiros entre 0 e 255).

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

var cell = sheet.getRange("B2");

// Sets the background to white
cell.setBackgroundRGB(255, 255, 255);

// Sets the background to red
cell.setBackgroundRGB(255, 0, 0);

Parâmetros

NomeTipoDescrição
redIntegerO valor vermelho na notação RGB.
greenIntegerO valor verde na notação RGB.
blueIntegerO valor azul na notação RGB.

Retorno

Range: esse intervalo para encadeamento.

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

setBackgrounds(color)

Define uma grade retangular de cores de fundo (deve corresponder às dimensões deste intervalo). As cores estão em notação CSS (como '#ffffff' ou 'white').

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

var colors = [
  ["red", "white", "blue"],
  ["#FF0000", "#FFFFFF", "#0000FF"] // These are the hex equivalents
];

var cell = sheet.getRange("B5:D6");
cell.setBackgrounds(colors);

Parâmetros

NomeTipoDescrição
colorString[][]Uma matriz bidimensional de cores na notação CSS (como '#ffffff' ou 'white'). Os valores null redefinem a cor.

Retorno

Range: esse intervalo para encadeamento.

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

setBorder(top, left, bottom, right, vertical, horizontal)

Define a propriedade da borda. Os valores válidos são true (ativado), false (desativado) e null (sem alterações).

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

var cell = sheet.getRange("B2");
// Sets borders on the top and bottom, but leaves the left and right unchanged
cell.setBorder(true, null, true, null, false, false);

Parâmetros

NomeTipoDescrição
topBooleantrue para borda, false para nenhuma e null para nenhuma alteração.
leftBooleantrue para borda, false para nenhuma e null para nenhuma alteração.
bottomBooleantrue para borda, false para nenhuma e null para nenhuma alteração.
rightBooleantrue para borda, false para nenhuma e null para nenhuma alteração.
verticalBooleantrue para bordas verticais internas, false para nenhuma e null para nenhuma mudança.
horizontalBooleantrue para bordas horizontais internas, false para nenhuma e null para nenhuma mudança.

Retorno

Range: esse intervalo para encadeamento.

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

setBorder(top, left, bottom, right, vertical, horizontal, color, style)

Define a propriedade da borda com cor e/ou estilo. Os valores válidos são true (ativado), false (desativado) e null (sem alterações). Para cores, use Cor na notação CSS (como '#ffffff' ou 'white').

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

var cell = sheet.getRange("B2");
// Sets borders on the top and bottom, but leaves the left and right unchanged
// Also sets the color to "red", and the border to "DASHED".
cell.setBorder(true, null, true, null, false, false, "red", SpreadsheetApp.BorderStyle.DASHED);

Parâmetros

NomeTipoDescrição
topBooleantrue para borda, false para nenhuma e null para nenhuma alteração.
leftBooleantrue para borda, false para nenhuma e null para nenhuma alteração.
bottomBooleantrue para borda, false para nenhuma e null para nenhuma alteração.
rightBooleantrue para borda, false para nenhuma e null para nenhuma alteração.
verticalBooleantrue para bordas verticais internas, false para nenhuma e null para nenhuma mudança.
horizontalBooleantrue para bordas horizontais internas, false para nenhuma e null para nenhuma mudança.
colorStringUma cor na notação CSS (como '#ffffff' ou 'white') e null para a cor padrão (preto).
styleBorderStyleUm estilo para as bordas, null para o estilo padrão (sólido).

Retorno

Range: esse intervalo para encadeamento.

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

setDataValidation(rule)

Define uma regra de validação de dados para todas as células no intervalo.

// Set the data validation rule for cell A1 to require a value from B1:B10.
var cell = SpreadsheetApp.getActive().getRange('A1');
var range = SpreadsheetApp.getActive().getRange('B1:B10');
var rule = SpreadsheetApp.newDataValidation().requireValueInRange(range).build();
cell.setDataValidation(rule);

Parâmetros

NomeTipoDescrição
ruleDataValidationA regra de validação de dados que será definida ou null para remover a validação de dados.

Retorno

Range: esse intervalo para encadeamento.

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

setDataValidations(rules)

Define as regras de validação de dados para todas as células no intervalo. Esse método usa uma matriz bidimensional de validações de dados, indexada por linha e depois por coluna. As dimensões da matriz precisam corresponder às dimensões do intervalo.

// Set the data validation rules for Sheet1!A1:B5 to require a value from Sheet2!A1:A10.
var destinationRange = SpreadsheetApp.getActive().getSheetByName('Sheet1').getRange('A1:B5');
var sourceRange = SpreadsheetApp.getActive().getSheetByName('Sheet2').getRange('A1:A10');
var rule = SpreadsheetApp.newDataValidation().requireValueInRange(sourceRange).build();
var rules = destinationRange.getDataValidations();
for (var i = 0; i < rules.length; i++) {
  for (var j = 0; j < rules[i].length; j++) {
    rules[i][j] = rule;
  }
}
destinationRange.setDataValidations(rules);

Parâmetros

NomeTipoDescrição
rulesDataValidation[][]Uma matriz bidimensional de regras de validação de dados a serem definidas. Os valores null removem a validação de dados.

Retorno

Range: esse intervalo para encadeamento.

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

setFontColor(color)

Define a cor da fonte na notação CSS (como '#ffffff' ou 'white').

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

var cell = sheet.getRange("B2");
cell.setFontColor("red");

Parâmetros

NomeTipoDescrição
colorStringA cor da fonte na notação CSS (como '#ffffff' ou 'white'). Um valor null redefine a cor.

Retorno

Range: esse intervalo para encadeamento.

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

setFontColorObject(color)

Define a cor da fonte do intervalo especificado.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var color = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.TEXT)
    .build();

var cell = sheet.getRange("B2");
cell.setFontColor(color);

Parâmetros

NomeTipoDescrição
colorColorA cor da fonte a ser definida (um valor null redefine a cor).

Retorno

Range: esse intervalo para encadeamento.

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

setFontColorObjects(colors)

Define uma grade retangular de cores de fonte (deve corresponder às dimensões deste intervalo).

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

var colorAccent1 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1)
    .build();
var colorAccent2 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT2)
    .build();
var colorAccent3 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT3)
    .build();
var colorAccent4 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT4)
    .build();

var colors = [
  [colorAccent1, colorAccent2],
  [colorAccent3, colorAccent4]
];

var cell = sheet.getRange("B5:C6");
cell.setFontColorObjects(colors);

Parâmetros

NomeTipoDescrição
colorsColor[][]Uma matriz bidimensional de cores. Os valores null redefinem a cor da fonte.

Retorno

Range: esse intervalo para encadeamento.

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

setFontColors(colors)

Define uma grade retangular de cores de fonte (deve corresponder às dimensões deste intervalo). As cores estão em notação CSS (como '#ffffff' ou 'white').

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

var colors = [
  ["red", "white", "blue"],
  ["#FF0000", "#FFFFFF", "#0000FF"] // These are the hex equivalents
];

var cell = sheet.getRange("B5:D6");
cell.setFontColors(colors);

Parâmetros

NomeTipoDescrição
colorsObject[][]Uma matriz bidimensional de cores na notação CSS (como '#ffffff' ou 'white'). Os valores null redefinem a cor.

Retorno

Range: esse intervalo para encadeamento.

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

setFontFamilies(fontFamilies)

Define uma grade retangular de famílias de fontes (deve corresponder às dimensões desse intervalo). Exemplos de famílias de fontes são "Arial" ou "Helvetica".

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

var fonts = [
  ["Arial", "Helvetica", "Verdana"],
  ["Courier New", "Arial", "Helvetica]
];

var cell = sheet.getRange("B2:D3");
cell.setFontFamilies(fonts);

Parâmetros

NomeTipoDescrição
fontFamiliesObject[][]Uma matriz bidimensional de famílias de fontes. Os valores null redefinem a família de fontes.

Retorno

Range: esse intervalo para encadeamento.

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

setFontFamily(fontFamily)

Define a família de fontes, como "Arial" ou "Helvetica".

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

var cell = sheet.getRange("B2");
cell.setFontFamily("Helvetica");

Parâmetros

NomeTipoDescrição
fontFamilyStringA família de fontes a ser definida. Um valor null redefine a família de fontes.

Retorno

Range: esse intervalo para encadeamento.

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

setFontLine(fontLine)

Define o estilo da linha de fonte do intervalo especificado ('underline', 'line-through' ou 'none').

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

var cell = sheet.getRange("B2");
cell.setFontLine("line-through");

Parâmetros

NomeTipoDescrição
fontLineStringO estilo de linha da fonte, 'underline', 'line-through' ou 'none'. Um valor null redefine o estilo da linha da fonte.

Retorno

Range: esse intervalo para encadeamento.

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

setFontLines(fontLines)

Define uma grade retangular de estilos de linha (deve corresponder às dimensões deste intervalo).

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

// The size of the two-dimensional array must match the size of the range.
var fontLines = [
  ["underline", "line-through", "none"]
];

var range = sheet.getRange("B2:D2");
range.setFontLines(fontLines);

Parâmetros

NomeTipoDescrição
fontLinesObject[][]Uma matriz bidimensional de estilos de linha de fonte ('underline', 'line-through' ou 'none'). Os valores null redefinem o estilo da linha da fonte.

Retorno

Range: esse intervalo para encadeamento.

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

setFontSize(size)

Define o tamanho da fonte, sendo o tamanho o tamanho do ponto a ser usado.

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

var cell = sheet.getRange("B2");
cell.setFontSize(20);

Parâmetros

NomeTipoDescrição
sizeIntegerUm tamanho de fonte em tamanho de ponto.

Retorno

Range: esse intervalo para encadeamento.

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

setFontSizes(sizes)

Define uma grade retangular de tamanhos de fonte (deve corresponder às dimensões desse intervalo). Os tamanhos estão em pontos.

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

// The size of the two-dimensional array must match the size of the range.
var fontSizes = [
  [16, 20, 24]
];

var range = sheet.getRange("B2:D2");
range.setFontSizes(fontSizes);

Parâmetros

NomeTipoDescrição
sizesObject[][]Uma matriz bidimensional de tamanhos.

Retorno

Range: esse intervalo para encadeamento.

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

setFontStyle(fontStyle)

Define o estilo da fonte do intervalo especificado ('italic' ou 'normal').

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

var cell = sheet.getRange("B2");
cell.setFontStyle("italic");

Parâmetros

NomeTipoDescrição
fontStyleStringO estilo da fonte, 'italic' ou 'normal', um valor null redefine o estilo da fonte.

Retorno

Range: esse intervalo para encadeamento.

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

setFontStyles(fontStyles)

Define uma grade retangular de estilos de fonte (deve corresponder às dimensões desse intervalo).

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

// The size of the two-dimensional array must match the size of the range.
var fontStyles = [
  ["italic", "normal"]
];

var range = sheet.getRange("B2:C2");
range.setFontStyles(fontStyles);

Parâmetros

NomeTipoDescrição
fontStylesObject[][]Uma matriz bidimensional de estilos de fonte, 'italic' ou 'normal'. Os valores null redefinem o estilo da fonte.

Retorno

Range: esse intervalo para encadeamento.

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

setFontWeight(fontWeight)

Define a espessura da fonte para o intervalo fornecido (normal/negrito).

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

var cell = sheet.getRange("B2");
cell.setFontWeight("bold");

Parâmetros

NomeTipoDescrição
fontWeightStringA espessura da fonte, 'bold' ou 'normal'. Um valor null redefine o peso da fonte.

Retorno

Range: esse intervalo para encadeamento.

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

setFontWeights(fontWeights)

Define uma grade retangular de espessuras de fonte (deve corresponder às dimensões deste intervalo). Um exemplo de peso da fonte é "negrito".

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

// The size of the two-dimensional array must match the size of the range.
var fontStyles = [
  [ "bold", "bold", "normal" ]
];

var range = sheet.getRange("B2:D2");
range.setFontWeights(fontStyles);

Parâmetros

NomeTipoDescrição
fontWeightsObject[][]Uma matriz bidimensional de pesos de fonte, 'bold' ou 'normal'. Os valores null redefinem o peso da fonte.

Retorno

Range: esse intervalo para encadeamento.

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

setFormula(formula)

Atualiza a fórmula para esse intervalo. A fórmula fornecida precisa estar na notação A1.

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

var cell = sheet.getRange("B5");
cell.setFormula("=SUM(B3:B4)");

Parâmetros

NomeTipoDescrição
formulaStringUma string que representa a fórmula a ser definida para a célula.

Retorno

Range: esse intervalo para encadeamento.

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

setFormulaR1C1(formula)

Atualiza a fórmula para esse intervalo. A fórmula deve estar na notação R1C1.

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

var cell = sheet.getRange("B5");
// This sets the formula to be the sum of the 3 rows above B5
cell.setFormulaR1C1("=SUM(R[-3]C[0]:R[-1]C[0])");

Parâmetros

NomeTipoDescrição
formulaStringUma fórmula de string.

Retorno

Range: esse intervalo para encadeamento.

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

setFormulas(formulas)

Define uma grade retangular de fórmulas (precisa corresponder às dimensões deste intervalo). As fórmulas fornecidas precisam estar em notação A1. Esse método usa uma matriz bidimensional de fórmulas, indexadas por linha e, em seguida, por coluna. As dimensões da matriz precisam corresponder às do intervalo.

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

// This sets the formulas to be a row of sums, followed by a row of averages right below.
// The size of the two-dimensional array must match the size of the range.
var formulas = [
  ["=SUM(B2:B4)", "=SUM(C2:C4)", "=SUM(D2:D4)"],
  ["=AVERAGE(B2:B4)", "=AVERAGE(C2:C4)", "=AVERAGE(D2:D4)"]
];

var cell = sheet.getRange("B5:D6");
cell.setFormulas(formulas);

Parâmetros

NomeTipoDescrição
formulasString[][]Uma matriz de string bidimensional de fórmulas.

Retorno

Range: esse intervalo para encadeamento.

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

setFormulasR1C1(formulas)

Define uma grade retangular de fórmulas (precisa corresponder às dimensões deste intervalo). As fórmulas fornecidas precisam estar na notação R1C1.

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

// This creates formulas for a row of sums, followed by a row of averages.
var sumOfRowsAbove = "=SUM(R[-3]C[0]:R[-1]C[0])";
var averageOfRowsAbove = "=AVERAGE(R[-4]C[0]:R[-2]C[0])";

// The size of the two-dimensional array must match the size of the range.
var formulas = [
  [sumOfRowsAbove, sumOfRowsAbove, sumOfRowsAbove],
  [averageOfRowsAbove, averageOfRowsAbove, averageOfRowsAbove]
];

var cell = sheet.getRange("B5:D6");
// This sets the formula to be the sum of the 3 rows above B5.
cell.setFormulasR1C1(formulas);

Parâmetros

NomeTipoDescrição
formulasString[][]Uma matriz bidimensional de fórmulas no formato R1C1.

Retorno

Range: esse intervalo para encadeamento.

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

setHorizontalAlignment(alignment)

Define o alinhamento horizontal (da esquerda para a direita) para o intervalo especificado (esquerda/central/direita).

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

var cell = sheet.getRange("B2");
cell.setHorizontalAlignment("center");

Parâmetros

NomeTipoDescrição
alignmentStringO alinhamento, que é 'left', 'center' ou 'normal'. Um valor null redefine o alinhamento.

Retorno

Range: esse intervalo para encadeamento.

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

setHorizontalAlignments(alignments)

Define uma grade retangular de alinhamentos horizontais. Consulte setHorizontalAlignment(alignment)

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

// The size of the two-dimensional array must match the size of the range.
var horizontalAlignments = [
  [ "left", "right", "center" ]
];

var range = sheet.getRange("B2:D2");
range.setHorizontalAlignments(horizontalAlignments);

Parâmetros

NomeTipoDescrição
alignmentsObject[][]Uma matriz bidimensional de alinhamentos, 'left', 'center' ou 'normal'. Um valor null redefine o alinhamento.

Retorno

Range: esse intervalo para encadeamento.

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

Veja também


setNote(note)

Define a nota para o valor fornecido.

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

var cell = sheet.getRange("B2");
cell.setNote("This is a note");

Parâmetros

NomeTipoDescrição
noteStringO valor da nota a ser definido para o intervalo. Um valor null remove a nota.

Retorno

Range: esse intervalo para encadeamento.

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

setNotes(notes)

Define uma grade retangular de notas (deve corresponder às dimensões deste intervalo).

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

// The size of the two-dimensional array must match the size of the range.
var notes = [
  ["it goes", "like this", "the fourth, the fifth"],
  ["the minor fall", "and the", "major lift"]
];

var cell = sheet.getRange("B2:D3");
cell.setNotes(notes)

Parâmetros

NomeTipoDescrição
notesObject[][]Uma matriz bidimensional de notas. Os valores null removem a nota.

Retorno

Range: esse intervalo para encadeamento.

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

Veja também


setNumberFormat(numberFormat)

Define o formato de número ou data para a string de formatação especificada. Os padrões de formato aceitos estão descritos na documentação da API Sheets.

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

var cell = sheet.getRange("B2");
// Always show 3 decimal points
cell.setNumberFormat("0.000");

Parâmetros

NomeTipoDescrição
numberFormatStringUma string de formato numérico.

Retorno

Range: esse intervalo para encadeamento.

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

setNumberFormats(numberFormats)

Define uma grade retangular de formatos de número ou data (deve corresponder às dimensões desse intervalo). Os valores são strings de padrão de formato, conforme descrito na documentação da API Sheets.

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

// The size of the two-dimensional array must match the size of the range.
var formats = [
  [ "0.000", "0,000,000", "$0.00" ]
];

var range = sheet.getRange("B2:D2");
range.setNumberFormats(formats);

Parâmetros

NomeTipoDescrição
numberFormatsObject[][]Uma matriz bidimensional de formatos numéricos.

Retorno

Range: esse intervalo para encadeamento.

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

setRichTextValue(value)

Define o valor de rich text para as células no intervalo.

// Sets all cells in range B2:D4 to have the text "Hello world", with "Hello" bolded.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B2:D4");
var bold = SpreadsheetApp.newTextStyle()
    .setBold(true)
    .build();
var richText = SpreadsheetApp.newRichTextValue()
    .setText("Hello world")
    .setTextStyle(0, 5, bold)
    .build();
range.setRichTextValue(richText);

Parâmetros

NomeTipoDescrição
valueRichTextValueO valor de rich text desejado.

Retorno

Range: esse intervalo para encadeamento.

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

setRichTextValues(values)

Define uma grade retangular de valores de Rich Text.

// Sets the cells in range A1:A2 to have Rich Text values.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("A1:A2");
var bold = SpreadsheetApp.newTextStyle()
    .setBold(true)
    .build();
var italic = SpreadsheetApp.newTextStyle()
    .setItalic(true)
    .build();
var richTextA1 = SpreadsheetApp.newRichTextValue()
    .setText("This cell is bold")
    .setTextStyle(bold)
    .build();
var richTextA2 = SpreadsheetApp.newRichTextValue()
    .setText("bold words, italic words")
    .setTextStyle(0, 11, bold)
    .setTextStyle(12, 24, italic)
    .build();
range.setRichTextValues([[richTextA1], [richTextA2]]);

Parâmetros

NomeTipoDescrição
valuesRichTextValue[][]Os valores de rich text desejados.

Retorno

Range: esse intervalo para encadeamento.

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 se o intervalo deve ou não exibir hiperlinks.

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can useSpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets cell A30 and sets its hyperlink value.
const range = sheet.getRange('A30');
range.setValue('https://www.example.com');

// Sets cell A30 to show hyperlinks.
range.setShowHyperlink(true);

Parâmetros

NomeTipoDescrição
showHyperlinkBooleanSe o hiperlink deve ou não ser exibido.

Retorno

Range: esse intervalo para encadeamento.

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

setTextDirection(direction)

Define a direção do texto das células no intervalo. Se uma direção especificada for null, ela será inferida e definida.

// Sets right-to-left text direction for the range.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B5:C6");
range.setTextDirection(SpreadsheetApp.TextDirection.RIGHT_TO_LEFT);

Parâmetros

NomeTipoDescrição
directionTextDirectionA direção do texto desejada. Se for null, a direção será inferida antes da configuração.

Retorno

Range: esse intervalo para encadeamento.

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

setTextDirections(directions)

Define uma grade retangular de direções de texto. Se uma direção especificada for null, a direção será inferida e definida.

// Copies all of the text directions from range A1:B2 over to range C5:D6.
var sheet = SpreadsheetApp.getActiveSheet();
var range1 = sheet.getRange("A1:B2");
var range2 = sheet.getRange("C5:D6");

range2.setTextRotations(range1.getTextDirections());

Parâmetros

NomeTipoDescrição
directionsTextDirection[][]As direções de texto desejadas. Se uma direção especificada é null, ela é inferida antes da configuração.

Retorno

Range: esse intervalo para encadeamento.

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

setTextRotation(degrees)

Define as configurações de rotação do texto para as células no intervalo. A entrada corresponde ao ângulo entre a orientação de texto padrão e a orientação desejada. Uma entrada de zero indica que o texto está definido para a orientação padrão.

Na direção do texto da esquerda para a direita, os ângulos positivos estão no sentido anti-horário, enquanto para a esquerda eles estão no sentido horário.

// Sets all cell's in range B2:D4 to have text rotated up 45 degrees.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B2:D4");

range.setTextRotation(45);

Parâmetros

NomeTipoDescrição
degreesIntegerO ângulo desejado entre a orientação padrão e a orientação desejada. No texto da esquerda para a direita, os ângulos positivos estão no sentido anti-horário.

Retorno

Range: esse intervalo para encadeamento.

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

setTextRotation(rotation)

Define as configurações de rotação do texto para as células no intervalo.

// Sets all cell's in range B2:D4 to have the same text rotation settings as cell A1.
var sheet = SpreadsheetApp.getActiveSheet();

var rotation = sheet.getRange("A1").getTextRotation();

sheet.getRange("B2:D4").setTextRotation(rotation);

Parâmetros

NomeTipoDescrição
rotationTextRotationAs configurações de rotação do texto desejadas.

Retorno

Range: esse intervalo para encadeamento.

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

setTextRotations(rotations)

Define uma grade retangular de rotações do texto.

// Copies all of the text rotations from range A1:B2 over to range C5:D6.
var sheet = SpreadsheetApp.getActiveSheet();
var range1 = sheet.getRange("A1:B2");
var range2 = sheet.getRange("C5:D6");

range2.setTextRotations(range1.getTextRotations());

Parâmetros

NomeTipoDescrição
rotationsTextRotation[][]As configurações de rotação do texto desejadas.

Retorno

Range: esse intervalo para encadeamento.

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

setTextStyle(style)

Define o estilo de texto das células no intervalo.

// Sets the cells in range C5:D6 to have underlined size 15 font.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("C5:D6");
var style = SpreadsheetApp.newTextStyle()
    .setFontSize(15)
    .setUnderline(true)
    .build();
range.setTextStyle(style);

Parâmetros

NomeTipoDescrição
styleTextStyleO estilo de texto desejado.

Retorno

Range: esse intervalo para encadeamento.

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

setTextStyles(styles)

Define uma grade retangular de estilos de texto.

// Sets text styles for cells in range A1:B2
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("A1:B2");
var bold = SpreadsheetApp.newTextStyle()
    .setBold(true)
    .build();
var otherStyle = SpreadsheetApp.newTextStyle()
    .setBold(true)
    .setUnderline(true)
    .setItalic(true)
    .setForegroundColor("#335522")
    .setFontSize(44)
    .build();
range.setTextStyles([[bold, otherStyle], [otherStyle, bold]]);

Parâmetros

NomeTipoDescrição
stylesTextStyle[][]Os estilos de texto desejados.

Retorno

Range: esse intervalo para encadeamento.

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

setValue(value)

Define o valor do intervalo. O valor pode ser numérico, de string, booleano ou data. Se começar com '=', será interpretado como uma fórmula.

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

var cell = sheet.getRange("B2");
cell.setValue(100);

Parâmetros

NomeTipoDescrição
valueObjectValor do intervalo.

Retorno

Range: esse intervalo para encadeamento.

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

setValues(values)

Define uma grade retangular de valores (precisa corresponder às dimensões deste intervalo). Se um valor começar com =, ele será interpretado como uma fórmula.

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

// The size of the two-dimensional array must match the size of the range.
var values = [
  [ "2.000", "1,000,000", "$2.99" ]
];

var range = sheet.getRange("B2:D2");
range.setValues(values);

Parâmetros

NomeTipoDescrição
valuesObject[][]Uma matriz bidimensional de valores.

Retorno

Range: esse intervalo para encadeamento.

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

setVerticalAlignment(alignment)

Define o alinhamento vertical (de cima para baixo) no intervalo especificado (superior/meio/inferior).

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

var cell = sheet.getRange("B2");
cell.setVerticalAlignment("middle");

Parâmetros

NomeTipoDescrição
alignmentStringO alinhamento, que é 'top', 'middle' ou 'bottom'. Um valor null redefine o alinhamento.

Retorno

Range: esse intervalo para encadeamento.

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

setVerticalAlignments(alignments)

Define uma grade retangular de alinhamentos verticais (deve corresponder às dimensões deste intervalo).

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

// The size of the two-dimensional array must match the size of the range.
var alignments = [
  [ "top", "middle", "bottom" ]
];

var range = sheet.getRange("B2:D2");
range.setVerticalAlignments(alignments);

Parâmetros

NomeTipoDescrição
alignmentsObject[][]Uma matriz bidimensional de alinhamentos, 'top', 'middle' ou 'bottom'. Um valor null redefine o alinhamento.

Retorno

Range: esse intervalo para encadeamento.

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

Veja também


setVerticalText(isVertical)

Define se o texto será empilhado para as células no intervalo. Se o texto estiver empilhado verticalmente, a configuração de rotação do texto com grau será ignorada.

// Sets all cell's in range B2:D4 to have vertically stacked text.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B2:D4");

range.setVerticalText(true);

Parâmetros

NomeTipoDescrição
isVerticalBooleanSe o texto será empilhado ou não.

Retorno

Range: esse intervalo para encadeamento.

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

setWrap(isWrapEnabled)

Define a quebra de célula do intervalo especificado.

As células com ajuste ativado (padrão) são redimensionadas para exibir o conteúdo completo. As células com encapsulamento desativado são exibidas o máximo possível na célula, sem serem redimensionadas ou ter várias linhas.

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

var cell = sheet.getRange("B2");
cell.setWrap(true);

Parâmetros

NomeTipoDescrição
isWrapEnabledBooleanSe o texto deve ser ajustado ou não.

Retorno

Range: esse intervalo para encadeamento.

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

setWrapStrategies(strategies)

Define uma grade retangular de estratégias de agrupamento.

// Copies all of the wrap strategies from range A1:B2 over to range C5:D6.
var sheet = SpreadsheetApp.getActiveSheet();
var range1 = sheet.getRange("A1:B2");
var range2 = sheet.getRange("C5:D6");

range2.setWrapStrategies(range1.getWrapStrategies());

Parâmetros

NomeTipoDescrição
strategiesWrapStrategy[][]As estratégias de encapsulamento desejadas.

Retorno

Range: esse intervalo para encadeamento.

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

setWrapStrategy(strategy)

Define a estratégia de ajuste de texto para as células no intervalo.

// Sets all cells in range B2:D4 to use the clip wrap strategy.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B2:D4");

range.setWrapStrategy(SpreadsheetApp.WrapStrategy.CLIP);

Parâmetros

NomeTipoDescrição
strategyWrapStrategyA estratégia de encapsulamento desejada.

Retorno

Range: esse intervalo para encadeamento.

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

setWraps(isWrapEnabled)

Define uma grade retangular de políticas de quebra de palavra (deve corresponder às dimensões desse intervalo). As células com wrapper ativado (padrão) são redimensionadas para mostrar o conteúdo completo. As células com wrapper desativado são exibidas o máximo possível na célula, sem serem redimensionadas nem executadas em várias linhas.

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

// The size of the two-dimensional array must match the size of the range.
var wraps = [
  [ true, true, false ]
];

var range = sheet.getRange("B2:D2");
range.setWraps(wraps);

Parâmetros

NomeTipoDescrição
isWrapEnabledObject[][]Uma matriz bidimensional de variáveis de ajuste que determinam se o texto será ajustado ou não em uma célula.

Retorno

Range: esse intervalo para encadeamento.

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

Veja também


shiftColumnGroupDepth(delta)

Altera a profundidade do agrupamento de colunas do intervalo pelo valor especificado.

Isso tem o efeito de criar, modificar ou excluir grupos que cruzam com o intervalo. Para deltas positivos, os grupos são criados e/ou modificados. Para deltas negativos, os grupos são destruídos e/ou modificados.

Isso não tem efeito ao diminuir a profundidade do grupo para menos de zero ou acima de oito.

Se column group control position for BEFORE, será gerado um erro ao tentar mudar a profundidade da primeira linha.

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

// The column grouping depth is increased by 1.
range.shiftColumnGroupDepth(1);

// The column grouping depth is decreased by 1.
range.shiftColumnGroupDepth(-1);

Parâmetros

NomeTipoDescrição
deltaIntegerO valor pela qual alterar a profundidade do grupo de colunas desse intervalo.

Retorno

Range: esse intervalo para encadeamento.

Gera

Error: ao tentar mudar a profundidade da primeira coluna quando a posição de controle for GroupControlTogglePosition.BEFORE

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

shiftRowGroupDepth(delta)

Altera a profundidade do agrupamento de linhas do intervalo pelo valor especificado.

Isso tem o efeito de criar, modificar ou excluir grupos que cruzam com o intervalo. Para deltas positivos, os grupos são criados e/ou modificados. Para deltas negativos, os grupos são destruídos e/ou modificados.

Isso não tem efeito ao diminuir a profundidade do grupo para menos de zero ou acima de oito.

Se row group control position for BEFORE, um erro será gerado ao tentar mudar a profundidade da primeira linha.

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

// The row grouping depth is increased by 1.
range.shiftRowGroupDepth(1);

// The row grouping depth is decreased by 1.
range.shiftRowGroupDepth(-1);

Parâmetros

NomeTipoDescrição
deltaIntegerO valor pela qual alterar a profundidade do grupo de linhas desse intervalo.

Retorno

Range: esse intervalo para encadeamento.

Gera

Error: ao tentar mudar a profundidade da primeira linha quando a posição de controle for GroupControlTogglePosition.BEFORE.

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

sort(sortSpecObj)

Classifica as células de um intervalo específico, por coluna e ordem especificada.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("A1:C7");

// Sorts by the values in the first column (A)
range.sort(1);

// Sorts by the values in the second column (B)
range.sort(2);

// Sorts descending by column B
range.sort({column: 2, ascending: false});

// Sorts descending by column B, then ascending by column A
// Note the use of an array
range.sort([{column: 2, ascending: false}, {column: 1, ascending: true}]);

// For rows that are sorted in ascending order, the "ascending" parameter is
// optional, and just an integer with the column can be used instead. Note that
// in general, keeping the sort specification consistent results in more readable
// code. You can express the earlier sort as:
range.sort([{column: 2, ascending: false}, 1]);

// Alternatively, if you want all columns to be in ascending order, you can use
// the following (this makes column 2 ascending)
range.sort([2, 1]);
// ... which is equivalent to
range.sort([{column: 2, ascending: true}, {column: 1, ascending: true}]);

Parâmetros

NomeTipoDescrição
sortSpecObjObjectAs colunas para classificar.

Retorno

Range: esse intervalo para encadeamento.

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

splitTextToColumns()

Divide uma coluna de texto em várias colunas com base em um delimitador detectado automaticamente.

// A1:A3 has the following values:
//           A                  B                 C
// 1 |one,one,one      |                 |                 |
// 2 |two,two,two      |                 |                 |
// 3 |three,three,three|                 |                 |

var range = SpreadsheetApp.getActiveSheet().getRange("A1:A3");
range.splitTextToColumns();

// Result after spliting the text to columns:
//           A                  B                 C
// 1 |one              |one              |one              |
// 2 |two              |two              |two              |
// 3 |three            |three            |three            |

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

splitTextToColumns(delimiter)

Divide uma coluna de texto em várias colunas usando a string especificada como um delimitador personalizado.

// A1:A3 has the following values:
//           A                  B                 C
// 1 |one#one#one      |                 |                 |
// 2 |two#two#two      |                 |                 |
// 3 |three#three#three|                 |                 |

var range = SpreadsheetApp.getActiveSheet().getRange("A1:A3");
range.splitTextToColumns('#');

// Result after spliting the text to columns:
//           A                  B                 C
// 1 |one              |one              |one              |
// 2 |two              |two              |two              |
// 3 |three            |three            |three            |

Parâmetros

NomeTipoDescrição
delimiterStringO delimitador personalizado a ser dividido.

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

splitTextToColumns(delimiter)

Divide uma coluna de texto em várias colunas com base no delimitador especificado.

// A1:A3 has the following values:
//           A                  B                 C
// 1 |one;one;one      |                 |                 |
// 2 |two;two;two      |                 |                 |
// 3 |three;three;three|                 |                 |

var range = SpreadsheetApp.getActiveSheet().getRange("A1:A3");
range.splitTextToColumns(SpreadsheetApp.TextToColumnsDelimiter.SEMICOLON);

// Result after spliting the text to columns:
//           A                  B                 C
// 1 |one              |one              |one              |
// 2 |two              |two              |two              |
// 3 |three            |three            |three            |

Parâmetros

NomeTipoDescrição
delimiterTextToColumnsDelimiterO delimitador predefinido para divisão.

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

trimWhitespace()

Corta o espaço em branco (como espaços, tabulações ou novas linhas) em todas as células neste intervalo. Remove todos os espaços em branco do início e do final do texto de cada célula e reduz qualquer subsequência de caracteres de espaço em branco restantes a um único espaço.

var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
var range = sheet.getRange('A1:A4');
range.activate();
range.setValues(
    [' preceding space', 'following space ', 'two  middle  spaces', '   =SUM(1,2)'])

range.trimWhitespace();

var values = range.getValues();
// Values are ['preceding space', 'following space', 'two middle spaces', '=SUM(1,2)']

Retorno

Range: esse intervalo para encadeamento.

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

uncheck()

Muda o estado das caixas de seleção no intervalo para "desmarcada". Ignora as células no intervalo que atualmente não contêm o valor marcado ou desmarcado configurado.

// Changes the state of cells which currently contain either the checked or unchecked value
// configured in the range A1:B10 to 'unchecked'.
var range = SpreadsheetApp.getActive().getRange('A1:B10');
range.uncheck();

Retorno

Range: esse intervalo para encadeamento.

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

Métodos obsoletos