Excel.Range class

Referência

Pacote:: excel

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. Para saber mais sobre como os intervalos são utilizados em toda a API, comece com Intervalos na API JavaScript do Excel.

Extends: OfficeExtension.ClientObject

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

// Get a Range object by its address.
await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const range = worksheet.getRange(rangeAddress);
    const cell = range.getCell(0,0);
    cell.load('address');
    await context.sync();
    
    console.log(cell.address);
});

Propriedades

address	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").
addressLocal	Representa a referência de intervalo para o intervalo especificado no idioma do utilizador.
cellCount	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).
columnCount	Especifica o número total de colunas no intervalo.
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.
columnIndex	Especifica o número da coluna da primeira célula no intervalo. Indexados com zero.
context	O contexto do pedido associado ao objeto . Esta ação liga o processo do suplemento ao processo da aplicação anfitriã do Office.
format	Retorna um objeto de formato que encapsula a fonte, o preenchimento, as bordas, o alinhamento e outras propriedades do intervalo.
formulas	Representa a fórmula em notação A1. Se uma célula não tiver nenhuma fórmula, é devolvido o respetivo valor.
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.
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.
hidden	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.
numberFormat	Representa o código de formato de número do Excel para o intervalo especificado. Para obter mais informações sobre a formatação de números do Excel, consulte Códigos de formato de número.
rowCount	Retorna o número total de linhas no intervalo.
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.
rowIndex	Representa o número de linhas da primeira célula no intervalo. Indexados com zero.
sort	Representa a classificação de intervalo do intervalo atual.
text	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.
values	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.
valueTypes	Especifica o tipo de dados em cada célula.
worksheet	A planilha que contém o intervalo atual.

Métodos

clear(applyTo)	Limpar valores de intervalo e formatação, como preenchimento e limite.
clear(applyToString)	Limpar valores de intervalo e formatação, como preenchimento e limite.
delete(shift)	Exclui as células associadas ao intervalo.
delete(shiftString)	Exclui as células associadas ao intervalo.
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.
getColumn(column)	Obtém uma coluna incluída no intervalo.
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` .
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").
getIntersection(anotherRange)	Obtém o objeto de intervalo que representa a interseção retangular dos intervalos determinados.
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".
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.
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.
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` .
getUsedRange(valuesOnly)	Retorna o intervalo usado do objeto de intervalo determinado. Se não existirem células utilizadas dentro do intervalo, esta função gerará um `ItemNotFound` erro.
getVisibleView()	Representa as linhas visíveis do intervalo atual.
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(shiftString)	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.
load(options)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar `context.sync()` antes de ler as propriedades.
load(propertyNames)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar `context.sync()` antes de ler as propriedades.
load(propertyNamesAndPaths)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar `context.sync()` antes de ler as propriedades.
merge(across)	Mescla as células do intervalo em uma região da planilha.
select()	Seleciona o intervalo especificado na interface do usuário do Excel.
set(properties, options)	Define várias propriedades de um objeto ao mesmo tempo. Pode transmitir um objeto simples com as propriedades adequadas ou outro objeto de API do mesmo tipo.
set(properties)	Define várias propriedades no objeto ao mesmo tempo, com base num objeto carregado existente.
toJSON()	Substitui o método JavaScript `toJSON()` para fornecer uma saída mais útil quando um objeto de API é transmitido para `JSON.stringify()`. (`JSON.stringify`por sua vez, chama o `toJSON` método do objeto que lhe é transmitido.) Enquanto o objeto original `Excel.Range` é um objeto de API, o `toJSON` método devolve um objeto JavaScript simples (escrito como `Excel.Interfaces.RangeData`) que contém cópias rasas de quaisquer propriedades subordinadas carregadas do objeto original.
track()	Acompanha o objeto para ajuste automático com base nas alterações adjacentes no documento. Esta chamada é uma abreviatura de context.trackedObjects.add(thisObject). Se estiver a utilizar este objeto entre `.sync` chamadas e fora da execução sequencial de um lote ".run" e receber um erro "InvalidObjectPath" ao definir uma propriedade ou invocar um método no objeto, terá de adicionar o objeto à coleção de objetos controlados quando o objeto foi criado pela primeira vez.
unmerge()	Desfaz a mesclagem das células do intervalo em células separadas.
untrack()	Libere a memória associada a este objeto, se ele já tiver sido rastreado anteriormente. Esta chamada é abreviada para context.trackedObjects.remove(thisObject). Ter muitos objetos rastreados desacelera o aplicativo host, por isso, lembre-se de liberar todos os objetos adicionados após usá-los. Terá de chamar `context.sync()` antes de a libertação da memória ser aplicada.

Detalhes da propriedade

address

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").

readonly address: string;

Valor da propriedade

string

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

addressLocal

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

readonly addressLocal: string;

Valor da propriedade

string

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

cellCount

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

readonly cellCount: number;

Valor da propriedade

number

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

columnCount

Especifica o número total de colunas no intervalo.

readonly columnCount: number;

Valor da propriedade

number

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

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.

columnHidden: boolean;

Valor da propriedade

boolean

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

columnIndex

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

readonly columnIndex: number;

Valor da propriedade

number

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

context

O contexto do pedido associado ao objeto . Esta ação liga o processo do suplemento ao processo da aplicação anfitriã do Office.

context: RequestContext;

Valor da propriedade

Excel.RequestContext

format

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

readonly format: Excel.RangeFormat;

Valor da propriedade

Excel.RangeFormat

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

formulas

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

formulas: any[][];

Valor da propriedade

any[][]

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

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.

formulasLocal: any[][];

Valor da propriedade

any[][]

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

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.

formulasR1C1: any[][];

Valor da propriedade

any[][]

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

hidden

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.

readonly hidden: boolean;

Valor da propriedade

boolean

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

numberFormat

Representa o código de formato de número do Excel para o intervalo especificado. Para obter mais informações sobre a formatação de números do Excel, consulte Códigos de formato de número.

numberFormat: any[][];

Valor da propriedade

any[][]

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

// Set the text of the chart title to "My Chart" and display it as an overlay on the chart.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "F5:G7";
    const numberFormat = [[null, "d-mmm"], [null, "d-mmm"], [null, null]]
    const values = [["Today", 42147], ["Tomorrow", "5/24"], ["Difference in days", null]];
    const formulas = [[null,null], [null,null], [null,"=G6-G5"]];
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.numberFormat = numberFormat;
    range.values = values;
    range.formulas= formulas;
    range.load('text');
    await context.sync();
    
    console.log(range.text);
});

rowCount

Retorna o número total de linhas no intervalo.

readonly rowCount: number;

Valor da propriedade

number

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

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.

rowHidden: boolean;

Valor da propriedade

boolean

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

rowIndex

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

readonly rowIndex: number;

Valor da propriedade

number

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

sort

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

readonly sort: Excel.RangeSort;

Valor da propriedade

Excel.RangeSort

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/event-column-and-row-sort.yaml

async function sortTopToBottom(criteria: string) {
    await Excel.run(async (context) => {
        const sheet = context.workbook.worksheets.getActiveWorksheet();
        const range = sheet.getRange("A1:E5");

        // Find the column header that provides the sort criteria.
        const header = range.find(criteria, {});
        header.load("columnIndex");
        await context.sync();

        range.sort.apply(
            [
                {
                    key: header.columnIndex,
                    sortOn: Excel.SortOn.value
                }
            ],
            false /*matchCase*/,
            true /*hasHeaders*/,
            Excel.SortOrientation.rows
        );
        await context.sync();
    });
}

text

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.

readonly text: string[][];

Valor da propriedade

string[][]

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

values

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.

values: any[][];

Valor da propriedade

any[][]

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

valueTypes

Especifica o tipo de dados em cada célula.

readonly valueTypes: Excel.RangeValueType[][];

Valor da propriedade

Excel.RangeValueType[][]

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

worksheet

A planilha que contém o intervalo atual.

readonly worksheet: Excel.Worksheet;

Valor da propriedade

Excel.Worksheet

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Detalhes do método

clear(applyTo)

Limpar valores de intervalo e formatação, como preenchimento e limite.

clear(applyTo?: Excel.ClearApplyTo): void;

Parâmetros

applyTo: Excel.ClearApplyTo

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

Retornos

void

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

// Clear the format and contents of the range.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D:F";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.clear();
    await context.sync(); 
});

clear(applyToString)

Limpar valores de intervalo e formatação, como preenchimento e limite.

clear(applyToString?: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks"): void;

Parâmetros

applyToString: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks"

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

Retornos

void

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

delete(shift)

Exclui as células associadas ao intervalo.

delete(shift: Excel.DeleteShiftDirection): void;

Parâmetros

shift: Excel.DeleteShiftDirection

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

Retornos

void

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D:F";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.delete("Left");
    await context.sync(); 
});

delete(shiftString)

Exclui as células associadas ao intervalo.

delete(shiftString: "Up" | "Left"): void;

Parâmetros

shiftString: "Up" | "Left"

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

Retornos

void

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

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): Excel.Range;

Parâmetros

anotherRange: Excel.Range | string

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

Retornos

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D4:G6";
    let range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range = range.getBoundingRect("G4:H8");
    range.load('address');
    await context.sync();
    
    console.log(range.address); // Prints Sheet1!D4:H8
});

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): Excel.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

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const range = worksheet.getRange(rangeAddress);
    const cell = range.getCell(0,0);
    cell.load('address');
    await context.sync();
    
    console.log(cell.address);
});

getColumn(column)

Obtém uma coluna incluída no intervalo.

getColumn(column: number): Excel.Range;

Parâmetros

column: number

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

Retornos

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet19";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getColumn(1);
    range.load('address');
    await context.sync();

    console.log(range.address); // prints Sheet1!B1:B8
});

getColumnsAfter(count)

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

getColumnsAfter(count?: number): Excel.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

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

getColumnsBefore(count)

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

getColumnsBefore(count?: number): Excel.Range;

Parâmetros

count: number

Retornos

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

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(): Excel.Range;

Retornos

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

// Note: the grid properties of the Range (values, numberFormat, formulas) 
// contains null since the Range in question is unbounded.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D:F";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    const rangeEC = range.getEntireColumn();
    rangeEC.load('address');
    await context.sync();
    
    console.log(rangeEC.address);
});

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(): Excel.Range;

Retornos

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

// Gets an object that represents the entire row of the range 
// (for example, if the current range represents cells "B4:E11", 
// its GetEntireRow is a range that represents rows "4:11").
await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "D:F"; 
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    const rangeER = range.getEntireRow();
    rangeER.load('address');
    await context.sync();
    
    console.log(rangeER.address);
});

getIntersection(anotherRange)

Obtém o objeto de intervalo que representa a interseção retangular dos intervalos determinados.

getIntersection(anotherRange: Range | string): Excel.Range;

Parâmetros

anotherRange: Excel.Range | string

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

Retornos

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = 
        context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getIntersection("D4:G6");
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!D4:F6
});

getLastCell()

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

getLastCell(): Excel.Range;

Retornos

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastCell();
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!F8
});

getLastColumn()

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

getLastColumn(): Excel.Range;

Retornos

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastColumn();
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!F1:F8
});

getLastRow()

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

getLastRow(): Excel.Range;

Retornos

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastRow();
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!A8:F8
});

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): Excel.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

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D4:F6";
    const range = 
        context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getOffsetRange(-1,4);
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!H3:J5
});

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): Excel.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

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

getRow(row)

Obtém uma linha contida no intervalo.

getRow(row: number): Excel.Range;

Parâmetros

row: number

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

Retornos

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getRow(1);
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!A2:F2
});

getRowsAbove(count)

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

getRowsAbove(count?: number): Excel.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

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

getRowsBelow(count)

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

getRowsBelow(count?: number): Excel.Range;

Parâmetros

count: number

Retornos

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

getUsedRange(valuesOnly)

Retorna o intervalo usado do objeto de intervalo determinado. Se não existirem células utilizadas dentro do intervalo, esta função gerará um ItemNotFound erro.

getUsedRange(valuesOnly?: boolean): Excel.Range;

Parâmetros

valuesOnly: boolean

Considera apenas as células com valores como células usadas. [Conjunto de API: ExcelApi 1.2]

Retornos

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-relationships.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const salesTable = sheet.tables.getItem("SalesTable");
    const dataRange = salesTable.getDataBodyRange();

    // We want the most recent quarter that has data, so
    // exclude quarters without data and get the last of
    // the remaining columns.
    const usedDataRange = dataRange.getUsedRange(true /* valuesOnly */);
    const currentQuarterRange = usedDataRange.getLastColumn();

    // Asian and European teams have separate contests.
    const asianSalesRange = sheet.getRange("A2:E4");
    const europeanSalesRange = sheet.getRange("A5:E7");

    // The data for each chart is the intersection of the
    // current quarter column and the rows for the continent.
    const asianContestRange = asianSalesRange.getIntersectionOrNullObject(currentQuarterRange);
    const europeanContestRange = europeanSalesRange.getIntersectionOrNullObject(currentQuarterRange);

    // Must sync before you can test the output of *OrNullObject
    // method/property.
    await context.sync();

    if (asianContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("Asian");
    } else {
        createContinentChart(
            sheet,
            "Asian",
            asianContestRange,
            "A9",
            "F24"
        );
    }

    if (europeanContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("European");
    } else {
        createContinentChart(
            sheet,
            "European",
            europeanContestRange,
            "A25",
            "F40"
        );
    }

    await context.sync();
});

getVisibleView()

Representa as linhas visíveis do intervalo atual.

getVisibleView(): Excel.RangeView;

Retornos

Excel.RangeView

Comentários

[ Conjunto de API: ExcelApi 1.3 ]

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: Excel.InsertShiftDirection): Excel.Range;

Parâmetros

shift: Excel.InsertShiftDirection

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

Retornos

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "F5:F10";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.insert(Excel.InsertShiftDirection.down);
    await context.sync();
});

insert(shiftString)

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(shiftString: "Down" | "Right"): Excel.Range;

Parâmetros

shiftString: "Down" | "Right"

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

Retornos

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

load(options)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(options?: Excel.Interfaces.RangeLoadOptions): Excel.Range;

Parâmetros

options: Excel.Interfaces.RangeLoadOptions

Fornece opções para as propriedades do objeto a carregar.

Retornos

Excel.Range

load(propertyNames)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(propertyNames?: string | string[]): Excel.Range;

Parâmetros

propertyNames: string | string[]

Uma cadeia delimitada por vírgulas ou uma matriz de cadeias que especificam as propriedades a carregar.

Retornos

Excel.Range

Exemplos

// Use the range address to get the range object.
await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8"; 
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const range = worksheet.getRange(rangeAddress);
    range.load('cellCount');
    await context.sync();
    
    console.log(range.cellCount);
});

load(propertyNamesAndPaths)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Excel.Range;

Parâmetros

propertyNamesAndPaths: { select?: string; expand?: string; }

propertyNamesAndPaths.select é uma cadeia delimitada por vírgulas que especifica as propriedades a carregar e propertyNamesAndPaths.expand é uma cadeia delimitada por vírgulas que especifica as propriedades de navegação a carregar.

Retornos

Excel.Range

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

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:C3";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.merge(true);
    await context.sync(); 
});

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-merged-ranges.yaml

await Excel.run(async (context) => {
  // Retrieve the worksheet and the table in that worksheet.
  const sheet = context.workbook.worksheets.getActiveWorksheet();
  const tableRange = sheet.getRange("B2:E6");

  // Create a merged range in the first row of the table.
  const chartTitle = tableRange.getRow(0);
  chartTitle.merge(true);

  // Format the merged range.
  chartTitle.format.horizontalAlignment = "Center";

  await context.sync();
});

select()

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

select(): void;

Retornos

void

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "F5:F10"; 
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.select();
    await context.sync(); 
});

set(properties, options)

Define várias propriedades de um objeto ao mesmo tempo. Pode transmitir um objeto simples com as propriedades adequadas ou outro objeto de API do mesmo tipo.

set(properties: Interfaces.RangeUpdateData, options?: OfficeExtension.UpdateOptions): void;

Parâmetros

properties: Excel.Interfaces.RangeUpdateData

Um objeto JavaScript com propriedades que são estruturadas isomorfoticamente para as propriedades do objeto no qual o método é chamado.

options: OfficeExtension.UpdateOptions

Fornece uma opção para suprimir erros se o objeto de propriedades tentar definir quaisquer propriedades só de leitura.

Retornos

void

set(properties)

Define várias propriedades no objeto ao mesmo tempo, com base num objeto carregado existente.

set(properties: Excel.Range): void;

Parâmetros

properties: Excel.Range

Retornos

void

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/90-scenarios/multiple-property-set.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");

    const sourceRange = sheet.getRange("B2:E2");
    sourceRange.load("format/fill/color, format/font/name, format/font/color");
    await context.sync();

    // Set properties based on the loaded and synced 
    // source range.
    const targetRange = sheet.getRange("B7:E7");
    targetRange.set(sourceRange); 
    targetRange.format.autofitColumns();
    await context.sync();
});

toJSON()

Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é transmitido para JSON.stringify(). (JSON.stringifypor sua vez, chama o toJSON método do objeto que lhe é transmitido.) Enquanto o objeto original Excel.Range é um objeto de API, o toJSON método devolve um objeto JavaScript simples (escrito como Excel.Interfaces.RangeData) que contém cópias rasas de quaisquer propriedades subordinadas carregadas do objeto original.

toJSON(): Excel.Interfaces.RangeData;

Retornos

Excel.Interfaces.RangeData

track()

Acompanha o objeto para ajuste automático com base nas alterações adjacentes no documento. Esta chamada é uma abreviatura de context.trackedObjects.add(thisObject). Se estiver a utilizar este objeto entre .sync chamadas e fora da execução sequencial de um lote ".run" e receber um erro "InvalidObjectPath" ao definir uma propriedade ou invocar um método no objeto, terá de adicionar o objeto à coleção de objetos controlados quando o objeto foi criado pela primeira vez.

track(): Excel.Range;

Retornos

Excel.Range

unmerge()

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

unmerge(): void;

Retornos

void

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:C3";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.unmerge();
    await context.sync(); 
});

untrack()

Libere a memória associada a este objeto, se ele já tiver sido rastreado anteriormente. Esta chamada é abreviada para context.trackedObjects.remove(thisObject). Ter muitos objetos rastreados desacelera o aplicativo host, por isso, lembre-se de liberar todos os objetos adicionados após usá-los. Terá de chamar context.sync() antes de a libertação da memória ser aplicada.

untrack(): Excel.Range;

Retornos

Excel.Range

Exemplos

await Excel.run(async (context) => {
    const largeRange = context.workbook.getSelectedRange();
    largeRange.load(["rowCount", "columnCount"]);
    await context.sync();

    for (let i = 0; i < largeRange.rowCount; i++) {
        for (let j = 0; j < largeRange.columnCount; j++) {
            const cell = largeRange.getCell(i, j);
            cell.values = [[i *j]];

            // Call untrack() to release the range from memory.
            cell.untrack();
        }
    }

    await context.sync();
});

Compartilhar via

Excel.Range class

Comentários

Exemplos

Propriedades

Métodos

Detalhes da propriedade

address

Valor da propriedade

Comentários

addressLocal

Valor da propriedade

Comentários

cellCount

Valor da propriedade

Comentários

columnCount

Valor da propriedade

Comentários

columnHidden

Valor da propriedade

Comentários

columnIndex

Valor da propriedade

Comentários

context

Valor da propriedade

format

Valor da propriedade

Comentários

formulas

Valor da propriedade

Comentários

formulasLocal

Valor da propriedade

Comentários

formulasR1C1

Valor da propriedade

Comentários

hidden

Valor da propriedade

Comentários

numberFormat

Valor da propriedade

Comentários

Exemplos

rowCount

Valor da propriedade

Comentários

rowHidden

Valor da propriedade

Comentários

rowIndex

Valor da propriedade

Comentários

sort

Valor da propriedade

Comentários

Exemplos

text

Valor da propriedade

Comentários

values

Valor da propriedade

Comentários

valueTypes

Valor da propriedade

Comentários

worksheet

Valor da propriedade

Comentários

Detalhes do método

clear(applyTo)

Parâmetros

Retornos

Comentários

Exemplos

clear(applyToString)

Parâmetros

Retornos