Excel.Range class

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

readonly address: string;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1

Representa a referência de intervalo para o intervalo especificado no idioma do usuário.

readonly addressLocal: string;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1

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

Comentários

Conjunto de APIs: ExcelApi 1.1

Especifica o número total de colunas no intervalo.

readonly columnCount: number;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1

Representa se todas as colunas no intervalo atual estão ocultas. Valor é true quando todas as colunas em um intervalo estão ocultas. Valor é false quando nenhuma coluna no intervalo está oculta. Valor é null quando algumas colunas em um intervalo estão ocultas e outras colunas no mesmo intervalo não estão ocultas.

columnHidden: boolean;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.2

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

readonly columnIndex: number;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1

O contexto de solicitação associado ao objeto. Isso conecta o processo do suplemento ao processo do aplicativo host do Office.

context: RequestContext;

Valor da propriedade

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

Comentários

Conjunto de APIs: ExcelApi 1.1

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/46-table/formatting.yaml

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

    expensesTable.getHeaderRowRange().format.fill.color = "#C70039";
    expensesTable.getDataBodyRange().format.fill.color = "#DAF7A6";
    expensesTable.rows.getItemAt(1).getRange().format.fill.color = "#FFC300";
    expensesTable.columns.getItemAt(0).getDataBodyRange().format.fill.color = "#FFA07A";
    
  await context.sync();
});

Representa a fórmula em notação A1. Se uma célula não tiver fórmula, seu valor será retornado em vez disso.

formulas: any[][];

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1

Exemplos

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

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

    const data = [
        ["Total Price"],
        ["=C3 * D3"],
        ["=C4 * D4"],
        ["=C5 * D5"],
        ["=SUM(E3:E5)"]
    ];
    
    const range = sheet.getRange("E2:E6");
    range.formulas = data;
    range.format.autofitColumns();

    await context.sync();
});

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 fórmula, seu valor será retornado em vez disso.

formulasLocal: any[][];

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1

Representa a fórmula em notação no estilo L1C1. Se uma célula não tiver fórmula, seu valor será retornado em vez disso.

formulasR1C1: any[][];

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.2

Representa se todas as células no intervalo atual estão ocultas. Valor é true quando todas as células em um intervalo estão ocultas. Valor é false quando nenhuma célula do intervalo está oculta. O valor é null quando algumas células de um intervalo estão ocultas e outras células do mesmo intervalo não estão ocultas.

readonly hidden: boolean;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.2

Representa o código de formato de número do Excel para determinado intervalo. 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

Comentários

Conjunto de APIs: 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);
});

Retorna o número total de linhas no intervalo.

readonly rowCount: number;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1

Representa se todas as linhas no intervalo atual estão ocultas. O valor é true quando todas as linhas em um intervalo estão ocultas. O valor é false quando nenhuma linha no intervalo está oculta. O valor é null quando algumas linhas em um intervalo estão ocultas e outras linhas no mesmo intervalo não estão ocultas.

rowHidden: boolean;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.2

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

readonly rowIndex: number;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1

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

readonly sort: Excel.RangeSort;

Valor da propriedade

Comentários

Conjunto de APIs: 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();
    });
}

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 interface do usuário do Excel não afetará o valor de texto retornado pela API.

readonly text: string[][];

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1

Representa os valores brutos do intervalo especificado. Os dados retornados podem ser uma cadeia de caracteres, um número ou um booleano. Células que contêm um erro retornarão a cadeia de caracteres de erro. Se o valor retornado começar com um sinal de mais ("+"), sinal de subtração ("-") ou sinal de igual ("="), o Excel interpretará esse valor como uma fórmula. Cadeias de caracteres em forma de localidade (como a data "19-8-2025" em nl-NL ou fr-FR, formato DD-MM-AAAA) são armazenadas como texto em vez de datas. Para garantir que as datas sejam armazenadas como datas, use uma API com reconhecimento de localidade como formulasLocal ou use um formato neutro de localidade como ISO (AAAA-MM-DD) ou uma data numérica serial.

values: any[][];

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1

Exemplos

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

// Change the value of the checkbox in B3.
await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getActiveWorksheet();
  const range = sheet.getRange("B3");

  range.values = [["TRUE"]];
  await context.sync();
});

Especifica o tipo de dados em cada célula.

readonly valueTypes: Excel.RangeValueType[][];

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1

A planilha que contém o intervalo atual.

readonly worksheet: Excel.Worksheet;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1

Limpe os valores e a formatação do intervalo, como preenchimento e borda.

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: 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(); 
});

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range: Excel.Range = sheet.getRange("E2:E5");

    range.clear();

    await context.sync();
});

Limpe os valores e a formatação do intervalo, como preenchimento e borda.

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.1

Exclui as células associadas ao intervalo.

delete(shift: Excel.DeleteShiftDirection): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: 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(); 
});

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-worksheet.yaml

// This function deletes data from a range and sets the delete shift direction to "up".
await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range: Excel.Range = sheet.getRange("A5:F5");
    range.delete(Excel.DeleteShiftDirection.up);
});

Exclui as células associadas ao intervalo.

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.1

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

Retornos

Comentários

Conjunto de APIs: 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
});

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 de seu intervalo pai, desde que permaneça dentro da grade da planilha. A localização da célula retornada está relacionada à célula superior esquerda do intervalo.

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: 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);
});

Obtém uma coluna incluída no intervalo.

getColumn(column: number): Excel.Range;

Parâmetros

Retornos

Comentários

Conjunto de APIs: 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
});

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

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.2

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

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.2

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

getEntireColumn(): Excel.Range;

Retornos

Comentários

Conjunto de APIs: 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);
});

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

getEntireRow(): Excel.Range;

Retornos

Comentários

Conjunto de APIs: 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);
});

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

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: 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
});

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

getLastCell(): Excel.Range;

Retornos

Comentários

Conjunto de APIs: 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
});

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

getLastColumn(): Excel.Range;

Retornos

Comentários

Conjunto de APIs: 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
});

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

getLastRow(): Excel.Range;

Retornos

Comentários

Conjunto de APIs: 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
});

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

Retornos

Comentários

Conjunto de APIs: 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
});

Obtém um Range objeto semelhante ao objeto atual Range , mas com seu canto inferior direito expandido (ou contraído) por um certo número de linhas e colunas.

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.2

Obtém uma linha contida no intervalo.

getRow(row: number): Excel.Range;

Parâmetros

Retornos

Comentários

Conjunto de APIs: 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
});

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

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.2

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

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.2

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

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: 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();
});

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. Retorna um novo Range objeto com espaço em branco.

insert(shift: Excel.InsertShiftDirection): Excel.Range;

Parâmetros

Retornos

Comentários

Conjunto de APIs: 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();
});

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. Retorna um novo Range objeto com espaço em branco.

insert(shift: "Down" | "Right"): Excel.Range;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.1

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

Retornos

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

Retornos

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

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

Retornos

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

merge(across?: boolean): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.2

Exemplos

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

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

select(): void;

Retornos

Comentários

Conjunto de APIs: 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(); 
});

Define várias propriedades de um objeto ao mesmo tempo. Você pode passar um objeto simples com as propriedades apropriadas ou outro objeto de API do mesmo tipo.

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

Parâmetros

Retornos

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

set(properties: Excel.Range): void;

Parâmetros

Retornos

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

Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é passado para JSON.stringify(). (JSON.stringify, por sua vez, chama o toJSON método do objeto que é passado para ele.) Enquanto o objeto original Excel.Range é um objeto de API, o toJSON método retorna um objeto JavaScript simples (digitado como Excel.Interfaces.RangeData) que contém cópias superficiais de todas as propriedades filho carregadas do objeto original.

toJSON(): Excel.Interfaces.RangeData;

Retornos

Acompanha o objeto para ajuste automático com base nas alterações adjacentes no documento. Essa chamada é uma abreviação de context.trackedObjects.add(thisObject). Se você estiver usando esse 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, precisará adicionar o objeto à coleção de objetos rastreados quando o objeto foi criado pela primeira vez.

track(): Excel.Range;

Retornos

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

unmerge(): void;

Retornos

Comentários

Conjunto de APIs: 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(); 
});

Libere a memória associada a este objeto, se ele já tiver sido rastreado anteriormente. Essa chamada é a forma abreviada de 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. Você precisará ligar context.sync() antes que a liberação de memória entre em vigor.

untrack(): Excel.Range;

Retornos

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