ExcelScript.Range interface

Pacote:

ExcelScript

O intervalo representa um conjunto de uma ou mais células contíguas, como uma célula, uma linha, uma coluna ou um bloco de células.

Comentários

Exemplos

/**
 * This script logs the address of the used range in the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current, active worksheet.
  let currentWorksheet = workbook.getActiveWorksheet();

  // Get the range containing all the cells with data or formatting.
  let usedRange = currentWorksheet.getUsedRange();

  // Log the range's address to the console.
  console.log(usedRange.getAddress());
}

Métodos

addConditionalFormat(type)	Adiciona um novo formato condicional à coleção na primeira/prioridade máxima.
autoFill(destinationRange, autoFillType)	Preenche um intervalo entre o intervalo atual e o intervalo de destino com a lógica de Preenchimento Automático especificada. O intervalo de destino pode ser null ou pode expandir o intervalo de origem horizontal ou verticalmente. Os intervalos descontínuos não são suportados.
calculate()	Calcula um intervalo de células em uma planilha.
clear(applyTo)	Limpe valores de intervalo, formatação, preenchimento, bordas, etc.
clearAllConditionalFormats()	Limpa todos os formatos condicionais ativos no intervalo atual especificado.
convertDataTypeToText()	Converte as células de intervalo com tipos de dados em texto.
copyFrom(sourceRange, copyType, skipBlanks, transpose)	Copia dados de células ou formatação do intervalo de origem ou RangeAreas para o intervalo atual. O intervalo de destino pode ter um tamanho diferente do intervalo de origem ou RangeAreas. O destino é expandido automaticamente se for menor do que a origem. Nota: tal como a funcionalidade de cópia na IU do Excel, se o intervalo de destino for um múltiplo exato maior do que o intervalo de origem em linhas ou colunas, o conteúdo de origem é replicado várias vezes. Por exemplo, uma cópia de intervalo 2x2 para um intervalo 2x6 resultará em 3 cópias do intervalo 2x2 original.
delete(shift)	Exclui as células associadas ao intervalo.
find(text, criteria)	Localiza certa cadeia de caracteres com base em critérios especificados. Se o intervalo atual for maior do que uma única célula, a pesquisa será limitada a esse intervalo, caso contrário, a pesquisa cobrirá toda a folha a partir dessa célula. Se não existirem correspondências, este método devolve undefined.
flashFill()	Efetua uma Pré-visualização da Conclusão Automática para o intervalo atual. A Pré-visualização da Conclusão Automática preenche automaticamente os dados quando detetar um padrão, pelo que o intervalo tem de ser um intervalo de colunas único e ter dados à sua volta para encontrar um padrão.
getAbsoluteResizedRange(numRows, numColumns)	Obtém um Range objeto com a mesma célula superior esquerda que o objeto atual Range , mas com os números especificados de linhas e colunas.
getAddress()	Especifica a referência de intervalo no estilo A1. O valor do endereço contém a referência da folha (por exemplo, "Folha1! A1:B4").
getAddressLocal()	Representa a referência de intervalo para o intervalo especificado no idioma do utilizador.
getBoundingRect(anotherRange)	Obtém o menor objeto de intervalo que abrange os intervalos determinados. Por exemplo, " GetBoundingRect B2:C5" e "D10:E15" é "B2:E15".
getCell(row, column)	Obtém o objeto de intervalo que contém a célula única com base nos números de linha e de coluna. A célula pode estar fora dos limites do respetivo intervalo principal, desde que permaneça na grelha da folha de cálculo. A localização da célula retornada está relacionada à célula superior esquerda do intervalo.
getCellCount()	Especifica o número de células no intervalo. Essa API retornará -1 se a contagem de células exceder 2^31-1 (2.147.483.647).
getColumn(column)	Obtém uma coluna incluída no intervalo.
getColumnCount()	Especifica o número total de colunas no intervalo.
getColumnHidden()	Representa se todas as colunas no intervalo atual estão ocultas. O valor é true quando todas as colunas num intervalo estão ocultas. O valor é false quando não existem colunas no intervalo ocultadas. O valor é null quando algumas colunas num intervalo estão ocultas e outras colunas no mesmo intervalo não estão ocultas.
getColumnIndex()	Especifica o número da coluna da primeira célula no intervalo. Indexados com zero.
getColumnsAfter(count)	Obtém um determinado número de colunas à direita do objeto atual Range .
getColumnsBefore(count)	Obtém um determinado número de colunas à esquerda do objeto atual Range .
getConditionalFormat(id)	Devolve um formato condicional identificado pelo respetivo ID. Se o objeto de formato condicional não existir, este método devolve undefined.
getConditionalFormats()	A coleção do ConditionalFormats que intersecta o intervalo.
getDataValidation()	Retorna um objeto de validação de dados.
getDirectPrecedents()	Devolve um WorkbookRangeAreas objeto que representa o intervalo que contém todas as células precedentes diretas de um intervalo especificado na mesma folha de cálculo ou em várias folhas de cálculo.
getEntireColumn()	Obtém um objeto que representa toda a coluna do intervalo (por exemplo, se o intervalo atual representar as células "B4:E11", getEntireColumn é um intervalo que representa as colunas "B:E").
getEntireRow()	Obtém um objeto que representa toda a linha do intervalo (por exemplo, se o intervalo atual representar as células "B4:E11", GetEntireRow é um intervalo que representa as linhas "4:11").
getExtendedRange(direction, activeCell)	Devolve um objeto de intervalo que inclui o intervalo atual e até à margem do intervalo, com base na direção fornecida. Isto corresponde ao comportamento de Ctrl+Shift+Tecla de Seta na IU do Excel no Windows.
getFormat()	Retorna um objeto de formato que encapsula a fonte, o preenchimento, as bordas, o alinhamento e outras propriedades do intervalo.
getFormula()	Representa a fórmula de célula na notação de estilo A1. Se o intervalo contiver múltiplas células, serão devolvidos os dados da primeira célula (representados pelo índice de linha de 0 e índice de colunas de 0).
getFormulaLocal()	Representa a fórmula de célula na notação de estilo A1, no idioma do utilizador e na região de formatação de números. Por exemplo, a fórmula "=SUM(A1, 1.5)" em inglês seria "=SOMA(A1; 1,5)" em português. Se o intervalo contiver múltiplas células, serão devolvidos os dados da primeira célula (representados pelo índice de linha de 0 e índice de colunas de 0).
getFormulaR1C1()	Representa a fórmula da célula na notação de estilo R1C1. Se o intervalo contiver múltiplas células, serão devolvidos os dados da primeira célula (representados pelo índice de linha de 0 e índice de colunas de 0).
getFormulas()	Representa a fórmula em notação A1. Se uma célula não tiver nenhuma fórmula, é devolvido o respetivo valor.
getFormulasLocal()	Representa a fórmula em notação A1, na formatação de número da localidade e no idioma do usuário. Por exemplo, a fórmula "=SUM(A1, 1.5)" em inglês seria "=SOMA(A1; 1,5)" em português. Se uma célula não tiver nenhuma fórmula, é devolvido o respetivo valor.
getFormulasR1C1()	Representa a fórmula em notação no estilo L1C1. Se uma célula não tiver nenhuma fórmula, é devolvido o respetivo valor.
getHasSpill()	Representa se todas as células têm uma borda de despejo. Devolve true se todas as células tiverem um limite de transposição ou false se todas as células não tiverem um limite de transposição. Devolve null se existirem células com e sem limites de transposição dentro do intervalo.
getHeight()	Devolve a distância em pontos, para 100% de zoom, desde a margem superior do intervalo até à margem inferior do intervalo.
getHidden()	Representa se todas as células no intervalo atual estão ocultas. O valor é true quando todas as células num intervalo estão ocultas. O valor é false quando não existem células no intervalo ocultadas. O valor é null quando algumas células num intervalo estão ocultas e outras células no mesmo intervalo não estão ocultas.
getHyperlink()	Representa a hiperligação para o intervalo atual.
getImage()	Compõe o intervalo como uma imagem png codificada com base64.
getIntersection(anotherRange)	Obtém o objeto de intervalo que representa a interseção retangular dos intervalos determinados. Se não for encontrada nenhuma interseção, este método devolve undefined.
getIsEntireColumn()	Representa se o intervalo atual está em uma coluna inteira.
getIsEntireRow()	Representa se o intervalo atual está em uma linha inteira.
getLastCell()	Obtém a última célula do intervalo. Por exemplo, a última célula de "B2:D5" é "D5".
getLastColumn()	Obtém a última coluna do intervalo. Por exemplo, a última coluna de "B2:D5" é "D2:D5".
getLastRow()	Obtém a última linha do intervalo. Por exemplo, a última linha de "B2:D5" é "B5:D5".
getLeft()	Devolve a distância em pontos, para uma ampliação de 100%, desde a margem esquerda da folha de cálculo até à margem esquerda do intervalo.
getLinkedDataTypeState()	Representa o estado do tipo de dados da célula.
getLinkedDataTypeStates()	Representa o estado do tipo de dados de cada célula.
getMergedAreas()	Devolve um RangeAreas objeto que representa as áreas unidas neste intervalo. Tenha em atenção que se a contagem de áreas unidas neste intervalo for superior a 512, este método não devolverá o resultado. Se o RangeAreas objeto não existir, esta função devolve undefined.
getNumberFormat()	Representa o código de formato de número do Excel da célula para o intervalo especificado. Se o intervalo contiver múltiplas células, serão devolvidos os dados da primeira célula (representados pelo índice de linha de 0 e índice de colunas de 0).
getNumberFormatCategories()	Representa a categoria do formato de número de cada célula.
getNumberFormatCategory()	Especifica a categoria de formato de número da primeira célula no intervalo (representada pelo índice de linha de 0 e índice de coluna de 0).
getNumberFormatLocal()	Representa o código de formato de número de célula do Excel para o intervalo especificado, com base nas definições de idioma do utilizador. O Excel não executa qualquer idioma ou coerção de formato ao obter ou definir a numberFormatLocal propriedade. Qualquer texto devolvido utiliza as cadeias formatadas localmente com base no idioma especificado nas definições do sistema. Se o intervalo contiver múltiplas células, serão devolvidos os dados da primeira célula (representados pelo índice de linha de 0 e índice de colunas de 0).
getNumberFormats()	Representa o código de formato de número do Excel para o intervalo especificado.
getNumberFormatsLocal()	Representa o código de formato de número do Excel para o intervalo especificado, com base nas definições de idioma do utilizador. O Excel não executa qualquer idioma ou coerção de formato ao obter ou definir a numberFormatLocal propriedade. Qualquer texto devolvido utiliza as cadeias formatadas localmente com base no idioma especificado nas definições do sistema.
getOffsetRange(rowOffset, columnOffset)	Obtém um objeto que representa um intervalo deslocado do intervalo especificado. A dimensão do intervalo retornado corresponde a esse intervalo. Se o intervalo resultante for imposto para fora dos limites da grade da planilha, o sistema gerará um erro.
getPivotTables(fullyContained)	Obtém uma coleção de tabelas dinâmicas no âmbito que se sobrepõem ao intervalo.
getPredefinedCellStyle()	Representa o estilo de intervalo atual. Se os estilos das células forem inconsistentes, null serão devolvidos. Para estilos personalizados, o nome do estilo será devolvido. Para estilos incorporados, será devolvida uma cadeia que representa um valor na BuiltInStyle enumeração.
getRangeEdge(direction, activeCell)	Devolve um objeto de intervalo que é a célula de limite da região de dados que corresponde à direção fornecida. Isto corresponde ao comportamento da tecla Ctrl+Seta na IU do Excel no Windows.
getResizedRange(deltaRows, deltaColumns)	Obtém um Range objeto semelhante ao objeto atual Range , mas com o canto inferior direito expandido (ou contratado) por algumas linhas e colunas.
getRow(row)	Obtém uma linha contida no intervalo.
getRowCount()	Retorna o número total de linhas no intervalo.
getRowHidden()	Representa se todas as linhas no intervalo atual estão ocultas. O valor é true quando todas as linhas num intervalo estão ocultas. O valor é false quando não existem linhas no intervalo ocultadas. O valor é null quando algumas linhas num intervalo estão ocultas e outras linhas no mesmo intervalo não estão ocultas.
getRowIndex()	Representa o número de linhas da primeira célula no intervalo. Indexados com zero.
getRowsAbove(count)	Obtém um determinado número de linhas acima do objeto atual Range .
getRowsBelow(count)	Obtém um determinado número de linhas abaixo do objeto atual Range .
getSavedAsArray()	Representa se todas as células seriam guardadas como uma fórmula de matriz. Devolve true se todas as células fossem guardadas como uma fórmula de matriz ou false se todas as células não fossem guardadas como uma fórmula de matriz. Devolve null se algumas células fossem guardadas como uma fórmula de matriz e algumas não seriam.
getSort()	Representa a classificação de intervalo do intervalo atual.
getSpecialCells(cellType, cellValueType)	Obtém o RangeAreas objeto, composto por um ou mais intervalos, que representa todas as células que correspondem ao tipo e valor especificados. Se não forem encontradas células especiais, este método devolve undefined.
getSpillingToRange()	Obtém objeto range que contém o intervalo de despejo quando chamado em uma célula âncora. Se o intervalo não for uma célula de âncora ou não for possível localizar o intervalo de derrames, este método devolve undefined.
getSpillParent()	Obtém o objeto de intervalo que contém a célula de âncora para a célula a ser transbordada. Se não for uma célula transbordada ou se for fornecida mais do que uma célula, este método devolve undefined.
getSurroundingRegion()	Devolve um Range objeto que representa a região circundante para a célula superior esquerda neste intervalo. Uma região ao redor é um intervalo limitado por qualquer combinação de linhas e colunas em branco em relação a esse intervalo.
getTables(fullyContained)	Obtém uma coleção de tabelas com escopo que se sobrepõe ao intervalo.
getText()	Representa o valor de Texto do intervalo especificado. O valor de texto não depende da largura da célula. A substituição pelo sinal #, que ocorre na interface de usuário do Excel, não afeta o valor de texto retornado pela API. Se o intervalo contiver múltiplas células, serão devolvidos os dados da primeira célula (representados pelo índice de linha de 0 e índice de colunas de 0).
getTexts()	Valores de texto do intervalo especificado. O valor de texto não depende da largura da célula. A substituição do sinal de número (#) que ocorre na IU do Excel não afetará o valor de texto devolvido pela API.
getTop()	Devolve a distância em pontos, para uma ampliação de 100%, desde a margem superior da folha de cálculo até à margem superior do intervalo.
getUsedRange(valuesOnly)	Retorna o intervalo usado do objeto de intervalo determinado. Se não existirem células utilizadas dentro do intervalo, este método devolve undefined.
getValue()	Representa o valor não processado do intervalo especificado. Os dados retornados podem ser dos tipos: cadeia de caracteres, número ou booliano. Células que contêm um erro retornarão a cadeia de caracteres de erro. Se o intervalo contiver múltiplas células, serão devolvidos os dados da primeira célula (representados pelo índice de linha de 0 e índice de colunas de 0).
getValues()	Representa os valores brutos do intervalo especificado. Os dados devolvidos podem ser uma cadeia, número ou booleano. Células que contêm um erro retornarão a cadeia de caracteres de erro. Se o valor devolvido começar com uma adição ("+"), sinal de subtração ("-"), ou sinal de igual ("="), o Excel interpreta este valor como uma fórmula.
getValueType()	Representa o tipo de dados na célula. Se o intervalo contiver múltiplas células, serão devolvidos os dados da primeira célula (representados pelo índice de linha de 0 e índice de colunas de 0).
getValueTypes()	Especifica o tipo de dados em cada célula.
getVisibleView()	Representa as linhas visíveis do intervalo atual.
getWidth()	Devolve a distância em pontos, para um zoom de 100%, desde a margem esquerda do intervalo até à margem direita do intervalo.
getWorksheet()	A planilha que contém o intervalo atual.
group(groupOption)	Grupos colunas e linhas para um destaque.
hideGroupDetails(groupOption)	Oculta os detalhes do grupo de linhas ou colunas.
insert(shift)	Insere uma célula ou um intervalo de células na planilha, no lugar desse intervalo, e desloca as outras células para liberar espaço. Devolve um novo Range objeto no espaço em branco agora.
merge(across)	Mescla as células do intervalo em uma região da planilha.
moveTo(destinationRange)	Move valores de células, formatação e fórmulas do intervalo atual para o intervalo de destino, substituindo as informações antigas nessas células. O intervalo de destino será expandido automaticamente se for menor do que o intervalo atual. As células no intervalo de destino que estejam fora da área do intervalo original não são alteradas.
removeDuplicates(columns, includesHeader)	Remove valores duplicados do intervalo especificado pelas colunas.
replaceAll(text, replacement, criteria)	Localiza e substitui a cadeia de caracteres fornecida com base nos critérios especificados no intervalo atual.
select()	Seleciona o intervalo especificado na interface do usuário do Excel.
setColumnHidden(columnHidden)	Representa se todas as colunas no intervalo atual estão ocultas. O valor é true quando todas as colunas num intervalo estão ocultas. O valor é false quando não existem colunas no intervalo ocultadas. O valor é null quando algumas colunas num intervalo estão ocultas e outras colunas no mesmo intervalo não estão ocultas.
setDirty()	Define um intervalo a ser recalculado quando o próximo recálculo ocorrer.
setFormula(formula)	Define a fórmula da célula na notação de estilo A1. Se o intervalo contiver múltiplas células, cada célula no intervalo especificado será atualizada com os dados de entrada.
setFormulaLocal(formulaLocal)	Defina a fórmula de célula na notação de estilo A1, no idioma do utilizador e na região de formatação de números. Por exemplo, a fórmula "=SUM(A1, 1.5)" em inglês seria "=SOMA(A1; 1,5)" em português. Se o intervalo contiver múltiplas células, cada célula no intervalo especificado será atualizada com os dados de entrada.
setFormulaR1C1(formulaR1C1)	Define a fórmula da célula na notação de estilo R1C1. Se o intervalo contiver múltiplas células, cada célula no intervalo especificado será atualizada com os dados de entrada.
setFormulas(formulas)	Representa a fórmula em notação A1. Se uma célula não tiver nenhuma fórmula, é devolvido o respetivo valor.
setFormulasLocal(formulasLocal)	Representa a fórmula em notação A1, na formatação de número da localidade e no idioma do usuário. Por exemplo, a fórmula "=SUM(A1, 1.5)" em inglês seria "=SOMA(A1; 1,5)" em português. Se uma célula não tiver nenhuma fórmula, é devolvido o respetivo valor.
setFormulasR1C1(formulasR1C1)	Representa a fórmula em notação no estilo L1C1. Se uma célula não tiver nenhuma fórmula, é devolvido o respetivo valor.
setHyperlink(hyperlink)	Representa a hiperligação para o intervalo atual.
setNumberFormat(numberFormat)	Define a célula código de formato de número do Excel para o intervalo especificado. Se o intervalo contiver múltiplas células, cada célula no intervalo especificado será atualizada com os dados de entrada.
setNumberFormatLocal(numberFormatLocal)	Define a célula código de formato de número do Excel para o intervalo especificado, com base nas definições de idioma do utilizador. O Excel não executa qualquer idioma ou coerção de formato ao obter ou definir a numberFormatLocal propriedade. Qualquer texto devolvido utiliza as cadeias formatadas localmente com base no idioma especificado nas definições do sistema. Se o intervalo contiver múltiplas células, cada célula no intervalo especificado será atualizada com os dados de entrada.
setNumberFormats(numberFormats)	Representa o código de formato de número do Excel para o intervalo especificado.
setNumberFormatsLocal(numberFormatsLocal)	Representa o código de formato de número do Excel para o intervalo especificado, com base nas definições de idioma do utilizador. O Excel não executa qualquer idioma ou coerção de formato ao obter ou definir a numberFormatLocal propriedade. Qualquer texto devolvido utiliza as cadeias formatadas localmente com base no idioma especificado nas definições do sistema.
setPredefinedCellStyle(predefinedCellStyle)	Representa o estilo de intervalo atual.
setRowHidden(rowHidden)	Representa se todas as linhas no intervalo atual estão ocultas. O valor é true quando todas as linhas num intervalo estão ocultas. O valor é false quando não existem linhas no intervalo ocultadas. O valor é null quando algumas linhas num intervalo estão ocultas e outras linhas no mesmo intervalo não estão ocultas.
setValue(value)	Define o valor não processado do intervalo especificado. Os dados que estão a ser definidos podem ser do tipo cadeia, número ou um booleano. null o valor será ignorado (não definido ou substituído no Excel). Se o intervalo contiver múltiplas células, cada célula no intervalo especificado será atualizada com os dados de entrada.
setValues(values)	Define os valores não processados do intervalo especificado. Os dados fornecidos podem ser uma cadeia, número ou booleano. Se o valor fornecido começar com uma adição ("+"), sinal de subtração ("-"), ou sinal de igual ("="), o Excel interpreta este valor como uma fórmula.
showCard()	Exibe o cartão para uma célula ativa se ele tiver um conteúdo valioso.
showGroupDetails(groupOption)	Mostra os detalhes do grupo de linhas ou colunas.
ungroup(groupOption)	Desagrupar colunas e linhas para um destaque.
unmerge()	Desfaz a mesclagem das células do intervalo em células separadas.

Detalhes do método

addConditionalFormat(type)

Adiciona um novo formato condicional à coleção na primeira/prioridade máxima.

addConditionalFormat(type: ConditionalFormatType): ConditionalFormat;

Parâmetros

type

ExcelScript.ConditionalFormatType

O tipo de formato condicional a ser adicionado. Veja ExcelScript.ConditionalFormatType para obter detalhes.

Retornos

ExcelScript.ConditionalFormat

Exemplos

/**
 * This sample applies conditional formatting to the currently used range in the worksheet. 
 * The conditional formatting is a green fill for the top 10% of values.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get the used range in the worksheet.
  let range = selectedSheet.getUsedRange();

  // Set the fill color to green for the top 10% of values in the range.
  let conditionalFormat = range.addConditionalFormat(ExcelScript.ConditionalFormatType.topBottom)
  conditionalFormat.getTopBottom().getFormat().getFill().setColor("green");
  conditionalFormat.getTopBottom().setRule({
    rank: 10, // The percentage threshold.
    type: ExcelScript.ConditionalTopBottomCriterionType.topPercent // The type of the top/bottom condition.
  });
}

autoFill(destinationRange, autoFillType)

Preenche um intervalo entre o intervalo atual e o intervalo de destino com a lógica de Preenchimento Automático especificada. O intervalo de destino pode ser null ou pode expandir o intervalo de origem horizontal ou verticalmente. Os intervalos descontínuos não são suportados.

autoFill(
            destinationRange?: Range | string,
            autoFillType?: AutoFillType
        ): void;

Parâmetros

destinationRange

ExcelScript.Range | string

O intervalo de destino para Preenchimento Automático. Se o intervalo de destino for null, os dados são preenchidos com base nas células adjacentes (que é o comportamento ao fazer duplo clique na alça de preenchimento do intervalo da IU).

autoFillType

ExcelScript.AutoFillType

O tipo de Preenchimento Automático. Especifica como o intervalo de destino deve ser preenchido, com base no conteúdo do intervalo atual. A predefinição é "FillDefault".

Retornos

void

Exemplos

/**
 * This script uses the autofill feature to complete a table.
 * See https://support.microsoft.com/office/74e31bdd-d993-45da-aa82-35a236c5b5db
 * for examples of autofill scenarios.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current, active worksheet.
  let currentWorksheet = workbook.getActiveWorksheet();

  // Get the data range that shows the pattern.
  let dataRange = currentWorksheet.getRange("C2:C3");

  // Autofill the connected range. C2:C3 are filled in. C4:C14 are blank.
  // This uses the default behavior to match a pattern with the table's contents.
  dataRange.autoFill("C2:C14");
}

calculate()

Calcula um intervalo de células em uma planilha.

calculate(): void;

Retornos

void

Exemplos

/**
 * This script recalculates the used range of a specific worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Only recalculate if the calculation mode is not set to automatic.
  if (workbook.getApplication().getCalculationMode() !== ExcelScript.CalculationMode.automatic) {
    // Get the used range from a worksheet named "Monthly Report".
    const sheet = workbook.getWorksheet("Monthly Report");
    const range = sheet.getUsedRange();
    console.log(`Calculating ${range.getAddress()}`);

    // Force all the used cells in that worksheet to calculate.
    sheet.getUsedRange().calculate();
  }
}

clear(applyTo)

Limpe valores de intervalo, formatação, preenchimento, bordas, etc.

clear(applyTo?: ClearApplyTo): void;

Parâmetros

applyTo

ExcelScript.ClearApplyTo

Opcional. Determina o tipo de ação clara. Veja ExcelScript.ClearApplyTo para obter detalhes.

Retornos

void

Exemplos

/**
 * This script removes all the formatting from the selected range.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the selected range.
  let range = workbook.getSelectedRange();

  // Clear all the formatting in that range.
  range.clear(ExcelScript.ClearApplyTo.formats);
}

clearAllConditionalFormats()

Limpa todos os formatos condicionais ativos no intervalo atual especificado.

clearAllConditionalFormats(): void;

Retornos

void

convertDataTypeToText()

Converte as células de intervalo com tipos de dados em texto.

convertDataTypeToText(): void;

Retornos

void

copyFrom(sourceRange, copyType, skipBlanks, transpose)

Copia dados de células ou formatação do intervalo de origem ou RangeAreas para o intervalo atual. O intervalo de destino pode ter um tamanho diferente do intervalo de origem ou RangeAreas. O destino é expandido automaticamente se for menor do que a origem. Nota: tal como a funcionalidade de cópia na IU do Excel, se o intervalo de destino for um múltiplo exato maior do que o intervalo de origem em linhas ou colunas, o conteúdo de origem é replicado várias vezes. Por exemplo, uma cópia de intervalo 2x2 para um intervalo 2x6 resultará em 3 cópias do intervalo 2x2 original.

copyFrom(
            sourceRange: Range | RangeAreas | string,
            copyType?: RangeCopyType,
            skipBlanks?: boolean,
            transpose?: boolean
        ): void;

Parâmetros

sourceRange

ExcelScript.Range | ExcelScript.RangeAreas | string

O intervalo de origem ou RangeAreas a partir do quais copiar. Quando a origem RangeAreas tem múltiplos intervalos, o respetivo formulário tem de ser capaz de ser criado ao remover linhas ou colunas completas de um intervalo retangular.

copyType

ExcelScript.RangeCopyType

O tipo de dados de célula ou formatação a copiar. A predefinição é "Tudo".

skipBlanks

boolean

Verdadeiro se ignorar células em branco no intervalo de origem. O padrão é false.

transpose

boolean

Verdadeiro se transpor as células no intervalo de destino. O padrão é false.

Retornos

void

Exemplos

/**
 * This script copies a table from one worksheet to a new worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the worksheet named "TableTemplate".
  let base = workbook.getWorksheet("TableTemplate");
  
  // Get the range to be copied based on the first table.
  let tableRange = base.getTables()[0].getRange();

  // Get the area in a new worksheet for the new table.
  let newWorksheet = workbook.addWorksheet();
  let newRange = newWorksheet.getRangeByIndexes(0,0, tableRange.getRowCount(), tableRange.getColumnCount());

  // Copy the existing data into the new range.
  newRange.copyFrom(tableRange);
}

delete(shift)

Exclui as células associadas ao intervalo.

delete(shift: DeleteShiftDirection): void;

Parâmetros

shift

ExcelScript.DeleteShiftDirection

Especifica como deslocar as células. Veja ExcelScript.DeleteShiftDirection para obter detalhes.

Retornos

void

Exemplos

/**
 * This sample creates a sample range, then deletes
 * "A1" using different DeleteShiftDirection values.
 */
function main(workbook: ExcelScript.Workbook) {
  // Add sample data to better visualize the delete changes.
  const currentSheet = workbook.getActiveWorksheet();
  currentSheet.getRange("A1:D4").setValues([
    [1,2,3,4],
    [5,6,7,8],
    [9,10,11,12],
    [13,14,15,16]]);

  // Delete A1 and shift the cells from the right to fill the space.
  // The value being deleted is 1.
  currentSheet.getRange("A1").delete(ExcelScript.DeleteShiftDirection.left);

  // Delete A1 and shift the cells from the bottom to fill the space.
  // The value being deleted is 2.
  currentSheet.getRange("A1").delete(ExcelScript.DeleteShiftDirection.up);

  // Log the sample range. The values should be:
  /*
    5, 3, 4, "",
    9, 6, 7, 8,
    13, 10, 11, 12,
    "", 14, 15, 16
  */
  console.log(currentSheet.getRange("A1:D4").getValues()); 
}

find(text, criteria)

Localiza certa cadeia de caracteres com base em critérios especificados. Se o intervalo atual for maior do que uma única célula, a pesquisa será limitada a esse intervalo, caso contrário, a pesquisa cobrirá toda a folha a partir dessa célula. Se não existirem correspondências, este método devolve undefined.

find(text: string, criteria: SearchCriteria): Range;

Parâmetros

text

string

A cadeia a localizar.

criteria

ExcelScript.SearchCriteria

Critérios de pesquisa adicionais, incluindo a direção da pesquisa e se a pesquisa precisa de corresponder a toda a célula ou ser sensível a maiúsculas e minúsculas.

Retornos

ExcelScript.Range

Exemplos

/**
 * This script searches through a table column and finds cells marked "no change". 
 * Those cells have "no change" replaced with the value from the cell to the left.
 * This script uses Range.find instead of Worksheet.findAll 
 * to limit the search to a specific range.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the range of a table named "Orders".
  let table = workbook.getTable("Orders");
  let range = table.getColumnByName("March").getRange();

  // Find all cells with the value "no change".
  let cellToOverwrite = range.find("no change", { completeMatch: true });
  while (cellToOverwrite) {
    let cellToCopyFrom = cellToOverwrite.getOffsetRange(0,-1);
    cellToOverwrite.setValue(cellToCopyFrom.getValue());
    cellToOverwrite = range.find("no change", { completeMatch: true });
  }
}

flashFill()

Efetua uma Pré-visualização da Conclusão Automática para o intervalo atual. A Pré-visualização da Conclusão Automática preenche automaticamente os dados quando detetar um padrão, pelo que o intervalo tem de ser um intervalo de colunas único e ter dados à sua volta para encontrar um padrão.

flashFill(): void;

Retornos

void

Exemplos

/**
 * This script uses the Flash Fill feature to complete a table.
 * See https://support.microsoft.com/office/3f9bcf1e-db93-4890-94a0-1578341f73f7
 * for the example table.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current, active worksheet.
  let currentWorksheet = workbook.getActiveWorksheet();

  // Get the data range with a pattern and cells to fill. C2 is filled in. C3:C6 are blank.
  let dataRange = currentWorksheet.getRange("C2:C6");

  // Flash fill the connected range. 
  dataRange.flashFill();
}

getAbsoluteResizedRange(numRows, numColumns)

Obtém um Range objeto com a mesma célula superior esquerda que o objeto atual Range , mas com os números especificados de linhas e colunas.

getAbsoluteResizedRange(numRows: number, numColumns: number): Range;

Parâmetros

numRows

number

O número de linhas do novo tamanho do intervalo.

numColumns

number

O número de colunas do novo tamanho do intervalo.

Retornos

ExcelScript.Range

getAddress()

Especifica a referência de intervalo no estilo A1. O valor do endereço contém a referência da folha (por exemplo, "Folha1! A1:B4").

getAddress(): string;

Retornos

string

Exemplos

/**
 * This script logs the address of the used range in each worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Iterate over every worksheet in the workbook.
  workbook.getWorksheets().forEach((sheet) => {
    // Get the used range for a single worksheet.
    let range = sheet.getUsedRange();

    // Print the address of the used range to the console.
    console.log(range.getAddress());
  });
}

getAddressLocal()

Representa a referência de intervalo para o intervalo especificado no idioma do utilizador.

getAddressLocal(): string;

Retornos

string

getBoundingRect(anotherRange)

Obtém o menor objeto de intervalo que abrange os intervalos determinados. Por exemplo, " GetBoundingRect B2:C5" e "D10:E15" é "B2:E15".

getBoundingRect(anotherRange: Range | string): Range;

Parâmetros

anotherRange

ExcelScript.Range | string

O nome do objeto, endereço ou intervalo do intervalo.

Retornos

ExcelScript.Range

Exemplos

/**
 * This script gets the bounding range of two existing ranges and puts a border around it.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let sheet = workbook.getActiveWorksheet();

  // Create two range objects for the sample.
  let range1 = sheet.getRange("B2:C5");
  let range2 = sheet.getRange("D10:E15");

  // Get the rectangular range that fully includes both ranges.
  let boundingRectangle = range1.getBoundingRect(range2);

  // Add a border around the whole bounding range (B2:E15).
  let format = boundingRectangle.getFormat();
  format.getRangeBorder(ExcelScript.BorderIndex.edgeTop).setStyle(ExcelScript.BorderLineStyle.continuous); // Top border
  format.getRangeBorder(ExcelScript.BorderIndex.edgeBottom).setStyle(ExcelScript.BorderLineStyle.continuous); // Bottom border
  format.getRangeBorder(ExcelScript.BorderIndex.edgeLeft).setStyle(ExcelScript.BorderLineStyle.continuous); // Left border
  format.getRangeBorder(ExcelScript.BorderIndex.edgeRight).setStyle(ExcelScript.BorderLineStyle.continuous); // Right border
}

getCell(row, column)

Obtém o objeto de intervalo que contém a célula única com base nos números de linha e de coluna. A célula pode estar fora dos limites do respetivo intervalo principal, desde que permaneça na grelha da folha de cálculo. A localização da célula retornada está relacionada à célula superior esquerda do intervalo.

getCell(row: number, column: number): Range;

Parâmetros

row

number

O número da linha da célula a ser recuperada. Indexados com zero.

column

number

O número da coluna da célula a ser recuperada. Indexados com zero.

Retornos

ExcelScript.Range

getCellCount()

Especifica o número de células no intervalo. Essa API retornará -1 se a contagem de células exceder 2^31-1 (2.147.483.647).

getCellCount(): number;

Retornos

number

getColumn(column)

Obtém uma coluna incluída no intervalo.

getColumn(column: number): Range;

Parâmetros

column

number

O número da coluna do intervalo a ser recuperado. Indexados com zero.

Retornos

ExcelScript.Range

getColumnCount()

Especifica o número total de colunas no intervalo.

getColumnCount(): number;

Retornos

number

Exemplos

/**
 * This sample provides the count of negative numbers that are present
 * in the used range of the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the working range.
  let usedRange = workbook.getActiveWorksheet().getUsedRange();
  let rowCount = usedRange.getRowCount();
  let columnCount = usedRange.getColumnCount();

  // Save the values locally to avoid repeatedly asking the workbook.
  let usedRangeValues = usedRange.getValues();

  // Start the negative number counter.
  let negativeCount = 0;

  // Iterate over the entire range looking for negative numbers.
  for (let i = 0; i < rowCount; i++) {
    for (let j = 0; j < columnCount; j++) {
      if (usedRangeValues[i][j] < 0) {
        negativeCount++;
      }
    }
  }

  // Log the negative number count to the console.
  console.log(negativeCount);
}

getColumnHidden()

Representa se todas as colunas no intervalo atual estão ocultas. O valor é true quando todas as colunas num intervalo estão ocultas. O valor é false quando não existem colunas no intervalo ocultadas. O valor é null quando algumas colunas num intervalo estão ocultas e outras colunas no mesmo intervalo não estão ocultas.

getColumnHidden(): boolean;

Retornos

boolean

getColumnIndex()

Especifica o número da coluna da primeira célula no intervalo. Indexados com zero.

getColumnIndex(): number;

Retornos

number

getColumnsAfter(count)

Obtém um determinado número de colunas à direita do objeto atual Range .

getColumnsAfter(count?: number): Range;

Parâmetros

count

number

Opcional. O número de colunas a serem incluídas no intervalo resultante. Em geral, use um número positivo para criar um intervalo fora do intervalo atual. Você também pode usar um número negativo para criar um intervalo dentro do intervalo atual. O valor padrão é 1.

Retornos

ExcelScript.Range

getColumnsBefore(count)

Obtém um determinado número de colunas à esquerda do objeto atual Range .

getColumnsBefore(count?: number): Range;

Parâmetros

count

number

Opcional. O número de colunas a serem incluídas no intervalo resultante. Em geral, use um número positivo para criar um intervalo fora do intervalo atual. Você também pode usar um número negativo para criar um intervalo dentro do intervalo atual. O valor padrão é 1.

Retornos

ExcelScript.Range

getConditionalFormat(id)

Devolve um formato condicional identificado pelo respetivo ID. Se o objeto de formato condicional não existir, este método devolve undefined.

getConditionalFormat(id: string): ConditionalFormat | undefined;

Parâmetros

id

string

O ID do formato condicional.

Retornos

ExcelScript.ConditionalFormat | undefined

getConditionalFormats()

A coleção do ConditionalFormats que intersecta o intervalo.

getConditionalFormats(): ConditionalFormat[];

Retornos

ExcelScript.ConditionalFormat[]

getDataValidation()

Retorna um objeto de validação de dados.

getDataValidation(): DataValidation;

Retornos

ExcelScript.DataValidation

Exemplos

/**
 * This script creates a drop-down selection list for a cell. It uses the existing values of the selected range as the choices for the list.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the values for data validation.
  let selectedRange = workbook.getSelectedRange();
  let rangeValues = selectedRange.getValues();

  // Convert the values into a comma-delimited string.
  let dataValidationListString = "";
  rangeValues.forEach((rangeValueRow) => {
    rangeValueRow.forEach((value) => {
      dataValidationListString += value + ",";
    });
  });

  // Clear the old range.
  selectedRange.clear(ExcelScript.ClearApplyTo.contents);

  // Apply the data validation to the first cell in the selected range.
  let targetCell = selectedRange.getCell(0,0);
  let dataValidation = targetCell.getDataValidation();

  // Set the content of the drop-down list.
  dataValidation.setRule({
      list: {
        inCellDropDown: true,
        source: dataValidationListString
      }
    });
}

getDirectPrecedents()

Devolve um WorkbookRangeAreas objeto que representa o intervalo que contém todas as células precedentes diretas de um intervalo especificado na mesma folha de cálculo ou em várias folhas de cálculo.

getDirectPrecedents(): WorkbookRangeAreas;

Retornos

ExcelScript.WorkbookRangeAreas

Exemplos

/**
 * This script finds the direct precedents of the active cell.
 * It changes the font and color of those precedent cells. 
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the active cell.
  const selected = workbook.getActiveCell();
  
  // Get the cells that are direct precedents of the current cell.
  const precedents : ExcelScript.WorkbookRangeAreas = selected.getDirectPrecedents();

  // Set the font to bold and the fill color to orange for all the precedent cells.
  precedents.getRanges().forEach(range => {
    range.getFormat().getFill().setColor("orange");
    range.getFormat().getFont().setBold(true);
  });
}

getEntireColumn()

Obtém um objeto que representa toda a coluna do intervalo (por exemplo, se o intervalo atual representar as células "B4:E11", getEntireColumn é um intervalo que representa as colunas "B:E").

getEntireColumn(): Range;

Retornos

ExcelScript.Range

getEntireRow()

Obtém um objeto que representa toda a linha do intervalo (por exemplo, se o intervalo atual representar as células "B4:E11", GetEntireRow é um intervalo que representa as linhas "4:11").

getEntireRow(): Range;

Retornos

ExcelScript.Range

getExtendedRange(direction, activeCell)

Devolve um objeto de intervalo que inclui o intervalo atual e até à margem do intervalo, com base na direção fornecida. Isto corresponde ao comportamento de Ctrl+Shift+Tecla de Seta na IU do Excel no Windows.

getExtendedRange(
            direction: KeyboardDirection,
            activeCell?: Range | string
        ): Range;

Parâmetros

direction

ExcelScript.KeyboardDirection

A direção da célula ativa.

activeCell

ExcelScript.Range | string

A célula ativa neste intervalo. Por predefinição, a célula ativa é a célula superior esquerda do intervalo. É gerado um erro se a célula ativa não estiver neste intervalo.

Retornos

ExcelScript.Range

Exemplos

/**
 * This script makes the font bold on all the contiguous cells between 
 * A1 and the bottom of the used range of the first column.
 */
function main(workbook: ExcelScript.Workbook)
{
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get every cell that's used between A1 and the end of the column.
  // This recreates the Ctrl+Shift+Down arrow key behavior.
  let firstCell = selectedSheet.getRange("A1");
  let firstColumn = firstCell.getExtendedRange(ExcelScript.KeyboardDirection.down);

  // Set the font to bold in that range.
  firstColumn.getFormat().getFont().setBold(true);
}

getFormat()

Retorna um objeto de formato que encapsula a fonte, o preenchimento, as bordas, o alinhamento e outras propriedades do intervalo.

getFormat(): RangeFormat;

Retornos

ExcelScript.RangeFormat

Exemplos

/**
 * This script gives the total row of a table a green color fill.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the first table in the workbook.
  let table = workbook.getTables()[0];

  // Get the range for the total row of the table.
  let totalRange = table.getTotalRowRange();

  // Set the fill color to green.
  totalRange.getFormat().getFill().setColor("green");
}

getFormula()

Representa a fórmula de célula na notação de estilo A1. Se o intervalo contiver múltiplas células, serão devolvidos os dados da primeira célula (representados pelo índice de linha de 0 e índice de colunas de 0).

getFormula(): string;

Retornos

string

Exemplos

/*
 * This script sets a cell's formula, 
 * then displays how Excel stores the cell's formula and value separately.
 */
function main(workbook: ExcelScript.Workbook) {
  let selectedSheet = workbook.getActiveWorksheet();

  // Set A1 to 2.
  let a1 = selectedSheet.getRange("A1");
  a1.setValue(2);

  // Set B1 to the formula =(2*A1), which should equal 4.
  let b1 = selectedSheet.getRange("B1")
  b1.setFormula("=(2*A1)");

  // Log the current results for `getFormula` and `getValue` at B1.
  console.log(`B1 - Formula: ${b1.getFormula()} | Value: ${b1.getValue()}`);
}

getFormulaLocal()

Representa a fórmula de célula na notação de estilo A1, no idioma do utilizador e na região de formatação de números. Por exemplo, a fórmula "=SUM(A1, 1.5)" em inglês seria "=SOMA(A1; 1,5)" em português. Se o intervalo contiver múltiplas células, serão devolvidos os dados da primeira célula (representados pelo índice de linha de 0 e índice de colunas de 0).

getFormulaLocal(): string;

Retornos

string

getFormulaR1C1()

Representa a fórmula da célula na notação de estilo R1C1. Se o intervalo contiver múltiplas células, serão devolvidos os dados da primeira célula (representados pelo índice de linha de 0 e índice de colunas de 0).

getFormulaR1C1(): string;

Retornos

string

getFormulas()

Representa a fórmula em notação A1. Se uma célula não tiver nenhuma fórmula, é devolvido o respetivo valor.

getFormulas(): string[][];

Retornos

string[][]

getFormulasLocal()

Representa a fórmula em notação A1, na formatação de número da localidade e no idioma do usuário. Por exemplo, a fórmula "=SUM(A1, 1.5)" em inglês seria "=SOMA(A1; 1,5)" em português. Se uma célula não tiver nenhuma fórmula, é devolvido o respetivo valor.

getFormulasLocal(): string[][];

Retornos

string[][]

getFormulasR1C1()

Representa a fórmula em notação no estilo L1C1. Se uma célula não tiver nenhuma fórmula, é devolvido o respetivo valor.

getFormulasR1C1(): string[][];

Retornos

string[][]

getHasSpill()

Representa se todas as células têm uma borda de despejo. Devolve true se todas as células tiverem um limite de transposição ou false se todas as células não tiverem um limite de transposição. Devolve null se existirem células com e sem limites de transposição dentro do intervalo.

getHasSpill(): boolean;

Retornos

boolean

getHeight()

Devolve a distância em pontos, para 100% de zoom, desde a margem superior do intervalo até à margem inferior do intervalo.

getHeight(): number;

Retornos

number

getHidden()

Representa se todas as células no intervalo atual estão ocultas. O valor é true quando todas as células num intervalo estão ocultas. O valor é false quando não existem células no intervalo ocultadas. O valor é null quando algumas células num intervalo estão ocultas e outras células no mesmo intervalo não estão ocultas.

getHidden(): boolean;

Retornos

boolean

getHyperlink()

Representa a hiperligação para o intervalo atual.

getHyperlink(): RangeHyperlink;

Retornos

ExcelScript.RangeHyperlink

Exemplos

/**
 * This sample clears all of the hyperlinks from the current worksheet
 * and removes the usual hyperlink formatting.
 */
function main(workbook: ExcelScript.Workbook, sheetName: string = 'Sheet1') {
  // Get the active worksheet. 
  let sheet = workbook.getWorksheet(sheetName);

  // Get the used range to operate on.
  // For large ranges (over 10000 entries), consider splitting the operation into batches for performance.
  const targetRange = sheet.getUsedRange(true);
  console.log(`Target Range to clear hyperlinks from: ${targetRange.getAddress()}`);

  const rowCount = targetRange.getRowCount();
  const colCount = targetRange.getColumnCount();
  console.log(`Searching for hyperlinks in ${targetRange.getAddress()} which contains ${(rowCount * colCount)} cells`);

  // Go through each individual cell looking for a hyperlink. 
  // This allows us to limit the formatting changes to only the cells with hyperlink formatting.
  let clearedCount = 0;
  for (let i = 0; i < rowCount; i++) {
    for (let j = 0; j < colCount; j++) {
      const cell = targetRange.getCell(i, j);
      const hyperlink = cell.getHyperlink();
      if (hyperlink) {
        cell.clear(ExcelScript.ClearApplyTo.hyperlinks);
        cell.getFormat().getFont().setUnderline(ExcelScript.RangeUnderlineStyle.none);
        cell.getFormat().getFont().setColor('Black');
        clearedCount++;
      }
    }
  }

  console.log(`Done. Cleared hyperlinks from ${clearedCount} cells`);
}

getImage()

Compõe o intervalo como uma imagem png codificada com base64.

getImage(): string;

Retornos

string

getIntersection(anotherRange)

Obtém o objeto de intervalo que representa a interseção retangular dos intervalos determinados. Se não for encontrada nenhuma interseção, este método devolve undefined.

getIntersection(anotherRange: Range | string): Range;

Parâmetros

anotherRange

ExcelScript.Range | string

O objeto Range ou o endereço do intervalo que será usado para determinar a interseção de intervalos.

Retornos

ExcelScript.Range

getIsEntireColumn()

Representa se o intervalo atual está em uma coluna inteira.

getIsEntireColumn(): boolean;

Retornos

boolean

getIsEntireRow()

Representa se o intervalo atual está em uma linha inteira.

getIsEntireRow(): boolean;

Retornos

boolean

getLastCell()

Obtém a última célula do intervalo. Por exemplo, a última célula de "B2:D5" é "D5".

getLastCell(): Range;

Retornos

ExcelScript.Range

getLastColumn()

Obtém a última coluna do intervalo. Por exemplo, a última coluna de "B2:D5" é "D2:D5".

getLastColumn(): Range;

Retornos

ExcelScript.Range

getLastRow()

Obtém a última linha do intervalo. Por exemplo, a última linha de "B2:D5" é "B5:D5".

getLastRow(): Range;

Retornos

ExcelScript.Range

getLeft()

Devolve a distância em pontos, para uma ampliação de 100%, desde a margem esquerda da folha de cálculo até à margem esquerda do intervalo.

getLeft(): number;

Retornos

number

getLinkedDataTypeState()

Representa o estado do tipo de dados da célula.

getLinkedDataTypeState(): LinkedDataTypeState;

Retornos

ExcelScript.LinkedDataTypeState

getLinkedDataTypeStates()

Representa o estado do tipo de dados de cada célula.

getLinkedDataTypeStates(): LinkedDataTypeState[][];

Retornos

ExcelScript.LinkedDataTypeState[][]

getMergedAreas()

Devolve um RangeAreas objeto que representa as áreas unidas neste intervalo. Tenha em atenção que se a contagem de áreas unidas neste intervalo for superior a 512, este método não devolverá o resultado. Se o RangeAreas objeto não existir, esta função devolve undefined.

getMergedAreas(): RangeAreas;

Retornos

ExcelScript.RangeAreas

getNumberFormat()

Representa o código de formato de número do Excel da célula para o intervalo especificado. Se o intervalo contiver múltiplas células, serão devolvidos os dados da primeira célula (representados pelo índice de linha de 0 e índice de colunas de 0).

getNumberFormat(): string;

Retornos

string

getNumberFormatCategories()

Representa a categoria do formato de número de cada célula.

getNumberFormatCategories(): NumberFormatCategory[][];

Retornos

ExcelScript.NumberFormatCategory[][]

Exemplos

/**
 * This script finds cells in a table column that are not formatted as currency
 * and sets the fill color to red.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the "Cost" column from the "Expenses" table.
  const table = workbook.getTable("Expenses");
  const costColumn = table.getColumnByName("Cost");
  const costColumnRange = costColumn.getRangeBetweenHeaderAndTotal();

  // Get the number format categories for the column's range.
  const numberFormatCategories = costColumnRange.getNumberFormatCategories();

  // If any cell in the column doesn't have a currency format, make the cell red.
  numberFormatCategories.forEach((category, index) =>{
    if (category[0] != ExcelScript.NumberFormatCategory.currency) {
      costColumnRange.getCell(index, 0).getFormat().getFill().setColor("red");
    }
  }); 
}

getNumberFormatCategory()

Especifica a categoria de formato de número da primeira célula no intervalo (representada pelo índice de linha de 0 e índice de coluna de 0).

getNumberFormatCategory(): NumberFormatCategory;

Retornos

ExcelScript.NumberFormatCategory

getNumberFormatLocal()

Representa o código de formato de número de célula do Excel para o intervalo especificado, com base nas definições de idioma do utilizador. O Excel não executa qualquer idioma ou coerção de formato ao obter ou definir a numberFormatLocal propriedade. Qualquer texto devolvido utiliza as cadeias formatadas localmente com base no idioma especificado nas definições do sistema. Se o intervalo contiver múltiplas células, serão devolvidos os dados da primeira célula (representados pelo índice de linha de 0 e índice de colunas de 0).

getNumberFormatLocal(): string;

Retornos

string

getNumberFormats()

Representa o código de formato de número do Excel para o intervalo especificado.

getNumberFormats(): string[][];

Retornos

string[][]

getNumberFormatsLocal()

Representa o código de formato de número do Excel para o intervalo especificado, com base nas definições de idioma do utilizador. O Excel não executa qualquer idioma ou coerção de formato ao obter ou definir a numberFormatLocal propriedade. Qualquer texto devolvido utiliza as cadeias formatadas localmente com base no idioma especificado nas definições do sistema.

getNumberFormatsLocal(): string[][];

Retornos

string[][]

getOffsetRange(rowOffset, columnOffset)

Obtém um objeto que representa um intervalo deslocado do intervalo especificado. A dimensão do intervalo retornado corresponde a esse intervalo. Se o intervalo resultante for imposto para fora dos limites da grade da planilha, o sistema gerará um erro.

getOffsetRange(rowOffset: number, columnOffset: number): Range;

Parâmetros

rowOffset

number

O número de linhas (positivo, negativo ou 0) com base no qual o intervalo deve ser deslocado. Valores positivos estão deslocados para baixo, e os valores negativos para cima.

columnOffset

number

O número de colunas (positivo, negativo ou 0) com base no qual o intervalo deve ser deslocado. Valores positivos estão deslocados para a direita, e os valores negativos para a esquerda.

Retornos

ExcelScript.Range

Exemplos

/**
 * This script gets adjacent cells using relative references.
 * Note that if the active cell is on the top row, part of the script fails, 
 * because it references the cell above the currently selected one.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the currently active cell in the workbook.
  let activeCell = workbook.getActiveCell();
  console.log(`The active cell's address is: ${activeCell.getAddress()}`);

  // Get the cell to the right of the active cell and set its value and color.
  let rightCell = activeCell.getOffsetRange(0,1);
  rightCell.setValue("Right cell");
  console.log(`The right cell's address is: ${rightCell.getAddress()}`);
  rightCell.getFormat().getFont().setColor("Magenta");
  rightCell.getFormat().getFill().setColor("Cyan");

  // Get the cell to the above of the active cell and set its value and color.
  // Note that this operation will fail if the active cell is in the top row.
  let aboveCell = activeCell.getOffsetRange(-1, 0);
  aboveCell.setValue("Above cell");
  console.log(`The above cell's address is: ${aboveCell.getAddress()}`);
  aboveCell.getFormat().getFont().setColor("White");
  aboveCell.getFormat().getFill().setColor("Black");
}

getPivotTables(fullyContained)

Obtém uma coleção de tabelas dinâmicas no âmbito que se sobrepõem ao intervalo.

getPivotTables(fullyContained?: boolean): PivotTable[];

Parâmetros

fullyContained

boolean

Se true, devolve apenas tabelas dinâmicas que estão totalmente contidas nos limites do intervalo. O valor predefinido é false.

Retornos

ExcelScript.PivotTable[]

getPredefinedCellStyle()

Representa o estilo de intervalo atual. Se os estilos das células forem inconsistentes, null serão devolvidos. Para estilos personalizados, o nome do estilo será devolvido. Para estilos incorporados, será devolvida uma cadeia que representa um valor na BuiltInStyle enumeração.

getPredefinedCellStyle(): string;

Retornos

string

getRangeEdge(direction, activeCell)

Devolve um objeto de intervalo que é a célula de limite da região de dados que corresponde à direção fornecida. Isto corresponde ao comportamento da tecla Ctrl+Seta na IU do Excel no Windows.

getRangeEdge(
            direction: KeyboardDirection,
            activeCell?: Range | string
        ): Range;

Parâmetros

direction

ExcelScript.KeyboardDirection

A direção da célula ativa.

activeCell

ExcelScript.Range | string

A célula ativa neste intervalo. Por predefinição, a célula ativa é a célula superior esquerda do intervalo. É gerado um erro se a célula ativa não estiver neste intervalo.

Retornos

ExcelScript.Range

Exemplos

/**
 * This script adds the value "Total" after the end of the first column.
 */
function main(workbook: ExcelScript.Workbook)
{
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get the last used cell at the end of the column.
  // This recreates the Ctrl+Down arrow key behavior.
  let firstCell = selectedSheet.getRange("A1");
  let firstColumn = selectedSheet.getRange("A1").getRangeEdge(ExcelScript.KeyboardDirection.down);
  let cellAfter = firstColumn.getOffsetRange(1, 0);

  // Set the value of the cell after the current end of the used column to "Total".
  cellAfter.setValue("Total");
}

getResizedRange(deltaRows, deltaColumns)

Obtém um Range objeto semelhante ao objeto atual Range , mas com o canto inferior direito expandido (ou contratado) por algumas linhas e colunas.

getResizedRange(deltaRows: number, deltaColumns: number): Range;

Parâmetros

deltaRows

number

O número de linhas pelo qual expandir o canto inferior direito, referente ao intervalo atual. Use um número positivo para expandir o intervalo ou um número negativo para diminuí-lo.

deltaColumns

number

O número de colunas pelas quais pretende expandir o canto inferior direito, relativamente ao intervalo atual. Use um número positivo para expandir o intervalo ou um número negativo para diminuí-lo.

Retornos

ExcelScript.Range

Exemplos

/**
 * This script copies the formatting in the active cell to the neighboring cells.
 * Note that this script only works when the active cell isn't on an edge of the worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the active cell.
  let activeCell = workbook.getActiveCell();

  // Get the cell that's one row above and one column to the left of the active cell.
  let cornerCell = activeCell.getOffsetRange(-1,-1);

  // Get a range that includes all the cells surrounding the active cell.
  let surroundingRange = cornerCell.getResizedRange(2, 2)

  // Copy the formatting from the active cell to the new range.
  surroundingRange.copyFrom(
    activeCell, /* The source range. */
    ExcelScript.RangeCopyType.formats /* What to copy. */
  );
}

getRow(row)

Obtém uma linha contida no intervalo.

getRow(row: number): Range;

Parâmetros

row

number

O número da linha do intervalo a ser recuperado. Indexados com zero.

Retornos

ExcelScript.Range

getRowCount()

Retorna o número total de linhas no intervalo.

getRowCount(): number;

Retornos

number

Exemplos

/**
 * This sample provides the count of negative numbers that are present
 * in the used range of the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the working range.
  let usedRange = workbook.getActiveWorksheet().getUsedRange();
  let rowCount = usedRange.getRowCount();
  let columnCount = usedRange.getColumnCount();

  // Save the values locally to avoid repeatedly asking the workbook.
  let usedRangeValues = usedRange.getValues();

  // Start the negative number counter.
  let negativeCount = 0;

  // Iterate over the entire range looking for negative numbers.
  for (let i = 0; i < rowCount; i++) {
    for (let j = 0; j < columnCount; j++) {
      if (usedRangeValues[i][j] < 0) {
        negativeCount++;
      }
    }
  }

  // Log the negative number count to the console.
  console.log(negativeCount);
}

getRowHidden()

Representa se todas as linhas no intervalo atual estão ocultas. O valor é true quando todas as linhas num intervalo estão ocultas. O valor é false quando não existem linhas no intervalo ocultadas. O valor é null quando algumas linhas num intervalo estão ocultas e outras linhas no mesmo intervalo não estão ocultas.

getRowHidden(): boolean;

Retornos

boolean

getRowIndex()

Representa o número de linhas da primeira célula no intervalo. Indexados com zero.

getRowIndex(): number;

Retornos

number

getRowsAbove(count)

Obtém um determinado número de linhas acima do objeto atual Range .

getRowsAbove(count?: number): Range;

Parâmetros

count

number

Opcional. O número de linhas a serem incluídas no intervalo resultante. Em geral, use um número positivo para criar um intervalo fora do intervalo atual. Você também pode usar um número negativo para criar um intervalo dentro do intervalo atual. O valor padrão é 1.

Retornos

ExcelScript.Range

getRowsBelow(count)

Obtém um determinado número de linhas abaixo do objeto atual Range .

getRowsBelow(count?: number): Range;

Parâmetros

count

number

Opcional. O número de linhas a serem incluídas no intervalo resultante. Em geral, use um número positivo para criar um intervalo fora do intervalo atual. Você também pode usar um número negativo para criar um intervalo dentro do intervalo atual. O valor padrão é 1.

Retornos

ExcelScript.Range

getSavedAsArray()

Representa se todas as células seriam guardadas como uma fórmula de matriz. Devolve true se todas as células fossem guardadas como uma fórmula de matriz ou false se todas as células não fossem guardadas como uma fórmula de matriz. Devolve null se algumas células fossem guardadas como uma fórmula de matriz e algumas não seriam.

getSavedAsArray(): boolean;

Retornos

boolean

getSort()

Representa a classificação de intervalo do intervalo atual.

getSort(): RangeSort;

Retornos

ExcelScript.RangeSort

getSpecialCells(cellType, cellValueType)

Obtém o RangeAreas objeto, composto por um ou mais intervalos, que representa todas as células que correspondem ao tipo e valor especificados. Se não forem encontradas células especiais, este método devolve undefined.

getSpecialCells(
            cellType: SpecialCellType,
            cellValueType?: SpecialCellValueType
        ): RangeAreas;

Parâmetros

cellType

ExcelScript.SpecialCellType

O tipo de células a incluir.

cellValueType

ExcelScript.SpecialCellValueType

Se cellType for ou constantsformulas, este argumento é utilizado para determinar que tipos de células deve incluir no resultado. Estes valores podem ser combinados para devolver mais do que um tipo. O padrão é selecionar todas as constantes ou as fórmulas, independente do tipo.

Retornos

ExcelScript.RangeAreas

Exemplos

/**
 * This sample gets all the blank cells in the current worksheet's used range. It then highlights all those cells with a yellow background.
 */
function main(workbook: ExcelScript.Workbook) {
    // Get the current used range.
    let range = workbook.getActiveWorksheet().getUsedRange();
    
    // Get all the blank cells.
    let blankCells = range.getSpecialCells(ExcelScript.SpecialCellType.blanks);
    // Highlight the blank cells with a yellow background.
    blankCells.getFormat().getFill().setColor("yellow");
}

getSpillingToRange()

Obtém objeto range que contém o intervalo de despejo quando chamado em uma célula âncora. Se o intervalo não for uma célula de âncora ou não for possível localizar o intervalo de derrames, este método devolve undefined.

getSpillingToRange(): Range;

Retornos

ExcelScript.Range

getSpillParent()

Obtém o objeto de intervalo que contém a célula de âncora para a célula a ser transbordada. Se não for uma célula transbordada ou se for fornecida mais do que uma célula, este método devolve undefined.

getSpillParent(): Range;

Retornos

ExcelScript.Range

getSurroundingRegion()

Devolve um Range objeto que representa a região circundante para a célula superior esquerda neste intervalo. Uma região ao redor é um intervalo limitado por qualquer combinação de linhas e colunas em branco em relação a esse intervalo.

getSurroundingRegion(): Range;

Retornos

ExcelScript.Range

getTables(fullyContained)

Obtém uma coleção de tabelas com escopo que se sobrepõe ao intervalo.

getTables(fullyContained?: boolean): Table[];

Parâmetros

fullyContained

boolean

Se true, devolve apenas as tabelas que estão totalmente contidas nos limites do intervalo. O valor predefinido é false.

Retornos

ExcelScript.Table[]

getText()

Representa o valor de Texto do intervalo especificado. O valor de texto não depende da largura da célula. A substituição pelo sinal #, que ocorre na interface de usuário do Excel, não afeta o valor de texto retornado pela API. Se o intervalo contiver múltiplas células, serão devolvidos os dados da primeira célula (representados pelo índice de linha de 0 e índice de colunas de 0).

getText(): string;

Retornos

string

getTexts()

Valores de texto do intervalo especificado. O valor de texto não depende da largura da célula. A substituição do sinal de número (#) que ocorre na IU do Excel não afetará o valor de texto devolvido pela API.

getTexts(): string[][];

Retornos

string[][]

getTop()

Devolve a distância em pontos, para uma ampliação de 100%, desde a margem superior da folha de cálculo até à margem superior do intervalo.

getTop(): number;

Retornos

number

getUsedRange(valuesOnly)

Retorna o intervalo usado do objeto de intervalo determinado. Se não existirem células utilizadas dentro do intervalo, este método devolve undefined.

getUsedRange(valuesOnly?: boolean): Range;

Parâmetros

valuesOnly

boolean

Considera apenas as células com valores como células usadas.

Retornos

ExcelScript.Range

getValue()

Representa o valor não processado do intervalo especificado. Os dados retornados podem ser dos tipos: cadeia de caracteres, número ou booliano. Células que contêm um erro retornarão a cadeia de caracteres de erro. Se o intervalo contiver múltiplas células, serão devolvidos os dados da primeira célula (representados pelo índice de linha de 0 e índice de colunas de 0).

getValue(): string | number | boolean;

Retornos

string | number | boolean

Exemplos

/**
 * This sample reads the value of A1 and prints it to the console.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get the value of cell A1.
  let range = selectedSheet.getRange("A1");
  
  // Print the value of A1.
  console.log(range.getValue());
}

getValues()

Representa os valores brutos do intervalo especificado. Os dados devolvidos podem ser uma cadeia, número ou booleano. Células que contêm um erro retornarão a cadeia de caracteres de erro. Se o valor devolvido começar com uma adição ("+"), sinal de subtração ("-"), ou sinal de igual ("="), o Excel interpreta este valor como uma fórmula.

getValues(): (string | number | boolean)[][];

Retornos

(string | number | boolean)[][]

getValueType()

Representa o tipo de dados na célula. Se o intervalo contiver múltiplas células, serão devolvidos os dados da primeira célula (representados pelo índice de linha de 0 e índice de colunas de 0).

getValueType(): RangeValueType;

Retornos

ExcelScript.RangeValueType

Exemplos

/**
 * This script formats rows in a worksheet based on the first value in that row. 
 * If it's the boolean value TRUE, the row is bolded. 
 * If it's FALSE, nothing is changed. 
 * If the value type isn't a boolean, the row is italicized.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the used range in the active worksheet.
  const sheet = workbook.getActiveWorksheet();
  const usedRange = sheet.getUsedRange();

  // Get the values in the first column.
  const firstColumnValues = usedRange.getColumn(0).getValues();

  // Look at the first cell in each row.
  const rowCount = usedRange.getRowCount();
  for (let i = 0; i < rowCount; i++) {
    // Get the type of the first cell to make sure it's a boolean.
    let firstValueType = usedRange.getCell(i, 0).getValueType();

    // Set the bold or italic of the row as described earlier.
    if (firstValueType === ExcelScript.RangeValueType.boolean) {
      if (firstColumnValues[i][0] as boolean === true) {
        usedRange.getRow(i).getFormat().getFont().setBold(true);
      } else {
        usedRange.getRow(i).getFormat().getFont().setBold(false);
      }
    } else {
      usedRange.getRow(i).getFormat().getFont().setItalic(true);
    }
  }
}

getValueTypes()

Especifica o tipo de dados em cada célula.

getValueTypes(): RangeValueType[][];

Retornos

ExcelScript.RangeValueType[][]

getVisibleView()

Representa as linhas visíveis do intervalo atual.

getVisibleView(): RangeView;

Retornos

ExcelScript.RangeView

Exemplos

/**
 * This script copies values and formatting from the 
 * visible range of a table in Sheet1 into Sheet2.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the filtered data from Sheet1.
  const currentSheet = workbook.getWorksheet("Sheet1");
  const table = currentSheet.getTables()[0];
  const visibleTableRange: ExcelScript.RangeView = table.getRange().getVisibleView();
  const source = currentSheet.getRanges(visibleTableRange.getCellAddresses().toString());

  // Copy the data into the other sheet.
  const otherSheet = workbook.getWorksheet("Sheet2");
  const otherRangeCorner = otherSheet.getRange("A1");
  otherRangeCorner.copyFrom(source, ExcelScript.RangeCopyType.all);
}

getWidth()

Devolve a distância em pontos, para um zoom de 100%, desde a margem esquerda do intervalo até à margem direita do intervalo.

getWidth(): number;

Retornos

number

getWorksheet()

A planilha que contém o intervalo atual.

getWorksheet(): Worksheet;

Retornos

ExcelScript.Worksheet

group(groupOption)

Grupos colunas e linhas para um destaque.

group(groupOption: GroupOption): void;

Parâmetros

groupOption

ExcelScript.GroupOption

Especifica como o intervalo pode ser agrupado por linhas ou colunas. É InvalidArgument gerado um erro quando a opção de grupo difere da propriedade ou isEntireColumn do isEntireRow intervalo (ou seja, range.isEntireRow é verdadeiro e groupOption é "ByColumns" ou range.isEntireColumn é verdadeiro e groupOption é "ByRows").

Retornos

void

Exemplos

/**
 * This script creates a two-level column-based outline on Sheet1.
 */
function main(workbook: ExcelScript.Workbook) {
  // Group columns A-F in the worksheet named Sheet1.
  const sheet = workbook.getWorksheet("Sheet1");
  const firstLevel = sheet.getRange("A:F");
  firstLevel.group(ExcelScript.GroupOption.byColumns);
  
  // Create a second level to the outline by grouping subsections.
  sheet.getRange("A:B").group(ExcelScript.GroupOption.byColumns);
  sheet.getRange("D:E").group(ExcelScript.GroupOption.byColumns);
}

hideGroupDetails(groupOption)

Oculta os detalhes do grupo de linhas ou colunas.

hideGroupDetails(groupOption: GroupOption): void;

Parâmetros

groupOption

ExcelScript.GroupOption

Especifica se pretende ocultar os detalhes de linhas agrupadas ou colunas agrupadas.

Retornos

void

insert(shift)

Insere uma célula ou um intervalo de células na planilha, no lugar desse intervalo, e desloca as outras células para liberar espaço. Devolve um novo Range objeto no espaço em branco agora.

insert(shift: InsertShiftDirection): Range;

Parâmetros

shift

ExcelScript.InsertShiftDirection

Especifica como deslocar as células. Veja ExcelScript.InsertShiftDirection para obter detalhes.

Retornos

ExcelScript.Range

Exemplos

/**
 * This script inserts headers at the top of the worksheet.
 */
function main(workbook: ExcelScript.Workbook)
{
  let currentSheet = workbook.getActiveWorksheet();

  // Create headers for 3 columns.
  let myHeaders = [["NAME", "ID", "ROLE"]];

  // Add a blank first row and push existing data down a row.
  let firstRow = currentSheet.getRange("1:1");
  firstRow.insert(ExcelScript.InsertShiftDirection.down);

  // Add the headers.
  currentSheet.getRange("A1:C1").setValues(myHeaders);
}

merge(across)

Mescla as células do intervalo em uma região da planilha.

merge(across?: boolean): void;

Parâmetros

across

boolean

Opcional. Defina true para unir células em cada linha do intervalo especificado como células unidas separadas. O valor predefinido é false.

Retornos

void

Exemplos

/**
 * This script merges a group of cells into a single region.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the active worksheet.
  const selectedSheet = workbook.getActiveWorksheet();

  // Merge cells A1 through A4.
  const range = selectedSheet.getRange("A1:A4");
  range.merge();
}

moveTo(destinationRange)

Move valores de células, formatação e fórmulas do intervalo atual para o intervalo de destino, substituindo as informações antigas nessas células. O intervalo de destino será expandido automaticamente se for menor do que o intervalo atual. As células no intervalo de destino que estejam fora da área do intervalo original não são alteradas.

moveTo(destinationRange: Range | string): void;

Parâmetros

destinationRange

ExcelScript.Range | string

destinationRange Especifica o intervalo para onde as informações neste intervalo serão movidas.

Retornos

void

removeDuplicates(columns, includesHeader)

Remove valores duplicados do intervalo especificado pelas colunas.

removeDuplicates(
            columns: number[],
            includesHeader: boolean
        ): RemoveDuplicatesResult;

Parâmetros

columns

number[]

As colunas dentro do intervalo que podem conter duplicados. Tem de especificar pelo menos uma coluna. Indexados com zero.

includesHeader

boolean

Verdadeiro se os dados de entrada contiverem cabeçalho. O padrão é false.

Retornos

ExcelScript.RemoveDuplicatesResult

Exemplos

/**
 * This script removes duplicate rows from a range.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the used range of the active worksheet.
  const usedRange = workbook.getActiveWorksheet().getUsedRange();

  // Remove any row that has a same value in the 0-indexed column as a previous row.
  const removedResults = usedRange.removeDuplicates([0], true);

  // Log the count of removed rows.
  console.log(`Rows removed: ${removedResults.getRemoved()}.`);
}

replaceAll(text, replacement, criteria)

Localiza e substitui a cadeia de caracteres fornecida com base nos critérios especificados no intervalo atual.

replaceAll(
            text: string,
            replacement: string,
            criteria: ReplaceCriteria
        ): number;

Parâmetros

text

string

Cadeia a localizar.

replacement

string

A cadeia que substitui a cadeia original.

criteria

ExcelScript.ReplaceCriteria

Critérios de substituição adicionais.

Retornos

number

Exemplos

/**
 * This script searches through a table column and replaces  
 * cells marked "monthly special" with "parsnip".
 * This script uses Range.replaceAll instead of Worksheet.replaceAll
 * to limit the search to a specific range.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the range of a table named "Orders".
  let table = workbook.getTable("Orders");
  let range = table.getColumnByName("Vegetable").getRange();
  
  // Change the value of any cells with the value "monthly special".
  range.replaceAll("monthly special", "parsnip", {completeMatch: true});
}

select()

Seleciona o intervalo especificado na interface do usuário do Excel.

select(): void;

Retornos

void

Exemplos

/**
 * This script selects the first row of a table.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the first table on the current worksheet.
  const sheet = workbook.getActiveWorksheet()
  const table = sheet.getTables()[0];

  // Get the first data row in the table.
  const row = table.getRangeBetweenHeaderAndTotal().getRow(0);

  // Select the first data row.
  row.select();
}

setColumnHidden(columnHidden)

Representa se todas as colunas no intervalo atual estão ocultas. O valor é true quando todas as colunas num intervalo estão ocultas. O valor é false quando não existem colunas no intervalo ocultadas. O valor é null quando algumas colunas num intervalo estão ocultas e outras colunas no mesmo intervalo não estão ocultas.

setColumnHidden(columnHidden: boolean): void;

Parâmetros

columnHidden

boolean

Retornos

void

setDirty()

Define um intervalo a ser recalculado quando o próximo recálculo ocorrer.

setDirty(): void;

Retornos

void

setFormula(formula)

Define a fórmula da célula na notação de estilo A1. Se o intervalo contiver múltiplas células, cada célula no intervalo especificado será atualizada com os dados de entrada.

setFormula(formula: string): void;

Parâmetros

formula

string

Retornos

void

Exemplos

/*
 * This script sets a cell's formula, 
 * then displays how Excel stores the cell's formula and value separately.
 */
function main(workbook: ExcelScript.Workbook) {
  let selectedSheet = workbook.getActiveWorksheet();

  // Set A1 to 2.
  let a1 = selectedSheet.getRange("A1");
  a1.setValue(2);

  // Set B1 to the formula =(2*A1), which should equal 4.
  let b1 = selectedSheet.getRange("B1")
  b1.setFormula("=(2*A1)");

  // Log the current results for `getFormula` and `getValue` at B1.
  console.log(`B1 - Formula: ${b1.getFormula()} | Value: ${b1.getValue()}`);
}

setFormulaLocal(formulaLocal)

Defina a fórmula de célula na notação de estilo A1, no idioma do utilizador e na região de formatação de números. Por exemplo, a fórmula "=SUM(A1, 1.5)" em inglês seria "=SOMA(A1; 1,5)" em português. Se o intervalo contiver múltiplas células, cada célula no intervalo especificado será atualizada com os dados de entrada.

setFormulaLocal(formulaLocal: string): void;

Parâmetros

formulaLocal

string

Retornos

void

setFormulaR1C1(formulaR1C1)

Define a fórmula da célula na notação de estilo R1C1. Se o intervalo contiver múltiplas células, cada célula no intervalo especificado será atualizada com os dados de entrada.

setFormulaR1C1(formulaR1C1: string): void;

Parâmetros

formulaR1C1

string

Retornos

void

setFormulas(formulas)

Representa a fórmula em notação A1. Se uma célula não tiver nenhuma fórmula, é devolvido o respetivo valor.

setFormulas(formulas: string[][]): void;

Parâmetros

formulas

string[][]

Retornos

void

Exemplos

/**
 * This script sets the values of a range, then adds SUM formulas to calculate
 * the totals for each row of that range. 
 */
function main(workbook: ExcelScript.Workbook)
{
  let currentSheet = workbook.getActiveWorksheet();

  // Set the values of a range.
  let values = [[1, 2, 4], [8, 16, 32], [64, 128, 256]];
  let valueRange = currentSheet.getRange("A1:C3");
  valueRange.setValues(values);

  // Set the formulas of a range.
  let formulas = [["=SUM(A1:C1)"], ["=SUM(A2:C2)"], ["=SUM(A3:C3)"]];
  let formulaRange = currentSheet.getRange("D1:D3");
  formulaRange.setFormulas(formulas);
}

setFormulasLocal(formulasLocal)

Representa a fórmula em notação A1, na formatação de número da localidade e no idioma do usuário. Por exemplo, a fórmula "=SUM(A1, 1.5)" em inglês seria "=SOMA(A1; 1,5)" em português. Se uma célula não tiver nenhuma fórmula, é devolvido o respetivo valor.

setFormulasLocal(formulasLocal: string[][]): void;

Parâmetros

formulasLocal

string[][]

Retornos

void

setFormulasR1C1(formulasR1C1)

Representa a fórmula em notação no estilo L1C1. Se uma célula não tiver nenhuma fórmula, é devolvido o respetivo valor.

setFormulasR1C1(formulasR1C1: string[][]): void;

Parâmetros

formulasR1C1

string[][]

Retornos

void

setHyperlink(hyperlink)

Representa a hiperligação para o intervalo atual.

setHyperlink(hyperlink: RangeHyperlink): void;

Parâmetros

hyperlink

ExcelScript.RangeHyperlink

Retornos

void

Exemplos

/** 
 * This script inserts a hyperlink to the first cell of the last worksheet in the workbook.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the active cell.
  let cell = workbook.getActiveCell();

  // Get the last worksheet in the workbook.
  // Note that this might be the current sheet if there's only one worksheet.
  let lastSheet = workbook.getLastWorksheet();

  // Get sheet name. 
  let linkedSheetName = lastSheet.getName();
  console.log(`Setting hyperlink of ${cell.getAddress()} to the ${linkedSheetName} sheet's A1 cell`);

  // Set the text for the hyperlink.
  let value = `Click to go to: ${linkedSheetName}`;

  // Create the hyperlink using that cell's value.
  cell.setHyperlink({
    textToDisplay: value.toString(),
    screenTip: `Navigate to ${linkedSheetName}`,
    documentReference: `${linkedSheetName}!A1`
  });
}

setNumberFormat(numberFormat)

Define a célula código de formato de número do Excel para o intervalo especificado. Se o intervalo contiver múltiplas células, cada célula no intervalo especificado será atualizada com os dados de entrada.

setNumberFormat(numberFormat: string): void;

Parâmetros

numberFormat

string

Retornos

void

Exemplos

/**
 * This script sets the number format in column C to show the data as a percentage.
 */
function main(workbook: ExcelScript.Workbook) {
  const  selectedSheet = workbook.getActiveWorksheet();
  
  // Set number format for column C to a percentage that rounds to the nearest percentage point.
  selectedSheet.getRange("C:C").setNumberFormat("0%");
}

setNumberFormatLocal(numberFormatLocal)

Define a célula código de formato de número do Excel para o intervalo especificado, com base nas definições de idioma do utilizador. O Excel não executa qualquer idioma ou coerção de formato ao obter ou definir a numberFormatLocal propriedade. Qualquer texto devolvido utiliza as cadeias formatadas localmente com base no idioma especificado nas definições do sistema. Se o intervalo contiver múltiplas células, cada célula no intervalo especificado será atualizada com os dados de entrada.

setNumberFormatLocal(numberFormatLocal: string): void;

Parâmetros

numberFormatLocal

string

Retornos

void

Exemplos

/**
 * This script sets the number format in column D to show the data as a percentage with a decimal.
 */
function main(workbook: ExcelScript.Workbook) {
  const  selectedSheet = workbook.getActiveWorksheet();
  
  // Set number format for column D to a percentage that rounds to the nearest tenth of a percentage.
  selectedSheet.getRange("D:D").setNumberFormatLocal("0.0%");
}

setNumberFormats(numberFormats)

Representa o código de formato de número do Excel para o intervalo especificado.

setNumberFormats(numberFormats: string[][]): void;

Parâmetros

numberFormats

string[][]

Retornos

void

setNumberFormatsLocal(numberFormatsLocal)

Representa o código de formato de número do Excel para o intervalo especificado, com base nas definições de idioma do utilizador. O Excel não executa qualquer idioma ou coerção de formato ao obter ou definir a numberFormatLocal propriedade. Qualquer texto devolvido utiliza as cadeias formatadas localmente com base no idioma especificado nas definições do sistema.

setNumberFormatsLocal(numberFormatsLocal: string[][]): void;

Parâmetros

numberFormatsLocal

string[][]

Retornos

void

setPredefinedCellStyle(predefinedCellStyle)

Representa o estilo de intervalo atual.

setPredefinedCellStyle(predefinedCellStyle: string): void;

Parâmetros

predefinedCellStyle

string

Retornos

void

setRowHidden(rowHidden)

Representa se todas as linhas no intervalo atual estão ocultas. O valor é true quando todas as linhas num intervalo estão ocultas. O valor é false quando não existem linhas no intervalo ocultadas. O valor é null quando algumas linhas num intervalo estão ocultas e outras linhas no mesmo intervalo não estão ocultas.

setRowHidden(rowHidden: boolean): void;

Parâmetros

rowHidden

boolean

Retornos

void

setValue(value)

Define o valor não processado do intervalo especificado. Os dados que estão a ser definidos podem ser do tipo cadeia, número ou um booleano. null o valor será ignorado (não definido ou substituído no Excel). Se o intervalo contiver múltiplas células, cada célula no intervalo especificado será atualizada com os dados de entrada.

setValue(value: any): void;

Parâmetros

value

any

Retornos

void

setValues(values)

Define os valores não processados do intervalo especificado. Os dados fornecidos podem ser uma cadeia, número ou booleano. Se o valor fornecido começar com uma adição ("+"), sinal de subtração ("-"), ou sinal de igual ("="), o Excel interpreta este valor como uma fórmula.

setValues(values: (string | number | boolean)[][]): void;

Parâmetros

values

(string | number | boolean)[][]

Retornos

void

Exemplos

/**
 * This sample inserts some pre-loaded data into a range.
 * It also shows how to get a range that fits the data.
 */
 function main(workbook: ExcelScript.Workbook) {
   // Get the active cell.
   let currentCell = workbook.getActiveCell();
   
   // Calculate the range needed to fit the given data.
   let targetRange = currentCell.getResizedRange(DATA.length - 1, DATA[0].length - 1);

   // Set range values to the data.
   targetRange.setValues(DATA);

   // Autofit the columns so the worksheet is readable. 
   targetRange.getFormat().autofitColumns();
 }

 /* 
  * This sample's data is in a static 2-dimensional array.
  * You could also get the input from other ranges or sources.
  * Note that each row must have the same number of columns to be valid. 
  */
 const DATA = [
   ['Date', 'Salesperson', 'Product', 'Amount']
   , ['3/2/2020', 'Anne', 'Pizza', '$1400']
   , ['3/2/2020', 'Mariya', 'Pizza', '$1700']
   , ['3/7/2020', 'Mark', 'Sandwiches', '$1010']
   , ['3/24/2020', 'Anne', 'Pizza', '$750']
   , ['3/28/2020', 'Mark', 'Salads', '$510']
   , ['4/17/2020', 'Laura', 'Salads', '$900']
   , ['4/17/2020', 'Mariya', 'Salads', '$1600']
   , ['4/28/2020', 'Laura', 'Sandwiches', '$680']
 ];

showCard()

Exibe o cartão para uma célula ativa se ele tiver um conteúdo valioso.

showCard(): void;

Retornos

void

showGroupDetails(groupOption)

Mostra os detalhes do grupo de linhas ou colunas.

showGroupDetails(groupOption: GroupOption): void;

Parâmetros

groupOption

ExcelScript.GroupOption

Especifica se pretende mostrar os detalhes de linhas agrupadas ou colunas agrupadas.

Retornos

void

ungroup(groupOption)

Desagrupar colunas e linhas para um destaque.

ungroup(groupOption: GroupOption): void;

Parâmetros

groupOption

ExcelScript.GroupOption

Especifica como o intervalo pode ser desagrupar por linhas ou colunas.

Retornos

void

unmerge()

Desfaz a mesclagem das células do intervalo em células separadas.

unmerge(): void;

Retornos

void

Exemplos

/**
 * This script unmerges every used cell in the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the active worksheet.
  const selectedSheet = workbook.getActiveWorksheet();

  // Separate all regions into single cells in the currently used range.
  const range = selectedSheet.getUsedRange();
  range.unmerge();
}