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

A coleção dessa ConditionalFormats interseção a cordilheira.

readonly conditionalFormats: Excel.ConditionalFormatCollection;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.6

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

Acessa o controle de célula aplicado a esse intervalo. Se o intervalo tiver vários controles de célula, isso retornará EmptyCellControl.

control: CellControl;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.18

Exemplos

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

// Add checkboxes to the table.
await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getActiveWorksheet();

  // Get the second column in the table, without the header.
  const range = sheet.tables.getItem("FruitTable").columns.getItem("Analysis").getDataBodyRange();

  // Change the boolean values to checkboxes.
  range.control = {
    type: Excel.CellControlType.checkbox
  };
  await context.sync();
});

Retorna um objeto de validação de dados.

readonly dataValidation: Excel.DataValidation;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.8

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

Especifica a fórmula de matriz de um intervalo. Se o intervalo especificado não contiver uma fórmula de matriz, esta propriedade retornará null.

formulaArray: string;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApiDesktop 1.1

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

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 têm uma borda de despejo. Retorna true se todas as células tiverem uma borda de despejo ou false se todas as células não tiverem uma borda de despejo. Retorna null se houver células com e sem bordas de despejo dentro do intervalo.

readonly hasSpill: boolean;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.12

Retorna a distância em pontos, para um zoom de 100%, da borda superior do intervalo até a borda inferior do intervalo.

readonly height: number;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.10

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 hiperlink para o intervalo atual.

hyperlink: Excel.RangeHyperlink;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.7

Exemplos

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

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

    let productsRange = sheet.getRange("A3:A5");
    productsRange.load("values");

    await context.sync();

    // Create a hyperlink to a URL 
    // for each product name in the first table.
    for (let i = 0; i < productsRange.values.length; i++) {
        let cellRange = productsRange.getCell(i, 0);
        let cellText = productsRange.values[i][0];

        let hyperlink = {
            textToDisplay: cellText,
            screenTip: "Search Bing for '" + cellText + "'",
            address: "https://www.bing.com?q=" + cellText
        }
        cellRange.hyperlink = hyperlink;
    }

    await context.sync();
});

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

readonly isEntireColumn: boolean;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.7

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

readonly isEntireRow: boolean;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.7

Retorna a distância em pontos, para um zoom de 100%, da borda esquerda da planilha até a borda esquerda do intervalo.

readonly left: number;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.10

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

readonly linkedDataTypeState: Excel.LinkedDataTypeState[][];

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.9

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

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

readonly numberFormatCategories: Excel.NumberFormatCategory[][];

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.12

Representa o código de formato de número do Excel para determinado intervalo, com base nas configurações de idioma do usuário. O Excel não executa nenhuma coerção de idioma ou formato ao obter ou definir a numberFormatLocal propriedade. Qualquer texto retornado usa as cadeias de caracteres formatadas localmente com base no idioma especificado nas configurações do sistema.

numberFormatLocal: any[][];

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.7

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 se todas as células seriam salvas como uma fórmula de matriz. Retorna true se todas as células forem salvas como uma fórmula de matriz ou false se todas as células não forem salvas como uma fórmula de matriz. Retorna null se algumas células seriam salvas como uma fórmula de matriz e outras não.

readonly savedAsArray: boolean;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.12

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

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

style: string;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.7

Exemplos

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

await Excel.run(async (context) => {
    let worksheet = context.workbook.worksheets.getItem("Sample");
    let range = worksheet.getRange("A1:E1");

    // Apply built-in style. 
    // Styles are in the Home tab ribbon.
    range.style = Excel.BuiltInStyle.neutral;
    range.format.horizontalAlignment = "Right";

    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

Retorna a distância em pontos, para um zoom de 100%, da borda superior da planilha até a borda superior do intervalo.

readonly top: number;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.10

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

Uma representação JSON dos valores nas células desse intervalo. Ao contrário do Range.values, Range.valuesAsJson oferece suporte a todos os tipos de dados que podem estar em uma célula. Os exemplos incluem valores numéricos formatados e imagens da Web, além dos valores booleanos padrão, numéricos e de cadeia de caracteres. Os dados retornados dessa API sempre se alinham com a localidade en-US. Para recuperar dados na localidade de exibição do usuário, use Range.valuesAsJsonLocal.

valuesAsJson: CellValue[][];

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.16

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/20-data-types/data-types-formatted-number.yaml

// This function creates a double data type,
// and sets the format of this data type as a date.
await Excel.run(async (context) => {
  // Get the Sample worksheet and a range on that sheet.
  const sheet = context.workbook.worksheets.getItemOrNullObject("Sample");
  const dateRange = sheet.getRange("A1");

  // Write a number formatted as a date to cell A1.
  dateRange.valuesAsJson = [
    [
      {
        type: Excel.CellValueType.double,
        basicValue: 32889.0,
        numberFormat: "m/d/yyyy"
      }
    ]
  ];
  await context.sync();
});

Uma representação JSON dos valores nas células desse intervalo. Ao contrário do Range.values, Range.valuesAsJsonLocal oferece suporte a todos os tipos de dados que podem estar em uma célula. Os exemplos incluem valores numéricos formatados e imagens da Web, além dos valores booleanos padrão, numéricos e de cadeia de caracteres. Os dados retornados dessa API sempre se alinham com a localidade de exibição do usuário. Para recuperar dados independentes da localidade, use Range.valuesAsJson.

valuesAsJsonLocal: CellValue[][];

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.16

Especifica o tipo de dados em cada célula.

readonly valueTypes: Excel.RangeValueType[][];

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1

Retorna a distância em pontos, para um zoom de 100%, da borda esquerda do intervalo até a borda direita do intervalo.

readonly width: number;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.10

A planilha que contém o intervalo atual.

readonly worksheet: Excel.Worksheet;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1

Preenche um intervalo do intervalo atual para o intervalo de destino usando a lógica de AutoPreenchimento especificada. O intervalo de destino pode ser null ou pode estender o intervalo de origem horizontal ou verticalmente. Intervalos descontíguos não são suportados.

Para obter mais informações, consulte Usar o AutoPreenchimento e o Preenchimento Relâmpago.

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.9, ExcelApi Visualização para nulo destinationRange

Exemplos

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

await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getActiveWorksheet();
  const sumCell = sheet.getRange("P4");
  
  // Copy everything. The formulas will be contextually updated based on their new locations.
  sumCell.autoFill("P4:P7", Excel.AutoFillType.fillCopy);
  sumCell.format.autofitColumns();
  await context.sync();
});

Preenche um intervalo do intervalo atual para o intervalo de destino usando a lógica de AutoPreenchimento especificada. O intervalo de destino pode ser null ou pode estender o intervalo de origem horizontal ou verticalmente. Intervalos descontíguos não são suportados.

Para obter mais informações, consulte Usar o AutoPreenchimento e o Preenchimento Relâmpago.

autoFill(destinationRange?: Range | string, autoFillType?: "FillDefault" | "FillCopy" | "FillSeries" | "FillFormats" | "FillValues" | "FillDays" | "FillWeekdays" | "FillMonths" | "FillYears" | "LinearTrend" | "GrowthTrend" | "FlashFill"): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.9, ExcelApi Visualização para nulo destinationRange

Calcula um intervalo de células em uma planilha.

calculate(): void;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.6

Verifica a ortografia das palavras nesse intervalo. Esse método abre a caixa de diálogo Ortografia na interface do usuário do Excel.

checkSpelling(options?: Excel.CheckSpellingOptions): void;

Parâmetros

Retornos

Comentários

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

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

Limpa os valores das células no intervalo, com consideração especial dada às células que contêm controles. Se o intervalo contiver apenas valores em branco e controles definidos com seu valor padrão, os valores e a formatação de controle serão removidos. Caso contrário, isso definirá as células com controles para seu valor padrão e limpará os valores das outras células no intervalo.

clearOrResetContents(): void;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.18

Exemplos

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

// Remove all content from the Analysis column.
await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getActiveWorksheet();

  // Get the second column in the table, without the header.
  const range = sheet.tables.getItem("FruitTable").columns.getItem("Analysis").getDataBodyRange();

  // Clear all the data from the second column.
  range.clearOrResetContents();
  await context.sync();
});

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

convertDataTypeToText(): void;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.9

Converte as células do intervalo em tipos de dados vinculados na planilha.

convertToLinkedDataType(serviceID: number, languageCulture: string): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.9

Copia os dados da célula ou a 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 será expandido automaticamente se for menor que a origem. Observação: Como a funcionalidade de cópia na interface do usuário do Excel, se o intervalo de destino for um múltiplo exato maior que o intervalo de origem em linhas ou colunas, o conteúdo de origem será 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?: Excel.RangeCopyType, skipBlanks?: boolean, transpose?: boolean): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.9

Exemplos

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    // Place a label in front of the copied data.
    sheet.getRange("F2").values = [["Copied Formula"]];

    // Copy a range preserving the formulas.
    // Note: non-formula values are copied over as is.
    sheet.getRange("G2").copyFrom("A1:E1", Excel.RangeCopyType.formulas);
    await context.sync();
});

Copia os dados da célula ou a 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 será expandido automaticamente se for menor que a origem. Observação: Como a funcionalidade de cópia na interface do usuário do Excel, se o intervalo de destino for um múltiplo exato maior que o intervalo de origem em linhas ou colunas, o conteúdo de origem será 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?: "All" | "Formulas" | "Values" | "Formats" | "Link" | "ColumnWidths", skipBlanks?: boolean, transpose?: boolean): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.9

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

Exclui as células associadas ao intervalo.

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.1

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 planilha que começa após essa célula.

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

Parâmetros

Retornos

O Range objeto que representa a primeira célula que contém um valor que corresponda ao texto e aos critérios de pesquisa.

Comentários

Conjunto de APIs: ExcelApi 1.9

Exemplos

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

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

    // NOTE: If no match is found, an ItemNotFound error
    // is thrown when Range.find is evaluated.
    const searchText = (document.getElementById("searchText") as HTMLTextAreaElement).value;
    const foundRange = searchRange.find(searchText, {
        completeMatch: isCompleteMatchToggle,
        matchCase: isMatchCaseToggle,
        searchDirection: searchDirectionToggle
    });
    
    foundRange.load("address");
    await context.sync();

    console.log(foundRange.address);
});

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 planilha que começa após essa célula. Se não houver correspondências, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte métodos e propriedades *OrNullObject.

findOrNullObject(text: string, criteria: Excel.SearchCriteria): Excel.Range;

Parâmetros

Retornos

O Range que correspondeu aos critérios de pesquisa.

Comentários

Conjunto de APIs: ExcelApi 1.9

Exemplos

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const table = sheet.tables.getItem("ExpensesTable");
    const searchRange = table.getRange();
    const searchText = (document.getElementById("searchText") as HTMLTextAreaElement).value;
    const foundRange = searchRange.findOrNullObject(searchText, {
        completeMatch: isCompleteMatchToggle,
        matchCase: isMatchCaseToggle,
        searchDirection: searchDirectionToggle
    });
    
    foundRange.load("address");
    await context.sync();

    if (foundRange.isNullObject) {
        console.log("Text not found");
    } else {
        console.log(foundRange.address);
    }
});

Faz um preenchimento relâmpago para o intervalo atual. O Preenchimento Relâmpago preenche automaticamente os dados quando detecta um padrão, portanto, o intervalo deve ser um intervalo de uma única coluna e ter dados ao seu redor para encontrar um padrão.

flashFill(): void;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.9

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

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.7

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

Retorna uma matriz 2D encapsulando os dados de fonte, preenchimento, bordas, alinhamento e outras propriedades de cada célula.

getCellProperties(cellPropertiesLoadOptions: CellPropertiesLoadOptions): OfficeExtension.ClientResult<CellProperties[][]>;

Parâmetros

Retornos

Uma matriz 2D em que cada item representa as propriedades solicitadas da célula correspondente.

Comentários

Conjunto de APIs: ExcelApi 1.9

Exemplos

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

await Excel.run(async (context) => {
    const cell = context.workbook.getActiveCell();

    // Get only the properties requested in this load-options object.
    const propertiesToGet: Excel.CellPropertiesLoadOptions = {
        address: true,
        format: {
            fill: {
                color: true
            },
            font: {
                bold: true,
                color: true
            }
        },
        style: true
    };
    const cellProperties = cell.getCellProperties(propertiesToGet);

    await context.sync();
    const activeCellProperties: Excel.CellProperties = cellProperties.value[0][0];
    console.log(JSON.stringify(activeCellProperties, null, 2));
});

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

Retorna uma única matriz dimensional encapsulando os dados de fonte, preenchimento, bordas, alinhamento e outras propriedades de cada coluna. Para propriedades que não são consistentes nas células de uma determinada coluna, será retornado null.

getColumnProperties(columnPropertiesLoadOptions: ColumnPropertiesLoadOptions): OfficeExtension.ClientResult<ColumnProperties[]>;

Parâmetros

Retornos

Uma matriz em que cada item representa as propriedades solicitadas da coluna correspondente.

Comentários

Conjunto de APIs: ExcelApi 1.9

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

Retorna um WorkbookRangeAreas objeto que representa o intervalo que contém todas as células dependentes de um intervalo especificado na mesma planilha ou em várias planilhas. Gera um ItemNotFound erro se nenhum dependente for encontrado.

getDependents(): Excel.WorkbookRangeAreas;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.15

Exemplos

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

/** Highlight all dependents (direct and indirect) of the active cell. */
async function getAllDependents() {
  await Excel.run(async (context) => {
    // Get addresses of all dependent cells of the active cell.
    const range = context.workbook.getActiveCell();
    const dependents = range.getDependents();
    range.load("address");
    dependents.areas.load("address");
    await context.sync();

    console.log(`All dependent cells of ${range.address} (orange cells):`);

    for (let i = 0; i < dependents.areas.items.length; i++) {
      // Highlight and print the address of each dependent cell.
      dependents.areas.items[i].format.fill.color = "Orange";
      console.log(`  ${dependents.areas.items[i].address}`);
    }
    await context.sync();
  });

Retorna um WorkbookRangeAreas objeto que representa o intervalo que contém todas as células dependentes diretas de um intervalo especificado na mesma planilha ou em várias planilhas. Gera um ItemNotFound erro se nenhum dependente for encontrado.

getDirectDependents(): Excel.WorkbookRangeAreas;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.13

Exemplos

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

/** Highlight the direct dependents of the active cell. */
async function getDirectDependents() {
  await Excel.run(async (context) => {
    // Direct dependents are cells that contain formulas that directly refer to the active cell.
    let range = context.workbook.getActiveCell();
    let directDependents = range.getDirectDependents();
    range.load("address");
    directDependents.areas.load("address");
    await context.sync();

    console.log(`Direct dependent cells of ${range.address} (yellow cells):`);

    for (let i = 0; i < directDependents.areas.items.length; i++) {
      // Highlight and print the address of each direct dependent cell.
      directDependents.areas.items[i].format.fill.color = "Yellow";
      console.log(`  ${directDependents.areas.items[i].address}`);
    }
    await context.sync();
  });

Retorna um WorkbookRangeAreas objeto que representa o intervalo que contém todas as células de precedente direta de um intervalo especificado na mesma planilha ou em várias planilhas. Gera um ItemNotFound erro se nenhum precedente for encontrado.

getDirectPrecedents(): Excel.WorkbookRangeAreas;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.12

Exemplos

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

/** Highlight the direct precedents of the active cell. */
async function getDirectPrecedents() {
  await Excel.run(async (context) => {
    // Precedents are cells referenced by the formula in a cell.
    // A "direct precedent" is a cell directly referenced by the selected formula.
    let range = context.workbook.getActiveCell();
    let directPrecedents = range.getDirectPrecedents();
    range.load("address");
    directPrecedents.areas.load("address");
    await context.sync();

    console.log(`Direct precedent cells of ${range.address} (yellow cells):`);

    for (let i = 0; i < directPrecedents.areas.items.length; i++) {
      // Highlight and print the address of each direct precedent cell.
      directPrecedents.areas.items[i].format.fill.color = "Yellow";
      console.log(`  ${directPrecedents.areas.items[i].address}`);
    }
    await context.sync();
  });

Retorna uma matriz 2D, encapsulando os dados de exibição para a fonte, o preenchimento, as bordas, o alinhamento e outras propriedades de cada célula. Ao contrário getCellPropertiesde , que mostra apenas propriedades definidas diretamente para a célula, isso retorna propriedades que são exibidas de fontes indiretas, como formatação condicional ou estilos.

getDisplayedCellProperties(cellPropertiesLoadOptions: CellPropertiesLoadOptions): OfficeExtension.ClientResult<CellProperties[][]>;

Parâmetros

Retornos

Uma matriz 2D em que cada item representa as propriedades de exibição solicitadas da célula correspondente.

Comentários

Conjunto de APIs: ExcelApi 1.19

Exemplos

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const cell = sheet.getRange("D3");
    const propertiesToGet: Excel.CellPropertiesLoadOptions = {
        address: true,
        format: {
            fill: {
                color: true
            },
            font: {
                bold: true,
                color: true
            },
        },
        style: true
    };

    // Direct properties exclude formatting inherited from styles or conditional formatting.
    const directProperties = cell.getCellProperties(propertiesToGet);
    // Displayed properties include formatting inherited from styles or conditional formatting.
    const displayedProperties = cell.getDisplayedCellProperties(propertiesToGet);

    await context.sync();

    console.log("Direct properties:");
    console.log(JSON.stringify(directProperties.value[0][0], null, 2));
    console.log("Displayed properties (including conditional formatting):");
    console.log(JSON.stringify(displayedProperties.value[0][0], null, 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);
});

Retorna um objeto de intervalo que inclui o intervalo atual e até a borda do intervalo, com base na direção fornecida. Isso corresponde ao comportamento da tecla Ctrl+Shift+Direção na interface do usuário do Excel no Windows.

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.13

Exemplos

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

await Excel.run(async (context) => {
  // Get the selected range.
  const range = context.workbook.getSelectedRange();

  // Specify the direction with the `KeyboardDirection` enum.
  const direction = Excel.KeyboardDirection.down;

  // Get the active cell in the workbook.
  const activeCell = context.workbook.getActiveCell();

  // Get all the cells from the currently selected range to the bottom-most edge of the used range.
  // This method acts like the Ctrl+Shift+Arrow key keyboard shortcut while a range is selected.
  const extendedRange = range.getExtendedRange(
    direction,
    activeCell // If the selected range contains more than one cell, the active cell must be defined.
  );
  extendedRange.select();

  await context.sync();
});

Retorna um objeto de intervalo que inclui o intervalo atual e até a borda do intervalo, com base na direção fornecida. Isso corresponde ao comportamento da tecla Ctrl+Shift+Direção na interface do usuário do Excel no Windows.

getExtendedRange(direction: "Left" | "Right" | "Up" | "Down", activeCell?: Range | string): Excel.Range;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.13

Renderiza o intervalo como uma imagem PNG codificada em Base64.

getImage(): OfficeExtension.ClientResult<string>;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.7

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 o objeto de intervalo que representa a interseção retangular dos intervalos determinados. Se nenhuma interseção for encontrada, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte métodos e propriedades *OrNullObject.

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.4

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

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

Retorna um RangeAreas objeto que representa as áreas mescladas nesse intervalo. Observe que, se a contagem de áreas mescladas nesse intervalo for maior que 512, esse método não retornará o resultado. Se o RangeAreas objeto não existir, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte métodos e propriedades *OrNullObject.

getMergedAreasOrNullObject(): Excel.RangeAreas;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.13

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

  // Retrieve the merged range within the table and load its details.
  const mergedAreas = tableRange.getMergedAreasOrNullObject();
  mergedAreas.load("address");
  mergedAreas.load("cellCount");

  // Select the merged range.
  const range = mergedAreas.areas.getItemAt(0);
  range.select();
  await context.sync();

  // Print out the details of the `mergedAreas` range object.
  console.log(`Address of the merged range: ${mergedAreas.address}`);
  console.log(`Number of cells in the merged range: ${mergedAreas.cellCount}`);

  await context.sync();
});

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 uma coleção com escopo de Tabelas Dinâmicas que se sobrepõem ao intervalo.

getPivotTables(fullyContained?: boolean): Excel.PivotTableScopedCollection;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.12

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/38-pivottable/pivottable-get-pivottables.yaml

await Excel.run(async (context) => {
  const activeRange = context.workbook.getSelectedRange();

  // Get all the PivotTables that intersect with this range.
  const partiallyContainedPivotTables = activeRange.getPivotTables();
  // Get all the PivotTables that are completely contained within this range.
  const fullyContainedPivotTables = activeRange.getPivotTables(true);

  partiallyContainedPivotTables.load("name");
  fullyContainedPivotTables.load("name");
  await context.sync();

  // Display the names in the console.
  console.log("PivotTables in the current range:")
  partiallyContainedPivotTables.items.forEach((pivotTable) => {
    console.log(`\t${pivotTable.name}`);
  });
  console.log("PivotTables completely contained in the current range:")
  fullyContainedPivotTables.items.forEach((pivotTable) => {
    console.log(`\t${pivotTable.name}`);
  });
});

Retorna um WorkbookRangeAreas objeto que representa o intervalo que contém todas as células precedentes de um intervalo especificado na mesma planilha ou em várias planilhas. Gera um ItemNotFound erro se nenhum precedente for encontrado.

getPrecedents(): Excel.WorkbookRangeAreas;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.14

Exemplos

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

/** Highlight all precedents (direct and indirect) of the active cell. */
async function getAllPrecedents() {
  await Excel.run(async (context) => {
    // Precedents are cells referenced by the formula in a cell.
    let range = context.workbook.getActiveCell();
    let precedents = range.getPrecedents();
    range.load("address");
    precedents.areas.load("address");
    await context.sync();

    console.log(`All precedent cells of ${range.address} (orange cells):`);

    for (let i = 0; i < precedents.areas.items.length; i++) {
      // Highlight and print the address of each precedent cell.
      precedents.areas.items[i].format.fill.color = "Orange";
      console.log(`  ${precedents.areas.items[i].address}`);
    }
    await context.sync();
  });

Retorna um objeto de intervalo que é a célula de borda da região de dados que corresponde à direção fornecida. Isso corresponde ao comportamento da tecla Ctrl+Direção na interface do usuário do Excel no Windows.

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.13

Exemplos

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

await Excel.run(async (context) => {
  // Get the selected range.
  const range = context.workbook.getSelectedRange();

  // Specify the direction with the `KeyboardDirection` enum.
  const direction = Excel.KeyboardDirection.up;

  // Get the active cell in the workbook.
  const activeCell = context.workbook.getActiveCell();

  // Get the top-most cell of the current used range.
  // This method acts like the Ctrl+Arrow key keyboard shortcut while a range is selected.
  const rangeEdge = range.getRangeEdge(
    direction,
    activeCell // If the selected range contains more than one cell, the active cell must be defined.
  );
  rangeEdge.select();

  await context.sync();
});

Retorna um objeto de intervalo que é a célula de borda da região de dados que corresponde à direção fornecida. Isso corresponde ao comportamento da tecla Ctrl+Direção na interface do usuário do Excel no Windows.

getRangeEdge(direction: "Left" | "Right" | "Up" | "Down", activeCell?: Range | string): Excel.Range;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.13

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

Retorna uma única matriz dimensional encapsulando os dados de fonte, preenchimento, bordas, alinhamento e outras propriedades de cada célula. Para propriedades que não são consistentes em cada célula dentro de uma determinada linha, null serão retornados.

getRowProperties(rowPropertiesLoadOptions: RowPropertiesLoadOptions): OfficeExtension.ClientResult<RowProperties[]>;

Parâmetros

Retornos

Uma matriz em que cada item representa as propriedades solicitadas da linha correspondente.

Comentários

Conjunto de APIs: ExcelApi 1.9

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

Obtém o RangeAreas objeto, compreendendo um ou mais intervalos retangulares, que representa todas as células que correspondem ao tipo e valor especificados. Se nenhuma célula especial for encontrada, um ItemNotFound erro será gerado.

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.9

Exemplos

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

await Excel.run(async (context) => {

    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const usedRange = sheet.getUsedRange();

    // Find the ranges with either text or logical (boolean) values.
    const formulaRanges = usedRange.getSpecialCells("Constants", "LogicalText");
    formulaRanges.format.fill.color = "orange";

    return context.sync();
});

Obtém o RangeAreas objeto, compreendendo um ou mais intervalos retangulares, que representa todas as células que correspondem ao tipo e valor especificados. Se nenhuma célula especial for encontrada, um ItemNotFound erro será gerado.

getSpecialCells(cellType: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible" | "DirtyFormulas", cellValueType?: "All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"): Excel.RangeAreas;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.9

Obtém o RangeAreas objeto, compreendendo um ou mais intervalos, que representa todas as células que correspondem ao tipo e valor especificados. Se nenhuma célula especial for encontrada, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte métodos e propriedades *OrNullObject.

getSpecialCellsOrNullObject(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.9

Obtém o RangeAreas objeto, compreendendo um ou mais intervalos, que representa todas as células que correspondem ao tipo e valor especificados. Se nenhuma célula especial for encontrada, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte métodos e propriedades *OrNullObject.

getSpecialCellsOrNullObject(cellType: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible" | "DirtyFormulas", cellValueType?: "All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"): Excel.RangeAreas;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.9

Obtém objeto range que contém o intervalo de despejo quando chamado em uma célula âncora. Falha se aplicado a um intervalo com mais de uma célula.

getSpillingToRange(): Excel.Range;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.12

Exemplos

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

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

  // Set G4 to a formula that returns a dynamic array.
  const targetCell = sheet.getRange("G4");
  targetCell.formulas = [["=A4:D4"]];

  // Get the address of the cells that the dynamic array spilled into.
  const spillRange = targetCell.getSpillingToRange();
  spillRange.load("address");

  // Fit the columns for readability.
  sheet.getUsedRange().format.autofitColumns();
  await context.sync();

  console.log(`Copying the table headers spilled into ${spillRange.address}.`);
});

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 âncora ou o intervalo de derramamento não puder ser encontrado, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte métodos e propriedades *OrNullObject.

getSpillingToRangeOrNullObject(): Excel.Range;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.12

Obtém o objeto range que contém a célula âncora para uma célula que recebe o despejo. Falha se aplicado a um intervalo com mais de uma célula.

getSpillParent(): Excel.Range;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.12

Obtém o objeto de intervalo que contém a célula âncora da célula que está sendo despejada. Se não for uma célula despejada ou mais de uma célula for fornecida, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte métodos e propriedades *OrNullObject.

getSpillParentOrNullObject(): Excel.Range;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.12

Retorna um Range objeto que representa a região ao redor da célula superior esquerda nesse 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(): Excel.Range;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.7

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

getTables(fullyContained?: boolean): Excel.TableScopedCollection;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.9

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

Retorna o intervalo usado do objeto de intervalo determinado. Se não houver células usadas no intervalo, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte métodos e propriedades *OrNullObject.

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.4

Exemplos

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

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

    // Pass true so only cells with values count as used
    const usedDataRange = dataRange.getUsedRangeOrNullObject(
        true /* valuesOnly */
    );

    //Must sync before reading value returned from *OrNullObject method/property.
    await context.sync();

    if (usedDataRange.isNullObject) {
        console.log("Need Data to Make Chart");
        console.log("To create a meaningful chart, press 'Fill the table' (or add names to the Product column and numbers to some of the other cells). Then press 'Try to create chart' again.");
    } else {
        const chart = sheet.charts.add(
            Excel.ChartType.columnClustered,
            dataRange,
            "Columns"
        );
        chart.setPosition("A15", "F30");
        chart.title.text = "Quarterly sales chart";
        chart.legend.position = "Right";
        chart.legend.format.fill.setSolidColor("white");
        chart.dataLabels.format.font.size = 15;
        chart.dataLabels.format.font.color = "black";
    }

    await context.sync();
});

Representa as linhas visíveis do intervalo atual.

getVisibleView(): Excel.RangeView;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.3

Agrupa colunas e linhas para obter uma estrutura de tópicos.

group(groupOption: Excel.GroupOption): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.10

Exemplos

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

Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    
    // Group the larger, main level. Note that the outline controls
    // will be on row 10, meaning 4-9 will collapse and expand.
    sheet.getRange("4:9").group(Excel.GroupOption.byRows);

    // Group the smaller, sublevels. Note that the outline controls
    // will be on rows 6 and 9, meaning 4-5 and 7-8 will collapse and expand.
    sheet.getRange("4:5").group(Excel.GroupOption.byRows);
    sheet.getRange("7:8").group(Excel.GroupOption.byRows);
    await context.sync();
});

Agrupa colunas e linhas para obter uma estrutura de tópicos.

group(groupOption: "ByRows" | "ByColumns"): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.10

Oculta os detalhes do grupo de linha ou coluna.

hideGroupDetails(groupOption: Excel.GroupOption): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.10

Oculta os detalhes do grupo de linha ou coluna.

hideGroupDetails(groupOption: "ByRows" | "ByColumns"): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.10

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

Move valores de célula, 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 que o intervalo atual. As células no intervalo de destino que estão fora da área do intervalo original não são alteradas. Observação: quando um intervalo é movido para um novo endereço usando essa API, o novo objeto de intervalo deve ser recuperado usando o novo endereço.

moveTo(destinationRange: Range | string): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.11

Exemplos

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    // Place a label in front of the moved data.
    sheet.getRange("F12").values = [["Moved Range:"]];

    // Move the range from A1:E1 to G12:K12.
    sheet.getRange("A1:E1").moveTo("G12");
    await context.sync();
});

Remove valores duplicados do intervalo especificado pelas colunas.

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

Parâmetros

Retornos

O objeto resultante que contém o número de linhas removidas e o número de linhas exclusivas restantes.

Comentários

Conjunto de APIs: ExcelApi 1.9

Exemplos

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

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

    const deleteResult = range.removeDuplicates([0],true);    
    deleteResult.load();    
    await context.sync();

    console.log(deleteResult.removed + " entries with duplicate names removed.");
    console.log(deleteResult.uniqueRemaining + " entries with unique names remain in the range.");
});

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

replaceAll(text: string, replacement: string, criteria: Excel.ReplaceCriteria): OfficeExtension.ClientResult<number>;

Parâmetros

Retornos

O número de substituições realizadas.

Comentários

Conjunto de APIs: ExcelApi 1.9

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

Atualizações o intervalo com base em uma matriz 2D de propriedades de célula, encapsulando itens como fonte, preenchimento, bordas e alinhamento.

setCellProperties(cellPropertiesData: SettableCellProperties[][]): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.9

Exemplos

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

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

    // Create the SettableCellProperties objects for the range.
    // Create these objects once, outside the function, in your add-in.
    const topHeaderProps: Excel.SettableCellProperties = {
        // Set the style property to the name of an Excel style.
        // The `BuiltInStyle` enum lists the built-in style names.
        // A style overwrites formatting, so don't use style and format in the same object.
        style: Excel.BuiltInStyle.heading1
    };

    const headerProps: Excel.SettableCellProperties = {
        // Setting these cell properties doesn't change unspecified format subproperties.
        format: {
            fill: {
                color: "Blue"
            },
            font: {
                color: "White",
                bold: true
            }
        }
    };

    const nonApplicableProps: Excel.SettableCellProperties = {
        format: {
            fill: {
                pattern: Excel.FillPattern.gray25
            },
            font: {
                color: "Gray",
                italic: true
            }
        }
    };

    const matchupScoreProps: Excel.SettableCellProperties = {
        format: {
            borders: {
                bottom: {
                    style: Excel.BorderLineStyle.continuous
                },
                left: {
                    style: Excel.BorderLineStyle.continuous
                },
                right: {
                    style: Excel.BorderLineStyle.continuous
                },
                top: {
                    style: Excel.BorderLineStyle.continuous
                }
            },
            horizontalAlignment: Excel.HorizontalAlignment.center
        }
    };

    const range = sheet.getRange("A1:E5");

    // Use empty JSON objects to leave a cell's properties unchanged.
    range.setCellProperties([
        [topHeaderProps, {}, {}, {}, {}],
        [{}, {}, headerProps, headerProps, headerProps],
        [{}, headerProps, nonApplicableProps, matchupScoreProps, matchupScoreProps],
        [{}, headerProps, matchupScoreProps, nonApplicableProps, matchupScoreProps],
        [{}, headerProps, matchupScoreProps, matchupScoreProps, nonApplicableProps]
    ]);

    sheet.getUsedRange().format.autofitColumns();
    await context.sync();
});

Atualizações o intervalo com base em uma matriz unidimensional de propriedades de coluna, encapsulando itens como fonte, preenchimento, bordas e alinhamento.

setColumnProperties(columnPropertiesData: SettableColumnProperties[]): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.9

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

setDirty(): void;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.9

Atualizações o intervalo com base em uma matriz unidimensional de propriedades de linha, encapsulando itens como fonte, preenchimento, bordas e alinhamento.

setRowProperties(rowPropertiesData: SettableRowProperties[]): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.9

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

showCard(): void;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.7

Desenha setas rastreadoras para os dependentes diretos do intervalo.

showDependents(remove?: boolean): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApiDesktop 1.1

Mostra os detalhes do grupo de linhas ou colunas.

showGroupDetails(groupOption: Excel.GroupOption): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.10

Mostra os detalhes do grupo de linhas ou colunas.

showGroupDetails(groupOption: "ByRows" | "ByColumns"): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.10

Desenha setas rastreadoras para os precedentes diretos do intervalo.

showPrecedents(remove?: boolean): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApiDesktop 1.1

Define o modo de empacotamento da fórmula do Python no Excel =PY.

togglePythonMarshalMode(marshalMode?: Excel.PythonMarshalMode): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi BETA (SOMENTE VISUALIZAÇÃO)

Define o modo de empacotamento da fórmula do Python no Excel =PY.

togglePythonMarshalMode(marshalMode?: "PythonObject" | "ExcelValue"): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi BETA (SOMENTE VISUALIZAÇÃO)

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

Desagrupa colunas e linhas para criar uma estrutura de tópicos.

ungroup(groupOption: Excel.GroupOption): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.10

Exemplos

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

Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    
    // This removes two levels of groups from the "A1-R10" range.
    // Any groups at the same level on the same dimension will be removed by a single call.
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byRows);
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byRows);
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byColumns);
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byColumns);
    await context.sync();
});

Desagrupa colunas e linhas para criar uma estrutura de tópicos.

ungroup(groupOption: "ByRows" | "ByColumns"): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.10

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